Developers

API reference

Callable's programmable surface for developers: embed the chat widget, receive webhook events, and open an agent's hosted chat page. Everything else — building and configuring agents — is done in the dashboard.

Note: There is no public REST API for managing agents/campaigns programmatically yet. If you need that, email [email protected] to talk about API access. The interfaces below are stable and available today.

Add a floating chat launcher to any website with a single script tag. It loads widget.js, pulls the agent's public appearance, and opens the agent's chat page in an iframe.

<!-- Callable chat widget -->
<script
  src="https://callableio.com/widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-position="bottom-right"
  async
></script>

Attributes

data-agent-id — the id of the chat agent to embed. Required (unless you use data-team-id).
data-team-id — embed an agent team instead of a single agent; each message is routed to the right member. Use this OR data-agent-id.
data-position — launcher position: bottom-right (default) or bottom-left.

The button color and label come from the agent's public appearance (set in the dashboard), so you don't configure look-and-feel in the snippet. The widget has no external dependencies and runs on any site.

Hosted chat pages

Every chat agent has a hosted page you can link to directly instead of embedding:

Agent: https://callableio.com/chat/YOUR_AGENT_ID
Agent team: https://callableio.com/chat/team/YOUR_TEAM_ID

Webhooks

Get notified in your own systems when calls and chats happen. Configure webhooks per agent (in the agent builder): set a delivery URL, an optional signing secret, and toggle which events you want.

Events

Two events are delivered today, both on by default:

call.ended — a phone call finished. Use this for post-call processing (status, transcript, recording).
chat.message — a message was exchanged in a web chat session.

The agent's webhook settings also list toggles for call.started, chat.started, chat.ended, tool.invoked, and extraction.completed. These are being rolled out — only the two events above are guaranteed to fire right now, so build against those.

Delivery

Callable POSTs a JSON body to your URL containing the event name and the conversation's context (the agent, the phone number or session, and timestamps; where available, links to the transcript/recording). Deliveries are signed with your webhook secret so you can verify they came from Callable, and requests are SSRF-guarded. Respond with a 2xx status to acknowledge — non-2xx responses are treated as failures.

Tip: Verify the signature on every webhook before trusting the payload, and return 200 quickly — do heavy work asynchronously so deliveries don't time out.

Tools & MCP

Agents can call your systems during a conversation through Tools (function calling) and MCP servers, rather than you polling an API afterward. See Tools & function calling.

Next steps

← Embed & webhooks

FAQ & troubleshooting →