Callbacks
Implement three POST endpoints to control your voice agent.
POST onCallStart
Called when a call comes in, before the conversation starts. Return the full call configuration.
Veevo sends
{
"callSid": "CA...",
"callerPhone": "+19805551234",
"calledNumber": "+15551234567",
"timestamp": "2026-04-03T..."
}Your backend returns
{
"twilioAccountSid": "AC...",
"twilioAuthToken": "...",
"openaiApiKey": "sk-...",
"systemPrompt": "You are a helpful assistant for...",
"voice": "marin",
"model": "gpt-realtime-1.5",
"onToolCallUrl": "https://your-backend.com/calls/tool",
"tools": []
}!
Timeout: 10 seconds. If your backend doesn't respond, the call is rejected.
Configuration Fields
| Field | Required | Default | Description |
|---|---|---|---|
| twilioAccountSid | yes | — | Twilio account SID |
| twilioAuthToken | yes | — | Twilio auth token |
| openaiApiKey | yes | — | OpenAI key with Realtime API access |
| systemPrompt | yes | — | The AI agent's instructions |
| voice | no | marin | alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar |
| model | no | gpt-realtime-1.5 | gpt-realtime-1.5 or gpt-realtime-mini |
| vadEagerness | no | high | low, medium, high, auto |
| noiseReduction | no | near_field | near_field or far_field |
| inactivityTimeoutMs | no | 60000 | Auto-hangup after silence (ms) |
| greetingUrl | no | — | MP3 URL played before AI connects |
| onToolCallUrl | yes | — | Where tool calls are POSTed |
| tools | no | [] | OpenAI function definitions |
| metadata | no | — | Passed through to onToolCall and onCallEnd |
POST onToolCall
Called when the AI invokes a tool defined in the tools array.
Veevo sends
{
"toolName": "check_availability",
"arguments": { "date": "April 15, 2026" },
"metadata": { "customerId": "cust_123" },
"timestamp": "2026-04-03T..."
}Your backend returns
{
"result": "We have 3 standard units available for April 15."
}i
Timeout: 30 seconds. The AI is blocked during this time — keep responses fast (<500ms) for natural conversation flow.
POST onCallEnd
Called after the call ends. Contains the full transcript and cost breakdown.
{
"callSid": "CA...",
"transcript": [
{ "role": "assistant", "content": "Hi, how can I help?", "timestamp": 1711900000 },
{ "role": "user", "content": "I need two units delivered Friday.", "timestamp": 1711900005 }
],
"costBreakdown": {
"inputTextTokens": 365,
"inputAudioTokens": 90,
"outputTextTokens": 45,
"outputAudioTokens": 109,
"costInputText": 0.00146,
"costInputAudio": 0.00288,
"costOutputText": 0.00072,
"costOutputAudio": 0.006976,
"costTwilio": 0.006647,
"totalCost": 0.018483
},
"durationSeconds": 47,
"metadata": { "customerId": "cust_123" },
"timestamp": "2026-04-03T..."
}