The VAPI integration provides a chat completions endpoint specifically designed for handling phone call conversations through the Voice API service.
Chat Completions
POST /api/project/{projectId}/integration/vapi/chat/completions
Path Parameters
Request Body
Array of messages in the conversation. Each message should have a role (“system”, “user”, or “assistant”) and content.
Whether to stream the response. Defaults to false.
Array of external tool definitions that will be available for the assistant to use during the phone call.
Each tool should have a type (currently only “function” is supported) and a function
object with name, description, and parameters (JSON Schema format).
Information about the current call session.{
id: string; // Call ID
orgId: string; // Organization ID
createdAt: string; // Call creation timestamp
updatedAt: string; // Call update timestamp
type: string; // Call type
status: string; // Call status
assistantId: string; // Assistant ID
customer?: {
number: string; // Customer phone number
};
phoneNumberId?: string; // Phone number ID
phoneCallProvider?: string; // Call provider (e.g., Twilio)
phoneCallProviderId?: string; // Provider-specific call ID
phoneCallTransport?: string; // Call transport method
}
Optional phone number configuration.{
id: string; // Phone number ID
orgId: string; // Organization ID
number: string; // Phone number
createdAt: string; // Creation timestamp
updatedAt: string; // Update timestamp
twilioAccountSid: string;// Twilio account SID
twilioAuthToken: string; // Twilio auth token
name: string; // Phone number name
provider: string; // Phone provider
}
Optional customer information.{
number: string; // Customer phone number
}
{
"messages": [
{
"role": "user",
"content": "Hello!"
}
],
"stream": false,
"call": {
"id": "call_abc123",
"orgId": "org_xyz789",
"type": "inbound",
"status": "in-progress",
"assistantId": "asst_def456"
}
}
{
"messages": [
{
"role": "user",
"content": "Can you check my account status?"
}
],
"stream": false,
"call": {
"id": "call_abc123",
"orgId": "org_xyz789",
"type": "inbound",
"status": "in-progress",
"assistantId": "asst_def456",
"customer": {
"number": "+1234567890"
}
},
"tools": [
{
"type": "function",
"function": {
"name": "check_account_status",
"description": "Check customer account status and information",
"parameters": {
"type": "object",
"properties": {
"customer_phone": {
"type": "string",
"description": "Customer's phone number"
}
},
"required": ["customer_phone"]
}
}
}
]
}
Response
The response format is identical to the API integration’s chat completions endpoint, with the addition of session management for phone calls.
Unique identifier for the completion
Object type (“chat.completion”)
Unix timestamp of when the completion was created
Model used for the completion
Array of completion choices
choices[].message.tool_calls
Array of tool calls made by the assistant (when tools are provided and used)
Reason for completion termination. Can be “stop” for normal completion or “tool_calls” when tools are invoked.
Session ID for the conversation
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1677858242,
"model": "pathway-default",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hi! How can I help you today?"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": -1,
"completion_tokens": -1,
"total_tokens": -1
},
"session_id": "session-xyz789"
}
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1677858242,
"model": "pathway-default",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "",
"tool_calls": [
{
"id": "call_123",
"type": "function",
"function": {
"name": "check_account_status",
"arguments": "{\"customer_phone\": \"+1234567890\"}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": -1,
"completion_tokens": -1,
"total_tokens": -1
},
"session_id": "session-xyz789"
}
Streaming Response
The streaming response format is identical to the API integration’s streaming format.
Error Responses
| Status Code | Description |
|---|
| 400 | Invalid request body or missing call ID |
| 500 | Internal server error |
When you provide tools in the VAPI request, the assistant can invoke them during the phone call conversation. The tool calling workflow is handled automatically:
- Tool Execution: When the assistant needs to call a tool, it will return a response with
tool_calls
- Tool Results: You should execute the requested tools and send the results back in a follow-up request
- Final Response: The assistant will use the tool results to formulate its final response to the caller
After receiving tool calls, send the results back in your next request:
{
"messages": [
{"role": "user", "content": "Can you check my account status?"},
{
"role": "assistant",
"content": "",
"tool_calls": [
{
"id": "call_123",
"type": "function",
"function": {
"name": "check_account_status",
"arguments": "{\"customer_phone\": \"+1234567890\"}"
}
}
]
},
{
"role": "tool",
"content": "Account status: Active, Balance: $150.00",
"tool_call_id": "call_123",
"name": "check_account_status"
}
],
"call": {
"id": "call_abc123",
"orgId": "org_xyz789",
"type": "inbound",
"status": "in-progress",
"assistantId": "asst_def456"
}
}
Session Management
The VAPI integration uses the call ID as the session identifier for conversation continuity. Each unique call ID represents a separate conversation session. 
