API Reference

Returns all agents belonging to the authenticated user's organization, ordered by creation date.

Response

[
  {
    "id": "clx1a2b3c4d5e6f7g8h9i0j",
    "name": "Customer Support Agent",
    "type": "inbound",
    "language": "en",
    "voiceId": "aura-athena-en",
    "twilioPhoneNumber": "+14155551234",
    "enableRecording": true,
    "enableHandoff": true,
    "skills": ["billing", "technical-support"],
    "createdAt": "2026-01-15T08:30:00.000Z",
    "updatedAt": "2026-02-01T14:22:00.000Z"
  }
]

Create a new AI agent with the specified configuration.

Request Body

Example Request

{
  "name": "Sales Agent",
  "type": "inbound",
  "systemPrompt": "You are a friendly sales representative for Acme Corp...",
  "greetingMessage": "Hi! Thanks for calling Acme Corp. How can I help you today?",
  "language": "en",
  "voiceId": "aura-athena-en",
  "twilioPhoneNumber": "+14155551234",
  "enableRecording": true,
  "enableHandoff": true,
  "skills": ["sales", "product-info"]
}

Response

{
  "id": "clx1a2b3c4d5e6f7g8h9i0j",
  "name": "Sales Agent",
  "type": "inbound",
  "systemPrompt": "You are a friendly sales representative for Acme Corp...",
  "greetingMessage": "Hi! Thanks for calling Acme Corp. How can I help you today?",
  "language": "en",
  "voiceId": "aura-athena-en",
  "twilioPhoneNumber": "+14155551234",
  "enableRecording": true,
  "enableHandoff": true,
  "skills": ["sales", "product-info"],
  "organizationId": "org_abc123",
  "createdAt": "2026-02-07T10:00:00.000Z",
  "updatedAt": "2026-02-07T10:00:00.000Z"
}

Retrieve full details for a specific agent including configuration, knowledge bases, and metrics.

Response

{
  "id": "clx1a2b3c4d5e6f7g8h9i0j",
  "name": "Customer Support Agent",
  "type": "inbound",
  "systemPrompt": "You are a helpful customer support agent...",
  "greetingMessage": "Hello! How can I assist you today?",
  "language": "en",
  "voiceId": "aura-athena-en",
  "twilioPhoneNumber": "+14155551234",
  "enableRecording": true,
  "enableHandoff": true,
  "skills": ["billing", "technical-support"],
  "widgetConfig": null,
  "templateId": null,
  "organizationId": "org_abc123",
  "createdAt": "2026-01-15T08:30:00.000Z",
  "updatedAt": "2026-02-01T14:22:00.000Z"
}

Update an existing agent's configuration. Accepts the same fields as the create endpoint. Only provided fields are updated.

Example Request

{
  "name": "Updated Support Agent",
  "enableRecording": false,
  "skills": ["billing", "technical-support", "returns"]
}

Permanently delete an agent and all associated data. This action cannot be undone.

Returns all knowledge bases for the organization.

Response

[
  {
    "id": "kb_01hx9z3abc",
    "name": "Product Documentation",
    "description": "Complete product docs and FAQ",
    "documentCount": 24,
    "createdAt": "2026-01-10T12:00:00.000Z",
    "updatedAt": "2026-02-05T09:15:00.000Z"
  }
]

Create a new knowledge base to hold documents for agent retrieval.

Request Body

Example Request

{
  "name": "Product Documentation",
  "description": "Complete product docs, FAQ, and troubleshooting guides"
}

Retrieve a knowledge base along with its uploaded documents.

Response

{
  "id": "kb_01hx9z3abc",
  "name": "Product Documentation",
  "description": "Complete product docs and FAQ",
  "documents": [
    {
      "id": "doc_a1b2c3",
      "filename": "product-manual.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 2048576,
      "chunkCount": 47,
      "uploadedAt": "2026-01-12T14:30:00.000Z"
    }
  ],
  "createdAt": "2026-01-10T12:00:00.000Z"
}

