Integrating the Voice Agent

Interactive Documentation

The platform provides two interactive API explorers auto-generated from the live OpenAPI schema. Use them to inspect every parameter, verify JSON schemas, and test endpoints directly from your browser:

System Overview

The Voice Agent platform provides a unified interface for conversational speech. Instead of stitching together separate speech-to-text, LLM, and speech-synthesis APIs, your application communicates with a single endpoint that manages the real-time audio loop, phrase streaming, and instant barge-in interruption.

Developers typically interact with the system in three ways:

• Real-Time Streaming WebSocket (/ws): For interactive web applications, mobile apps, or audio devices where users speak continuously and listen to immediate replies.
• Knowledge Base Endpoints (/api/v1/knowledge): To programmatically teach the voice agent your company's facts, product descriptions, pricing, and operational rules.
• Telephony & Phone Calls (/api/v1/telephony): To make automated outbound phone calls and handle inbound customer calls over standard carrier networks via Africa's Talking.

Authentication & API Keys

Every inbound request to the Voice Agent platform is authenticated using a secure API Key. Your API key identifies your tenant account and attributes usage quotas, minutes, and billing.

HTTP REST Authentication

Pass your API key in the X-API-Key header or standard Authorization: Bearer <key> header:

curl -X POST https://voiceagent.coetara.com/api/v1/chat \
  -H "X-API-Key: va_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, how can I buy tickets?"}'

WebSocket Audio Stream Authentication

When connecting to the live voice streaming WebSocket, supply your API key as a query parameter or via the X-API-Key handshake header:

const socket = new WebSocket('wss://voiceagent.coetara.com/ws?api_key=va_live_your_api_key_here');

Teaching the Agent (Knowledge Base)

You can programmatically teach the voice agent facts, event schedules, pricing tables, or custom instructions. Anything stored in the Knowledge Base is automatically and immediately incorporated into the agent's memory during live calls and chat turns.

curl -X POST https://voiceagent.coetara.com/api/v1/knowledge \
  -H "Content-Type: application/json" \
  -d '{
    "title": "VIP Ticket Access",
    "content": "VIP tickets include fast-track entry, complimentary drinks at the lounge, and backstage access after 9 PM.",
    "tags": ["tickets", "vip", "pricing"]
  }'

curl https://voiceagent.coetara.com/api/v1/knowledge

You can also query specific knowledge items by ID, update them with PUT /api/v1/knowledge/{id}, or erase them with DELETE /api/v1/knowledge/{id}.

Telephony Integration (Africa's Talking)

The platform natively supports carrier telephone calls across Africa via Africa's Talking Voice. You can trigger automated outbound phone calls or configure an inbound phone number to act as an automated voice agent.

Triggering an Outbound Phone Call

curl -X POST https://voiceagent.coetara.com/api/v1/telephony/call \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "initial_message": "Hello, this is Tickethub calling to confirm your event booking."
  }'

Handling Inbound & Outbound Call Webhooks

Set your Africa's Talking Voice Callback URL to:

When a call connects, the platform handles the conversation turn loop, processes the caller's spoken response, queries the grounded Knowledge Base, and responds with dynamic Voice XML.

Real-Time Streaming WebSocket

For custom browser interfaces or mobile applications, connect directly to the streaming audio WebSocket at wss://voiceagent.coetara.com/ws.

Audio Format Specification

Lifecycle & Interruption Events

The server streams binary audio chunks alongside JSON control events:

• {"event": "ready"} — Microphone audio stream is initialized and ready.
• {"event": "transcript_final", "text": "..."} — Recognized caller transcript.
• {"event": "clear_audio"} — Barge-In Interruption: Sent immediately when user speech is detected while the bot is speaking. Your client must immediately stop playing queued audio.
• {"event": "tts_finished"} — Bot finished speaking the current turn.

REST Conversational Endpoints

If you prefer standard HTTP requests rather than persistent WebSockets:

curl -X POST https://voiceagent.coetara.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "text": "What are your refund policies?",
    "voice": "female-shaonv",
    "return_audio": true
  }'