Authentication
- Create a workspace API key in Settings → API keys with the Talk to demo agents scope (
agents:converse). API keys are a Team plan feature. - Send it as
Authorization: Bearer ak_…. A key without the scope gets403 insufficient_scope. - Keys are server secrets. Never put them in a browser or mobile app.
- Each key may make 120 requests a minute. The widget’s per-conversation limits apply on top.
- Owners and admins can see each request’s route, status and latency for 30 days under Settings → Request log. The request log does not store request or response bodies.
Endpoints
Base URLhttps://api.arcdemo.io/api/v1. The agent ID is on the agent’s Channels → API page.
Start a conversation
For a first server-side request, setARCD_AGENT_ID and ARCD_API_KEY in your environment, then send JSON:
201 and a conversationId to use for the next request.
The request below is illustrative. Replace the agent ID and example values. Supply consent and terms fields only when they reflect the visitor’s actual choices, and provide any fields required by the agent’s published configuration.
- Send the lead fields, consent and terms your widget asks for. Missing ones fail with the widget’s message (for example
Email is required.). visitor.idkeeps a visitor on one branch of a traffic split.visitor.ipis the visitor’s address; the per-IP limit of 10 new conversations an hour applies to it (otherwise to your server’s IP).dynamicVariablesfill the agent’s{{variables}}, with the same limits as the widget.languagepicks the reply language. It must be one of the agent’s languages (its default plus its Additional languages on the Agent page); anything else fails with400. Leave it out to use the agent’s default.overrideschange one conversation, and only the fields the agent allows under Settings → Security → Overrides:firstMessage(one line, up to 500 characters, shown as written),language(one of the agent’s languages),voiceId(the agent’s voice or one listed there) andworkflowStartNodeId(a Subagent or Say step of the published workflow). The system prompt and other instructions can never be overridden. A field that isn’t allowed, isn’t valid, or isn’t overridable fails the start with400and names it, for exampleoverrides refused: systemPrompt:not_overridable. Applied overrides are stored on the conversation.- Use a new
idempotencyKeyfor each new conversation and keep it stable across retries. Retrying with the same key returns the same conversation.
override_first_message, override_language, override_voice and override_start_node. They apply only when the agent has an embed allowlist, so no other site can restyle your agent; fields that aren’t allowed are dropped. The floating launcher (arcdemo.js) forwards the same parameters from data-arcdemo-override-language (and -first-message, -voice, -start-node) on its script tag, or from arcdemo.agent.init({ agent, overrides: { language, firstMessage } }).
Send a message
SetARCD_CONVERSATION_ID to the returned ID and set ARCD_MESSAGE_ID to a newly generated UUID for this message. Persist and reuse that UUID if you retry the same message; generate a different one for the next message.
- Reusing a
messageIdreturns the stored reply without asking the agent again. - For a live stream send
Accept: text/event-streamor"stream": truein the request body. Ifstreamis supplied, it takes precedence over theAcceptheader. You get the widget’s Server-Sent Events:event: eventframes whosedatais JSON with atypesuch astext_delta,sources,content_surfaced,suggested_actions,escalation,errorandmessage_done. Lines starting with:are keep-alives. Ignore types you don’t use: new ones can be added. With the widget’s Action indicator on, you also gettool_statusframes (id,statusrunning or done, and a shortlabelsuch as “Checking availability…”) that never contain tool names or data, and never change the reply text. - One message per conversation at a time; up to 4,000 characters.
- Only conversations started through the API or a Custom Channel accept messages.
End, read
POST …/end closes the conversation and runs the summary, analysis and triggers (as when a visitor closes the widget). GET …/{conversationId} returns the status, lead, transcript, summary, engagement score and the analysis (criteria results, data points, sentiment, topics) once it has run. It works for any conversation of the agent.
Errors
The following is a schematic response, not a literal JSON example.Custom Channel
On the agent’s Channels → Custom Channel page, create the channel to get a webhook URL and a signing secret (shown once). Your system POSTs each user message; ArcDemo answers inline or, when a callback URL is set, answers202 and POSTs the reply there.
- The timestamp is Unix time in seconds. Requests more than 5 minutes off the current time are rejected; generate a fresh timestamp and signature for each request.
conversationIdis your own thread id. Messages with the same id continue one ArcDemo conversation; after it ends (or after 24 hours) the next message starts a new one.visitorand the other start fields are read on the first message.messageIdmakes retries safe: the same id returns the same reply. If a callback was lost, send the message again with the same id.- Callbacks carry the same envelope, signed the same way with the channel secret, plus
X-ArcDemo-Event: message.reply. Callback URLs must be public https. - A callback that fails (network error or a non-2xx answer) is retried with backoff, so treat
messageIdas your dedupe key. If every attempt fails, the Custom Channel page shows why.