Skip to main content
Talk to a published demo agent from your own backend, or connect a helpdesk, chat tool or bot through a signed webhook. Conversations run through the same pipeline as the website widget: the published version, lead form, consent and terms, guardrails, knowledge, tools, workflow, branches, limits and usage. They appear in Conversations with their summary and analysis. Text only.

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 gets 403 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 URL https://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, set ARCD_AGENT_ID and ARCD_API_KEY in your environment, then send JSON:
The empty body works only when the agent’s published configuration does not require additional lead, consent, or terms fields. Keep the key on your server; do not expose it in browser code. A successful response has status 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.id keeps a visitor on one branch of a traffic split. visitor.ip is the visitor’s address; the per-IP limit of 10 new conversations an hour applies to it (otherwise to your server’s IP).
  • dynamicVariables fill the agent’s {{variables}}, with the same limits as the widget.
  • language picks 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 with 400. Leave it out to use the agent’s default.
  • overrides change 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) and workflowStartNodeId (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 with 400 and names it, for example overrides refused: systemPrompt:not_overridable. Applied overrides are stored on the conversation.
  • Use a new idempotencyKey for each new conversation and keep it stable across retries. Retrying with the same key returns the same conversation.
The widget takes the same overrides as URL parameters on the agent page or iframe: 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

Set ARCD_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.
The following response is schematic; the alternatives and ellipses describe possible values rather than literal JSON.
  • Reusing a messageId returns the stored reply without asking the agent again.
  • For a live stream send Accept: text/event-stream or "stream": true in the request body. If stream is supplied, it takes precedence over the Accept header. You get the widget’s Server-Sent Events: event: event frames whose data is JSON with a type such as text_delta, sources, content_surfaced, suggested_actions, escalation, error and message_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 get tool_status frames (id, status running or done, and a short label such 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, answers 202 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.
  • conversationId is 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. visitor and the other start fields are read on the first message.
  • messageId makes 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 messageId as your dedupe key. If every attempt fails, the Custom Channel page shows why.