Copilot
The Copilot block is a complete, embeddable AI-assistant experience — a full chat surface backed by an AI agent (or a human Live Chat inbox) with streaming responses, a message composer, conversation history, citations, a chain-of-thought drawer, an optional side canvas for previewing documents and interfaces, and built-in voice mode with microphone, camera, screenshare, and live transcription.
It is a composite block: it arrives as an assembled set of child blocks — header, welcome, input panel, suggestions, message footer and actions, follow-up prompts, and a floating video avatar — that you can restyle in place. It exposes the whole conversation as bindable state plus a large set of methods so the rest of your interface can drive it.
Tip: When to use Copilot: Embed a full AI assistant into an interface — pick the AI Agent variant, choose an agent, and get streaming answers, citations, thoughts, suggestions, and follow-up prompts. For human conversations (agent-to-customer, group, inbound support), switch to Live Chat. For a plain human messaging widget with no AI framing, use the Chat block. For composable pieces only — just the input box, a single response, a thread — use the individual copilot blocks.
Properties
Content — Core
| Property | Type | Default | Description |
variant | "AI_AGENT" | "LIVE_CHAT" | AI_AGENT | AI assistant or human conversation surface. |
aiAgentId | agent id (bindable) | First available agent | The AI agent that answers messages. Appears when variant = AI_AGENT. |
conversationType | "INBOUND" | "OUTBOUND" | "GROUP" | INBOUND | Nature of the human conversation. Appears when variant = LIVE_CHAT. |
initialChatId | string (bindable) | — | Resume a specific chat session. If unset, a new chat is created. |
runtimeContext | string / JSON (bindable) | — | Context passed to the AI agent when a new chat is created. |
drawerContainerId | block reference | — | Stack or Container used as the mount point for the chain-of-thought and citations drawer. |
enableProfileMessages | boolean | false | When on, all of the user's chats are visible in the chat list. |
Voice Mode Parameters
| Property | Type | Default | Description |
separateVoiceMode | boolean | true | Voice mode opens in a dedicated view (on) vs. staying in context with the conversation (off). AI Agent only. |
fetchInitialMessagesOnConnect | boolean | false | Load all existing messages into the voice transcript on connect. |
enableVideo | boolean | false | Allow camera and agent video tracks during voice mode. |
enableScreenshare | boolean | false | Allow screenshare controls during voice mode. |
Add-Ons
| Add-on | Available on | What it adds |
| Message Timestamp | Both variants | Shows a timestamp on each message. |
| Agent Avatar | Both variants | Thinking / idle avatar imagery for the agent. |
| Conversation Starters | Both variants | Seed prompts shown at the start of a chat. |
| Mentions | Both variants | @-mentions — agents (AI Agent) or users (Live Chat). |
| Response Actions | AI Agent | Per-response actions such as copy / good / bad feedback. |
| Reply To Message | Live Chat | Reply-to-message threading. |
| Pin Messages | Live Chat | Pin / unpin messages. |
| Reference | Both variants | A context pill above the composer. |
Composable Slots
| Slot | Region |
| Header | Top bar of the chat. |
| Welcome | Empty-state welcome area. |
| Copilot Input | The message composer panel. |
| Suggestions | Suggested prompts. |
| Message Footer / Message Actions | Below-message chrome and per-message actions. |
| Follow Up Prompts | Follow-up chips after a response. |
| Video Avatar | Floating agent-video overlay during voice mode. |
Appearance
| Property | Type | Default | Description |
messageVariant | "DEFAULT" | "BUBBLE" | DEFAULT | Message bubble styling. AI Agent only. |
thoughtsVariant | "overlay" | "inline" | "loader" | "plainText" | overlay | How the agent's thinking is displayed. |
Events
| Event | Trigger |
On Message Sent | User submits a message in the composer. |
On Response Received | The AI agent's response has fully streamed in. |
On Open Copilot Canvas | The copilot's canvas surface opens. |
On Close Copilot Canvas | The copilot's canvas surface closes. |
On Voice Mode Connect | A voice session connects successfully. |
On Voice Mode Connect Error | Connecting to a voice session fails. |
On Citation Click | User clicks a citation chip in a response. |
Methods
| Method | Params | Effect |
Send Message | message | Sends a chat message to the AI agent programmatically. |
Create New Chat | — | Starts a fresh chat session. |
Go to Chat | chatId | Switches to an existing chat session. |
Set Copilot mode | mode | Switches between text and voice mode. |
Toggle voice mode microphone | state | Mutes or unmutes the user's microphone. |
Toggle voice mode camera | state | Turns the user's camera on or off. |
Start / Stop Screen Share | — | Starts or stops the active screen share. |
Scroll to Message | messageId | Scrolls the transcript to a specific message. |
Change Agent Observability | isAgentObserving | Turns the agent's screen-watching on or off. |
Interrupt Agent | — | Cuts off the agent while it is speaking or responding. |
Exposed State
| State key | Type | Description |
{{ id.chatId }} | string | The active chat session's identifier. |
{{ id.isGeneratingResponse }} | boolean | True while the agent is streaming a response. |
{{ id.voiceMode.isVoiceModeActive }} | boolean | Whether a voice session is running. |
{{ id.voiceMode.isMicrophoneEnabled }} | boolean | Whether the user's microphone is live. |
{{ id.voiceMode.isCameraEnabled }} | boolean | Whether the user's camera is on. |
{{ id.voiceMode.agentState }} | string | The agent's connection/speaking state. |
Behavior & Gotchas
Note: Conversation context only applies to brand-new chats. The value in Chat Context is handed to the agent when a new chat is created. Resuming via Chat Key does not re-send it.
Note: The composite slots are restylable, not replaceable arbitrarily. Each slot holds the block subtree for that region. You can restyle the child blocks inside a slot but cannot swap one slot's entire composition for a completely different block type without understanding the parent's expectations.
Headless Copilot
The Headless Copilot block is an AI copilot engine with no built-in chat window — you design the interface yourself. It connects your app to an AI agent, manages the chat session and a real-time voice mode (microphone, camera, screen share, live transcription), and exposes everything through slots, methods and state so your own blocks act as the copilot's face.
Tip: When to use Headless Copilot: Build a fully custom copilot experience — your own message list, input, avatars and voice controls. Drive an AI agent purely from events and methods (e.g. a voice-only assistant with no visible chat). If you want a ready-made chat interface, use the standard Copilot block instead.
Properties
Content
| Property | Type | Default | Description |
aiAgentId | string (bindable) | First available agent | The AI agent that powers the copilot. |
initialChatId | string (bindable) | — | The unique identifier used to resume a specific chat session. |
runtimeContext | string (bindable) | — | Context handed to the AI agent when a new chat is created. |
fetchInitialMessagesOnConnect | boolean | false | Load all existing messages into the voice transcript on connect. |
enableVideo | boolean | true | Enables the user's local camera sharing in voice mode. |
enableScreenshare | boolean | true | Enables the user's local screen-share controls in voice mode. |
Custom Voice Session
Enable Custom Voice Session to provide voice session credentials manually instead of having them managed automatically — for joining existing rooms with other people or agents.
| Property | Type | Description |
customRoomConnectionUrl | string | Address of the voice service to connect to. |
customRoomConnectionToken | string | Credential used to authenticate and join the session. |
customRoomId | string | Room identifier for the direct voice connection. |
Slots
| Slot | Description |
| Body | The main canvas for your custom copilot UI. |
| Voice Mode Actions | Holds voice controls; arrives pre-filled with working mic, camera, screenshare, and voice-mode toggles. |
Methods
| Method | Params | Effect |
Send Message | message | Sends a chat message to the AI agent. |
Create New Chat | — | Starts a fresh chat session. |
Go to Chat | chatId | Switches to an existing chat session. |
Set Copilot mode | mode | Switches between text and voice mode. |
Toggle voice mode microphone | state | Mutes or unmutes the user's microphone. |
Toggle voice mode camera | state | Turns the user's camera on or off. |
Start Screen Share | — | Starts sharing the user's screen. |
Stop Screen Share | — | Stops the active screen share. |
Change Agent Observability | isAgentObserving | Turns the agent's screen-watching on or off. |
Interrupt Agent | — | Cuts off the agent while it is speaking or responding. |
Exposed State
| State key | Type | Description |
{{ id.chatId }} | string | The active chat session's identifier. |
{{ id.voiceMode.isVoiceModeActive }} | boolean | Whether a voice session is running. |
{{ id.voiceMode.isMicrophoneEnabled }} | boolean | Whether the user's microphone is live. |
{{ id.voiceMode.isCameraEnabled }} | boolean | Whether the user's camera is on. |
{{ id.voiceMode.isScreenSharingEnabled }} | boolean | Whether a screen share is active. |
{{ id.voiceMode.agentState }} | string | The agent's connection/speaking state. |
{{ id.voiceMode.availableDevices }} | object | Detected microphones, speakers and cameras. |
Behavior & Gotchas
Warning: Send Message fails without an agent, but a blank message passes silently. No AI agent selected = the action fails. An empty or whitespace message is silently skipped but the action still reports success — chained actions run as if the message went through.
Warning: Long-running agent responses stop updating after 30 minutes. The block polls for the agent's response for up to 30 minutes. A response still pending after that stops updating in your UI.
Note: Voice transcripts start empty unless you turn on chat history. Turn on Show full chat history to load the existing conversation into the transcript on connect.
Examples
Related Blocks
| Block | Relationship |
| Copilot Chat | The transcript component embedded inside Copilot. |
| Copilot Input | The standalone message composer for custom compositions. |
| Copilot Voice | The voice engine block for fully custom voice UI. |
| Copilot History | Lists past conversations to jump back into. |
| Simple Agent Builder | Embeds the AI agent editor for in-app agent management. |
Frequently Asked Questions
When should I use a Copilot block versus a Headless Copilot?
Use the standard Copilot block when the built-in chat UI works for your use case — it gives you a complete chat interface including message list, input field, and optional voice mode with minimal setup. Use Headless Copilot when you need full control over every element of the UI — for example, a custom-styled chat widget, a non-standard conversation layout, or embedding the AI engine inside an existing page without the default chrome. Headless exposes the same methods and state but renders nothing itself; you build the UI in the Body and Voice Mode Actions slots.
How do I pass context about the current user or record to the AI agent?
Bind the Chat Context (runtimeContext) property to any expression — a page variable, a data source output, or a computed value. For example, {{ ds_caseRecord.output }} passes the current case details to the agent whenever a new chat is created. The agent receives this as context at conversation start. Changing runtimeContext after a chat has started does not retroactively update the existing conversation.
Can the Copilot block resume a previous conversation instead of always starting fresh?
Yes. Bind the Chat Key (initialChatId) property to a stable identifier for the conversation — for example a case ID or user ID. When the user returns, the block opens that conversation thread instead of starting new. Without a Chat Key, every page load starts a fresh conversation. You can also call the Go to Chat method to switch to a specific conversation programmatically.
What is the AI Agent variant versus the Live Chat variant?
The AI Agent variant connects to an AI agent you configure in the Agent Builder — it handles the conversation autonomously using tools and knowledge you define. The Live Chat variant is for human-to-human chat routed through a support or messaging system. The variant drives which backend handles messages and which features (like voice mode and AI tools) are available.
Is voice mode available in Headless Copilot?
Yes. Headless Copilot supports voice mode through the Voice Mode Actions slot, where you build your own voice controls. The same voice-related methods available in the standard Copilot block (Start Voice Mode, End Voice Mode, Toggle Microphone Mute, etc.) are callable from your custom slot UI. Voice mode parameters (provider, agent ID, API key) are configured via the voiceModeParams property.