Upload a document to a knowledge base. Uses multipart/form-data encoding. Supported formats: PDF, DOCX, TXT, Markdown.

Request Body

Response

{
  "id": "doc_d4e5f6",
  "filename": "faq.md",
  "mimeType": "text/markdown",
  "sizeBytes": 15234,
  "chunkCount": 12,
  "uploadedAt": "2026-02-07T10:15:00.000Z"
}

Returns conversations with optional filtering by agent, channel, and status.

Query Parameters

Response

[
  {
    "id": "conv_x1y2z3",
    "agentId": "clx1a2b3c4d5e6f7g8h9i0j",
    "channel": "voice",
    "status": "completed",
    "callerNumber": "+14155559876",
    "sentiment": "positive",
    "duration": 245,
    "messageCount": 12,
    "createdAt": "2026-02-06T15:30:00.000Z",
    "endedAt": "2026-02-06T15:34:05.000Z"
  }
]

Retrieve a full conversation including all messages and metadata.

Response

{
  "id": "conv_x1y2z3",
  "agentId": "clx1a2b3c4d5e6f7g8h9i0j",
  "channel": "voice",
  "status": "completed",
  "callerNumber": "+14155559876",
  "sentiment": "positive",
  "duration": 245,
  "recordingUrl": "https://api.twilio.com/recordings/RE...",
  "messages": [
    {
      "id": "msg_001",
      "role": "assistant",
      "content": "Hello! How can I assist you today?",
      "createdAt": "2026-02-06T15:30:00.000Z"
    },
    {
      "id": "msg_002",
      "role": "user",
      "content": "I need help with my billing statement.",
      "createdAt": "2026-02-06T15:30:15.000Z"
    }
  ],
  "createdAt": "2026-02-06T15:30:00.000Z",
  "endedAt": "2026-02-06T15:34:05.000Z"
}

Returns all messages in a conversation, ordered chronologically.

Response

[
  {
    "id": "msg_001",
    "conversationId": "conv_x1y2z3",
    "role": "assistant",
    "content": "Hello! How can I assist you today?",
    "metadata": null,
    "createdAt": "2026-02-06T15:30:00.000Z"
  },
  {
    "id": "msg_002",
    "conversationId": "conv_x1y2z3",
    "role": "user",
    "content": "I need help with my billing statement.",
    "metadata": null,
    "createdAt": "2026-02-06T15:30:15.000Z"
  }
]

Returns all campaigns with agent details and contact statistics.

Response

[
  {
    "id": "cmp_abc123",
    "name": "Q1 Outreach Campaign",
    "description": "Follow-up calls for Q1 leads",
    "status": "active",
    "agentId": "clx1a2b3c4d5e6f7g8h9i0j",
    "agent": { "id": "clx1a2b3c4d5e6f7g8h9i0j", "name": "Sales Agent" },
    "callerIdNumber": "+14155551234",
    "maxConcurrentCalls": 5,
    "maxRetries": 3,
    "retryDelayMinutes": 60,
    "contactStats": { "total": 500, "completed": 234, "pending": 266 },
    "createdAt": "2026-02-01T09:00:00.000Z"
  }
]

Create a new outbound campaign. Campaigns start in draft status.

Request Body

Example Request

{
  "name": "Q1 Outreach Campaign",
  "description": "Follow-up calls for Q1 leads",
  "agentId": "clx1a2b3c4d5e6f7g8h9i0j",
  "callerIdNumber": "+14155551234",
  "maxConcurrentCalls": 5,
  "maxRetries": 3,
  "retryDelayMinutes": 60
}

Retrieve a campaign with its full contact list and per-contact outcomes.

Update campaign configuration. Only draft campaigns can be fully edited; active campaigns allow limited updates.

Delete a campaign. Only campaigns with status draft, completed, or cancelled can be deleted.

Start executing a draft or paused campaign. Begins dialing contacts.

