Skip to main content

​
Overview

The custom integration feature allows you to send call transcripts from your own backend system or third-party service to Cekura via webhooks. This provides flexibility to integrate any voice platform while maintaining full control over your conversation data.

​
How It Works

  1. Configure your agent in Cekura and select “Custom” as the provider
  2. Cekura provides you with a webhook URL
  3. After each call ends, send the transcript to the webhook URL
  4. Cekura listens for transcripts for 5 minutes after the call starts
  5. View evaluation results in the Cekura dashboard

​
Setup

​
In Cekura Dashboard

  1. Create or edit an agent in the Cekura dashboard
  2. Set the transcript provider to “Custom”
  3. Copy the webhook URL provided by Cekura
  4. Note your API key for authentication

​
Webhook Implementation Requirements

Your system should send call transcripts to the Cekura webhook with the following specifications: HTTP Method: POST Headers: 
X-CEKURA-API-KEY: your-api-key-here
Content-Type: application/json
Timing: Send the transcript within 5 minutes after the call ends. Cekura will listen for webhooks for 5 minutes from when the call starts.

​
Payload Format

Your webhook POST request should send a JSON payload with the following structure:

​
Top Level Structure

{
  "agent_id": 123,  // Required: The ID of the AI agent in Cekura
  "calls": [...]    // Required: Array of call objects
}

​
Call Object Structure

Each call in the calls array should include:
FieldTypeRequiredDescription
idstringYesUnique identifier for this call from your system (max 255 chars)
startedAtstringYesCall start time in ISO 8601 format
endedAtstringYesCall end time in ISO 8601 format
messagesarrayNoList of transcript messages (see below)
to_phone_numberstringNoPhone number that received the call (must start with + followed by digits, max 15 chars). Example: ‘+14155551234’
from_phone_numberstringNoPhone number that initiated the call (must start with + followed by digits, max 15 chars). Example: ‘+18005551234’
metadataobjectNoOptional metadata as key-value pairs for additional call information
endedReasonstringNoReason call ended (default: “unknown”, e.g., “assistant-ended-call”, “customer-hungup”)

​
Message Object Structure

Each message in the messages array should include:
FieldTypeRequiredDescription
rolestringYesMessage role: “bot”, “user”, “system”, “function_call”, or “function_call_result”
contentstringYesThe message content or function description
start_timenumberYesStart time in milliseconds from epoch
end_timenumberYesEnd time in milliseconds from epoch
dataobjectNoAdditional data for function calls

​
Complete Example

Here’s a complete example payload with two calls: 
{
  "agent_id": 2,
  "calls": [
    {
      "id": "0199e72d-795e-7ffe-b9b9-d3b08a3a11ae",
      "startedAt": "2025-10-15T09:22:21.787Z",
      "endedAt": "2025-10-15T09:24:30.229Z",
      "to_phone_number": "+18646190758",
      "from_phone_number": "+14155551234",
      "messages": [
        {
          "role": "bot",
          "content": "Hi there. This is Alex from Tech Solutions customer support. How can I help you today?",
          "start_time": 1760520142852,
          "end_time": 1760520147842
        },
        {
          "role": "user",
          "content": "Yeah. I have a question about a recent recurring charge on my account.",
          "start_time": 1760520149392,
          "end_time": 1760520153012
        },
        {
          "role": "bot",
          "content": "Got it. Let me help you figure that out. Could you tell me the email address linked to your account so I can look this up for you?",
          "start_time": 1760520154442,
          "end_time": 1760520160522
        },
        {
          "role": "user",
          "content": "Okay. It's john dot doe at email dot com",
          "start_time": 1760520157372,
          "end_time": 1760520165132
        }
      ],
      "metadata": {
        "customer_name": "John Doe",
        "call_type": "support"
      },
      "endedReason": "customer-hungup"
    },
    {
      "id": "0199e72d-791d-7eee-b5d9-b82843919e42",
      "startedAt": "2025-10-15T09:22:21.727Z",
      "endedAt": "2025-10-15T09:23:48.100Z",
      "to_phone_number": "+18646190758",
      "from_phone_number": "+14155559999",
      "messages": [
        {
          "role": "bot",
          "content": "Hi there. This is Alex from Tech Solutions customer support. How can I help you today?",
          "start_time": 1760520142868,
          "end_time": 1760520147998
        },
        {
          "role": "user",
          "content": "Yeah. The Taskmaster Pro app keeps crashing.",
          "start_time": 1760520149538,
          "end_time": 1760520152118
        }
      ],
      "metadata": {
        "customer_name": "Jane Smith",
        "call_type": "technical_issue"
      },
      "endedReason": "assistant-ended-call"
    }
  ]
}

​
Important Considerations

For successful webhook integration, ensure:
  1. Timing: Send the webhook within 5 minutes after the call ends
  2. Authentication: Include the X-CEKURA-API-KEY header with your API key
  3. Phone Numbers: Phone numbers must start with + followed by digits (max 15 chars, e.g., ‘+14155551234’). The to_phone_number should match the scenario’s inbound number for testing
  4. Timestamps: Use ISO 8601 format for startedAt and endedAt
  5. Message Timing: Use milliseconds from epoch for message start_time and end_time (optional fields)
  6. Agent ID: Use the correct agent ID from your Cekura dashboard
  7. Unique Call IDs: Each call should have a unique identifier (max 255 chars)
  8. Metadata: Use the metadata field to pass additional key-value pairs for call information

​
Troubleshooting

If your webhook integration isn’t working as expected:

​
No calls appear in Cekura

  • Verify the webhook URL is correct
  • Check that the X-CEKURA-API-KEY header is included and correct
  • Ensure the payload format matches the specification
  • Confirm the agent_id is correct
  • Verify the webhook was sent within 5 minutes after the call ended

​
Authentication issues

  • Double-check your API key is correct
  • Ensure the header name is exactly X-CEKURA-API-KEY (case-sensitive)
  • Verify the API key has proper permissions

​
Calls not matching scenarios

  • Confirm the to_phone_number in the payload matches the scenario’s inbound number
  • Ensure phone numbers start with + followed by digits (max 15 chars)
  • Check that the call ID is unique and under 255 characters
  • Verify timestamps are in ISO 8601 format

​
Invalid payload errors

  • Validate your JSON payload structure
  • Ensure all required fields are present (id, startedAt, endedAt, messages)
  • Verify the agent_id is an integer, not a string
  • Check that phone numbers follow the correct format (+ followed by digits, max 15 chars)
  • Ensure messages is an array with dictionaries containing role and content fields

​
Next Steps