For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
WebsiteStatusSupportDashboard
DocumentationAPI ReferenceMCPSDKsCLI (new)What's New?
DocumentationAPI ReferenceMCPSDKsCLI (new)What's New?
  • Get started
    • Introduction
    • Phone calls
    • Web calls
    • Vapi Guides
    • Composer
    • CLI quickstart
  • Assistants
    • Quickstart
    • Tools
    • Custom keywords
    • Custom voices
    • Custom transcriber
    • Custom TTS
  • Observability
    • Boards
  • Squads
    • Quickstart
    • Overview
    • Handoff tool
    • Passing data between assistants
  • Best practices
    • Prompting guide
    • Debugging voice agents
    • Enterprise environments (DEV/UAT/PROD)
    • IVR navigation
  • Phone numbers
    • Free Vapi number
    • Inbound SMS
    • Phone Number Hooks
  • Calls
      • Real-time call control
      • Customer join timeout
      • Voicemail detection
      • Call queue management
      • Call concurrency
    • Call end reasons
    • Troubleshoot call errors
  • Outbound Campaigns
    • Quickstart
    • Overview
  • Chat
    • Quickstart
    • Streaming
    • Non-streaming
    • OpenAI compatibility
    • Session management
    • Variable substitution
    • SMS chat
    • Web widget
    • Webhooks
  • Workflows
    • Quickstart
    • Overview
LogoLogo
WebsiteStatusSupportDashboard
On this page
  • Obtaining URLs for Call Control and Listen
  • Sample Request
  • Sample Response
  • Call Control Features
  • 1. Say Message
  • 2. Add Message to Conversation
  • 3. Assistant Control
  • 4. End Call
  • 5. Transfer Call
  • 6. Handoff Call
  • Call Listen Feature
  • Example: Saving Audio Data from a Live Call
CallsIn-call control

Live Call Control

Was this page helpful?
Edit this page
Previous

Customer Join Timeout

Configure web call join timeout for better success rates
Next
Built with

Vapi offers two main features that provide enhanced control over live calls:

  1. Call Control: This feature allows you to inject conversation elements dynamically during an ongoing call.
  2. Call Listen: This feature enables real-time audio data streaming using WebSocket connections.

To use these features, you first need to obtain the URLs specific to the live call. These URLs can be retrieved by triggering a /call endpoint, which returns the listenUrl and controlUrl within the monitor object.

Obtaining URLs for Call Control and Listen

To initiate a call and retrieve the listenUrl and controlUrl, send a POST request to the /call endpoint.

Sample Request

$curl 'https://api.vapi.ai/call' 
$-H 'authorization: Bearer YOUR_API_KEY' 
$-H 'content-type: application/json' 
$--data-raw '{
>  "assistantId": "5b0a4a08-133c-4146-9315-0984f8c6be80",
>  "customer": {
>    "number": "+12345678913"
>  },
>  "phoneNumberId": "42b4b25d-031e-4786-857f-63b346c9580f"
>}'

Sample Response

1{
2  "id": "7420f27a-30fd-4f49-a995-5549ae7cc00d",
3  "assistantId": "5b0a4a08-133c-4146-9315-0984f8c6be80",
4  "phoneNumberId": "42b4b25d-031e-4786-857f-63b346c9580f",
5  "type": "outboundPhoneCall",
6  "createdAt": "2024-09-10T11:14:12.339Z",
7  "updatedAt": "2024-09-10T11:14:12.339Z",
8  "orgId": "eb166faa-7145-46ef-8044-589b47ae3b56",
9  "cost": 0,
10  "customer": {
11    "number": "+12345678913"
12  },
13  "status": "queued",
14  "phoneCallProvider": "twilio",
15  "phoneCallProviderId": "CA4c6793d069ef42f4ccad69a0957451ec",
16  "phoneCallTransport": "pstn",
17  "monitor": {
18    "listenUrl": "wss://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/transport",
19    "controlUrl": "<https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control>"
20  }
21}

Call Control Features

Once you have the controlUrl, you can use various control features during a live call. Here are all the available control options:

1. Say Message

Makes the assistant say a specific message during the call.

$curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control' 
$-H 'content-type: application/json' 
$--data-raw '{
>  "type": "say",
>  "content": "Welcome to Vapi, this message was injected during the call.",
>  "endCallAfterSpoken": false
>}'

2. Add Message to Conversation

Adds a message to the conversation history and optionally triggers a response.

$curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control' 
$-H 'content-type: application/json' 
$--data-raw '{
>  "type": "add-message",
>  "message": {
>    "role": "system",
>    "content": "New message added to conversation"
>  },
>  "triggerResponseEnabled": true
>}'

3. Assistant Control

Control the assistant’s behavior during the call.

$curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control' 
$-H 'content-type: application/json' 
$--data-raw '{
>  "type": "control",
>  "control": "mute-assistant"  // Options: "mute-assistant", "unmute-assistant", "say-first-message"
>}'

4. End Call

Programmatically end the ongoing call.

$curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control' 
$-H 'content-type: application/json' 
$--data-raw '{
>  "type": "end-call"
>}'

5. Transfer Call

Transfer the call to a different destination.

$curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control' 
$-H 'content-type: application/json' 
$--data-raw '{
>  "type": "transfer",
>  "destination": {
>    "type": "number",
>    "number": "+1234567890"
>  },
>  "content": "Transferring your call now"
>}'

You can also transfer to a SIP URI:

$curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control' 
$-H 'content-type: application/json' 
$--data-raw '{
>  "type": "transfer",
>  "destination": {
>    "type": "sip",
>    "sipUri": "sip:+transferPhoneNumber@sip.telnyx.com"
>  },
>  "content": "Testing transfer call."
>}'

6. Handoff Call

Handoff the call to a different assistant.

$curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control' 
$-H 'content-type: application/json' 
$--data-raw '{
>  "type": "handoff",
>  "destination": {
>    "type": "assistant",
>    "contextEngineeringPlan": "none",
>    "assistant": {
>        "name": "new_assistant",
>        "voice": {
>            "provider": "vapi",
>            "voiceId": "Neha"
>        },
>    }                                    
>  },
>  "content": "Handing off your call now"
>}'

Call Listen Feature

The listenUrl allows you to connect to a WebSocket and stream the audio data in real-time. You can either process the audio directly or save the binary data to analyze or replay later.

Example: Saving Audio Data from a Live Call

Here is a simple implementation for saving the audio buffer from a live call using Node.js:

1const WebSocket = require('ws');
2const fs = require('fs');
3
4let pcmBuffer = Buffer.alloc(0);
5
6const ws = new WebSocket("wss://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/transport");
7
8ws.on('open', () => console.log('WebSocket connection established'));
9
10ws.on('message', (data, isBinary) => {
11  if (isBinary) {
12    pcmBuffer = Buffer.concat([pcmBuffer, data]);
13    console.log(`Received PCM data, buffer size: ${pcmBuffer.length}`);
14  } else {
15    console.log('Received message:', JSON.parse(data.toString()));
16  }
17});
18
19ws.on('close', () => {
20  if (pcmBuffer.length > 0) {
21    fs.writeFileSync('audio.pcm', pcmBuffer);
22    console.log('Audio data saved to audio.pcm');
23  }
24});
25
26ws.on('error', (error) => console.error('WebSocket error:', error));