Response

{
  "id": "cmp_abc123",
  "status": "active",
  "startedAt": "2026-02-07T10:00:00.000Z"
}

Pause an active campaign. In-progress calls will complete but no new calls will be initiated.

Add multiple contacts to a campaign in a single request.

Request Body

Example Request

{
  "contacts": [
    {
      "phoneNumber": "+14155559001",
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "customData": { "plan": "enterprise", "accountId": "ACC-001" }
    },
    {
      "phoneNumber": "+14155559002",
      "name": "Bob Smith",
      "customData": { "plan": "starter" }
    }
  ]
}

Response

{
  "added": 2,
  "duplicatesSkipped": 0
}

Returns QA scores with filtering options.

Query Parameters

Response

[
  {
    "id": "qa_score_001",
    "conversationId": "conv_x1y2z3",
    "overallScore": 87,
    "categories": {
      "greeting": 95,
      "problemIdentification": 90,
      "resolution": 80,
      "communication": 88,
      "compliance": 92,
      "closing": 78
    },
    "flagged": false,
    "status": "auto",
    "feedback": null,
    "createdAt": "2026-02-06T16:00:00.000Z"
  }
]

Retrieve a QA score with the associated conversation and messages for full review context.

Override or review a QA score with manual feedback.

Request Body

Example Request

{
  "overallScore": 72,
  "feedback": "Agent missed upsell opportunity and had a slow closing.",
  "flagged": true,
  "flagReason": "Needs coaching on closing techniques",
  "status": "reviewed"
}

Re-run the AI scoring engine on a conversation. Useful after updating scoring criteria.

Response

{
  "id": "qa_score_001",
  "overallScore": 85,
  "status": "auto",
  "rescoredAt": "2026-02-07T10:30:00.000Z"
}

Returns pending and active handoff requests with optional filtering.

Query Parameters

Response

[
  {
    "id": "hoff_001",
    "conversationId": "conv_x1y2z3",
    "agentId": "clx1a2b3c4d5e6f7g8h9i0j",
    "reason": "Customer requesting human agent",
    "priority": "high",
    "customerSentiment": "frustrated",
    "contextSummary": "Customer has billing dispute, AI unable to resolve...",
    "status": "pending",
    "assignedTo": null,
    "waitTimeSeconds": 45,
    "createdAt": "2026-02-07T10:15:00.000Z"
  }
]

Escalate a conversation to the human agent queue.

Request Body

Example Request

{
  "conversationId": "conv_x1y2z3",
  "agentId": "clx1a2b3c4d5e6f7g8h9i0j",
  "reason": "Customer requesting human agent for billing dispute",
  "priority": "high",
  "customerSentiment": "frustrated",
  "contextSummary": "Customer disputes $49.99 charge on Feb statement. AI verified charge is valid but customer insists on speaking to a person."
}

Retrieve a handoff request with the full conversation and messages for agent review.

Update handoff request details such as priority or notes.

Claim a handoff request and assign it to the currently authenticated user.

Response

{
  "id": "hoff_001",
  "status": "assigned",
  "assignedTo": "user_me123",
  "assignedAt": "2026-02-07T10:16:00.000Z"
}

Mark a handoff as resolved after the human agent has handled the conversation.

Returns a list of human agents currently marked as available for handoffs.

Response

[
  {
    "userId": "user_me123",
    "name": "Jane Smith",
    "email": "jane@company.com",
    "available": true,
    "activeHandoffs": 1,
    "lastActiveAt": "2026-02-07T10:10:00.000Z"
  }
]

Toggle the current user's availability for receiving handoff assignments.

Example Request

{
  "available": true
}

Returns all automation rules for the organization.

Response

