Artifacts
Artifacts are rich content objects embedded in chat messages. Learn how the WebSocket delivers them JIT and how to parse and render artifacts like doctor profiles and custom data structures.
What are artifacts?
Artifacts are structured data objects that provide additional context or information beyond plain text messages. Common examples include:
- Doctor profiles: Healthcare provider information with NPI, specialty, ratings, etc.
- Provider search results: Lists of providers from search queries with locations and distances
- Structured data: Custom data objects specific to your use case
- Rich content: Any JSON-serializable object
How artifacts are delivered
Artifacts are not fetched via REST API. The WebSocket backend expands artifact tags just-in-time (JIT) during streaming. When the AI references an artifact, the backend replaces the tag with the full artifact JSON and embeds it directly in message.text.
You receive artifact content inline—no separate fetch is needed. The message text contains embedded JSON objects with item_type, item_content, and created_at.
Parsing embedded artifacts
Parse message.text for JSON objects with item_type and item_content:
Artifact structure
The inline JSON format embedded in message text:
Doctor profile artifacts
Doctor profiles are a common artifact type:
Parsing doctor profiles from message text
Provider search results artifacts
The provider_search_results artifact type contains search results from the provider search tool:
Parsing provider search results
Rendering artifacts
The createSunnyChat widget automatically parses and renders doctor profiles and provider search results from message text:
Doctor profiles and provider search results are automatically rendered when embedded in messages.
Embedded artifact format
Message text contains JSON blobs—no {art_tag} tags are visible to the client. The backend expands {art_tag}uuid{/art_tag} server-side before streaming. What you receive looks like:
Error handling
Malformed JSON
When parsing, handle invalid JSON gracefully:
Best practices
- Parse defensively: Wrap JSON.parse in try/catch; skip invalid objects
- Type safety: Use TypeScript assertions or guards for
item_contentbyitem_type - Fallback UI: Provide fallback when an artifact fails to parse
- No loading states: Artifacts arrive with the message—no fetch loading needed
Next steps
- Key Concepts - Understand events, state management, and MCP approvals
- Authentication - Set up authenticated sessions
- API Reference - WebSocket schemas and artifact type definitions