Server events
All messages sent to your Server URL are POST requests with this body shape:
Common metadata included on most events:
phoneNumber,timestampartifact(recording, transcript, messages, etc.)assistant,customer,call,chat
Most events are informational and do not require a response. Responses are only expected for these types sent to your Server URL:
- “assistant-request”
- “tool-calls”
- “transfer-destination-request”
- “knowledge-base-request”
Note: Some specialized messages like “voice-request” and “call.endpointing.request” are sent to their dedicated servers if configured (e.g. assistant.voice.server.url, assistant.startSpeakingPlan.smartEndpointingPlan.server.url).
Function Calling (Tools)
Vapi supports OpenAI-style tool/function calling. Assistants can ping your server to perform actions.
Example assistant configuration (excerpt):
When tools are triggered, your Server URL receives a tool-calls message:
Respond with results for each tool call:
Optionally include a message to speak to the user while or after running the tool.
If a tool does not need a response immediately, you can design it to be asynchronous.
Retrieving Assistants
For inbound phone calls, you can specify the assistant dynamically. If a PhoneNumber doesn’t have an assistantId, Vapi may request one from your server:
You must respond to the assistant-request webhook within 7.5 seconds end-to-end. This limit is fixed and not configurable: the telephony provider enforces a 15-second cap, and Vapi reserves ~7.5 seconds for call setup. The timeout value shown elsewhere in the dashboard does not apply to this webhook.
To avoid timeouts:
- Return quickly with an existing
assistantIdor a minimal assistant, then enrich context asynchronously after the call starts using Live Call Control. - Host your webhook close to
us-west-2to reduce latency, and target < ~6s to allow for network jitter.
Respond with either an existing assistant ID, a transient assistant, or transfer destination:
Transfer only (skip AI)
If you want to immediately transfer the call without using an assistant, return a destination in your assistant-request response. This bypasses AI handling.
When destination is present in the assistant-request response, the call forwards immediately and assistantId, assistant, squadId, and squad are ignored.
You must still respond within 7.5 seconds.
To transfer silently, set destination.message to an empty string.
For caller ID behavior, see Call features.
Or return an error message to be spoken to the caller:
Status Updates
scheduled: Call scheduled.queued: Call queued.ringing: The call is ringing.in-progress: The call has started.forwarding: The call is about to be forwarded.ended: The call has ended.
End of Call Report
Hang Notifications
Use this to surface delays or notify your team.
Conversation Updates
Sent when an update is committed to the conversation history.
Transcript
Partial and final transcripts from the transcriber.
For final-only events, you may receive type: "transcript[transcriptType=\"final\"]".
Speech Update
Model Output
Tokens or tool-call outputs as the model generates.
Transfer Destination Request
Requested when the model wants to transfer but the destination is not yet known and must be provided by your server.
This event is emitted only if the assistant did not supply a destination when calling a transferCall tool (for example, it did not include a custom parameter like phoneNumber). If the assistant includes the destination directly, Vapi will transfer immediately and will not send this webhook.
Respond with a destination and optionally a message:
Transfer Update
Fires whenever a transfer occurs.
User Interrupted
Language Change Detected
Sent when the transcriber switches based on detected language.
Phone Call Control (Advanced)
When requested in assistant.serverMessages, hangup and forwarding are delegated to your server.
Knowledge Base Request (Custom)
If using assistant.knowledgeBase.provider = "custom-knowledge-base".
Respond with documents (and optionally a custom message to speak):
Voice Input (Custom Voice Providers)
Voice Request (Custom Voice Server)
Sent to assistant.voice.server.url. Respond with raw 1-channel 16-bit PCM audio at the requested sample rate (not JSON).
Call Endpointing Request (Custom Endpointing Server)
Sent to assistant.startSpeakingPlan.smartEndpointingPlan.server.url.
Respond with the timeout before considering the user’s speech finished:
Chat Events
chat.created: Sent when a new chat is created.chat.deleted: Sent when a chat is deleted.
Session Events
session.created: Sent when a session is created.session.updated: Sent when a session is updated.session.deleted: Sent when a session is deleted.