[
  {
    "id": "auto_001",
    "name": "Negative Sentiment Alert",
    "description": "Send Slack notification when sentiment is negative",
    "trigger": "conversation.ended",
    "conditions": { "sentiment": "negative" },
    "action": "webhook",
    "actionConfig": {
      "url": "https://hooks.slack.com/services/T.../B.../xxx",
      "method": "POST"
    },
    "active": true,
    "executionCount": 47,
    "lastExecutedAt": "2026-02-06T22:15:00.000Z",
    "createdAt": "2026-01-20T08:00:00.000Z"
  }
]

Create a new automation rule.

Request Body

Example Request

{
  "name": "Escalation Webhook",
  "description": "Fire webhook when a handoff is requested",
  "trigger": "handoff.requested",
  "conditions": { "priority": "high" },
  "action": "webhook",
  "actionConfig": {
    "url": "https://api.yourapp.com/escalation",
    "method": "POST",
    "headers": { "Authorization": "Bearer token123" }
  }
}

Retrieve an automation rule with its most recent execution logs.

Update an automation rule's configuration. Accepts the same fields as the create endpoint.

Permanently delete an automation rule.

Toggle an automation rule between active and inactive states.

Response

{
  "id": "auto_001",
  "active": false
}

Returns paginated execution logs for a specific automation rule.

Query Parameters

Response

