POST/api/v1/voice-agents/{id}/webhook

Start a call via webhook

Initiates a voice agent call from an external application. Requires an API Key with the 'voice-agents:webhook' scope.

Authentication

Send your API key in the x-api-key header.

x-api-keybearer

Parameters

idrequired

path · string

Voice Agent ID

Request body

required

PublicApiStartCallWebhookDto

namerequired

string

Full name of the contact

email

string

Email address of the contact (optional if phone is provided)

phonerequired

string

Phone in E.164 format (e.g., +1234567890)

dynamicVariables

object

Dynamic variables to be used in the voice agent prompt. Must match the variables configured in the agent.

Example request

json

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "dynamicVariables": {
    "company.name": "Acme Inc",
    "contact.jobTitle": "CEO"
  }
}

Responses

201Call successfully initiated

PublicApiStartCallWebhookResponseDto

callIdrequired

string

ID of the created voice agent call

statusrequired

string

Status of the call

queuedringingin_progresscompletedfailedcancelled

contactIdrequired

string

ID of the contact associated with the call

phoneNumberrequired

string

Phone number being called

createdAtrequired

string (date-time)

Timestamp when the call was created

Example response

json

{
  "callId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "queued",
  "contactId": "123e4567-e89b-12d3-a456-426614174001",
  "phoneNumber": "+1234567890",
  "createdAt": "2024-01-20T10:30:00Z"
}

400Invalid request payload or voice agent is not active

401Invalid or missing API Key

403API Key does not have the required scope

404Voice agent not found