Ciao integrations

Ciao connects to your phone carrier, your contact lists, your website, and your own systems. Setup happens in the Ciao console, and your software uses the public API to start calls and chats and to read results.

Native integrations

Ciao connects directly to the following:

• Phone carriers: Bring your own Twilio or Plivo account. Connect it on the Telephony page, add your numbers, and assign each number to an assistant. Your carrier bills you directly for the phone line.
• Contacts: Import contacts from a spreadsheet and organize them into contact groups for batch calls and campaigns.
• Web widget: Add a chat and voice bubble to your website with one script tag. Your server creates a short-lived session token for each visitor, so your API key never reaches the page.
• Browser calls: Build your own call button. Your server requests a short-lived grant, and the visitor talks to your assistant with their microphone.

Developer and API

Anything your software needs to start a call or chat and read the result goes through the public API. The API never creates or changes assistants, phone numbers, knowledge bases, voices, plans, or API keys. Those stay in the console.

• Base URL: https://api-ciao.worksbuddy.ai/api/v1/public
• API keys: In the console, go to Developer → API Keys and create a key. Choose an expiry (never, 30, 60, or 90 days, or a custom number of days) and optionally restrict the key to up to five server IP addresses. The secret is shown once and cannot be recovered.
• Authentication: Send the key on every request as Authorization: Bearer <key>. An X-API-Key: <key> header is also accepted. Your organization comes from the key, so call the API only from your server.
• Calls: Phone one number with POST /outbound-calls or a list with POST /outbound-calls/batch. Send an Idempotency-Key header so a retry never dials twice.
• Browser calls: POST /browser-calls returns a short-lived grant your web page uses to open a voice call.
• Chats: Start a chat with POST /chats, send messages, and end it to get a summary. A chat closes after 15 minutes without a message.
• Transcripts: Read a call's transcript after it ends, or follow it live as server-sent events.
• Assistants: List your assistants and read the inputs each one needs. Assistants are read only through the API.
• Web widget: Read and update the widget settings, and create a session token for each visitor.
• Testing: There is no sandbox. API calls are real calls and use your plan or credits, so test with your own number first.

Webhooks

Send a webhook_url with a call or batch to receive the result. Without one, the result is still saved in the console.

• Call result: call.completed arrives once per call when the conversation ends, with the status, outcome, summary, transcript, collected answers, and recording status. An unanswered call sends no call result.
• Status updates: Ask for any of call.initiated, call.ringing, call.answered, and call.failed with webhook_events. They carry no conversation content. Subscribe to call.failed to hear about busy and unanswered calls.
• Verify every delivery: Compute an HMAC-SHA256 of the raw request body with your webhook_secret and compare it with the X-WorksBuddy-Signature header. Route on X-WorksBuddy-Event, and skip duplicates using X-WorksBuddy-Idempotency-Key plus the event name.
• Delivery rules: Your endpoint must use HTTPS on a public address and reply within 5 seconds. Each delivery is tried up to 3 times and may arrive more than once or out of order. There is no replay after the last attempt.
• Plan: On a plan without webhook delivery, calls still run and results are still saved in the console.