{
  "logs": [
    {
      "id": "log_001",
      "automationId": "auto_001",
      "conversationId": "conv_x1y2z3",
      "status": "success",
      "executedAt": "2026-02-06T22:15:00.000Z",
      "durationMs": 342,
      "result": { "statusCode": 200 }
    },
    {
      "id": "log_002",
      "automationId": "auto_001",
      "conversationId": "conv_a4b5c6",
      "status": "failed",
      "executedAt": "2026-02-06T20:00:00.000Z",
      "durationMs": 5023,
      "error": "Webhook timeout after 5000ms"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3
  }
}

Returns all routing rules with associated agent details, ordered by priority.

Response

[
  {
    "id": "route_001",
    "name": "Spanish to ES Agent",
    "sourceAgent": { "id": "agent_en", "name": "English Receptionist" },
    "targetAgent": { "id": "agent_es", "name": "Spanish Support Agent" },
    "conditions": { "language": "es" },
    "priority": 10,
    "active": true,
    "transferCount": 89,
    "createdAt": "2026-01-18T12:00:00.000Z"
  }
]

Create a new routing rule.

Request Body

Example Request

{
  "name": "Billing Escalation",
  "sourceAgentId": "agent_general",
  "targetAgentId": "agent_billing",
  "conditions": {
    "intent": "billing",
    "keywords": ["invoice", "charge", "payment", "refund"]
  },
  "priority": 5
}

Retrieve a specific routing rule with full details.

Update a routing rule. Accepts the same fields as the create endpoint.

Permanently delete a routing rule.

Toggle a routing rule between active and inactive.

Response

{
  "id": "route_001",
  "active": true
}

Evaluate routing rules against a set of conversation attributes. Returns the matched rule and target agent, if any.

Request Body

Response

{
  "matched": true,
  "rule": {
    "id": "route_001",
    "name": "Billing Escalation"
  },
  "targetAgent": {
    "id": "agent_billing",
    "name": "Billing Specialist"
  },
  "transferred": true
}

Returns all available agent templates, sorted by usage count.

Response

[
  {
    "id": "tmpl_support_01",
    "name": "Customer Support Agent",
    "description": "Pre-configured support agent with empathetic tone and escalation flows",
    "category": "support",
    "type": "inbound",
    "systemPrompt": "You are a helpful and empathetic customer support agent...",
    "greetingMessage": "Hello! How can I help you today?",
    "skills": ["general-support", "troubleshooting"],
    "usageCount": 342,
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
]

Retrieve full details for a specific template.

Create a new agent using the template's configuration as a starting point.

Request Body

Example Request

{
  "name": "My Support Agent",
  "twilioPhoneNumber": "+14155551234"
}

Response

{
  "id": "clx_new_agent_id",
  "name": "My Support Agent",
  "type": "inbound",
  "systemPrompt": "You are a helpful and empathetic customer support agent...",
  "templateId": "tmpl_support_01",
  "createdAt": "2026-02-07T10:00:00.000Z"
}

Returns the current organization's subscription and billing details.

Response

{
  "plan": "pro",
  "status": "active",
  "currentPeriodStart": "2026-02-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-03-01T00:00:00.000Z",
  "usage": {
    "minutesUsed": 4230,
    "minutesLimit": 10000,
    "agentsUsed": 5,
    "agentsLimit": 20
  },
  "stripeCustomerId": "cus_xxx"
}

Generate a Stripe billing portal URL for the customer to manage their subscription.

Response

{
  "url": "https://billing.stripe.com/p/session/..."
}

Send a message to a chat agent. Returns a Server-Sent Events (SSE) stream with the agent's response tokens.

Request Body

Example Request

{
  "agentId": "clx1a2b3c4d5e6f7g8h9i0j",
  "message": "What are your business hours?",
  "sessionToken": "sess_abc123xyz"
}

SSE Response Stream

data: {"type":"token","content":"Our"}
data: {"type":"token","content":" business"}
data: {"type":"token","content":" hours"}
data: {"type":"token","content":" are"}
data: {"type":"token","content":" Monday-Friday, 9am-5pm EST."}
data: {"type":"done","sessionToken":"sess_abc123xyz"}

Retrieve the chat history for a widget session. Requires a valid session token as a query parameter.

Query Parameters

Response

{
  "sessionToken": "sess_abc123xyz",
  "agentId": "clx1a2b3c4d5e6f7g8h9i0j",
  "messages": [
    { "role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-02-07T10:00:00.000Z" },
    { "role": "user", "content": "What are your hours?", "createdAt": "2026-02-07T10:00:15.000Z" },
    { "role": "assistant", "content": "Our business hours are Monday-Friday, 9am-5pm EST.", "createdAt": "2026-02-07T10:00:16.000Z" }
  ]
}

Receives incoming voice call events from Twilio. Matches the called number to an agent and initiates the AI conversation. Returns TwiML to control the call flow.

Twilio Sends

{
  "CallSid": "CA1234567890abcdef",
  "From": "+14155559876",
  "To": "+14155551234",
  "CallStatus": "ringing",
  "Direction": "inbound"
}

Returns

TwiML XML response to control the call (connect to AI agent via WebSocket).

Receives incoming SMS messages from Twilio. Processes the message through the matched agent and returns a TwiML response with the AI reply.

Twilio Sends

{
  "MessageSid": "SM1234567890abcdef",
  "From": "+14155559876",
  "To": "+14155551234",
  "Body": "Hi, I need help with my order"
}

Receives call status updates from Twilio (ringing, in-progress, completed, failed, busy, no-answer). Updates the conversation record accordingly.

Twilio Sends

{
  "CallSid": "CA1234567890abcdef",
  "CallStatus": "completed",
  "CallDuration": "245",
  "Timestamp": "2026-02-07T10:34:05.000Z"
}

Receives recording completion events from Twilio. Stores the recording URL and triggers QA scoring on the conversation.

Twilio Sends

{
  "CallSid": "CA1234567890abcdef",
  "RecordingSid": "RE1234567890abcdef",
  "RecordingUrl": "https://api.twilio.com/2010-04-01/Accounts/.../Recordings/RE...",
  "RecordingStatus": "completed",
  "RecordingDuration": "245"
}

Receives subscription lifecycle events from Stripe. Handles events like customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, and invoice.payment_failed.

Stripe Sends

{
  "id": "evt_1234567890",
  "type": "customer.subscription.updated",
  "data": {
    "object": {
      "id": "sub_abc123",
      "customer": "cus_xxx",
      "status": "active",
      "plan": {
        "id": "price_pro_monthly",
        "product": "prod_callcenter_pro"
      },
      "current_period_end": 1741046400
    }
  }
}