Make Outbound Call - API

Initiates an outbound SIP call using a configured SIP Gateway. The call is associated with a room, participant, and optional routing rule. Supports advanced options like DTMF, audio recording, call duration, and SIP headers.

HTTP method and endpoint

POST

|

https://api.videosdk.live/v2/sip/call

Headers Parameters

Authorization

REQUIRED

values : YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

Note that the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: Generate Auth token

Content-Type

REQUIRED

values : application/json

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.

Body Parameters

gatewayId

REQUIRED

ID of the outbound SIP gateway to use.

sipCallTo

REQUIRED

The destination phone number (E.164 format).

sipCallFrom

OPTIONAL

The caller ID number. Must be one of the numbers configured in the gateway. Defaults to the first number if not provided.

destinationRoomId

OPTIONAL

OPTIONAL. The room ID where the call will connect. If not provided, the roomId will be automatically derived from the outbound gateway’s routing rule configuration.

participant

OPTIONAL

Participant details (e.g., name, metadata) to be associated with the call.

recordAudio

OPTIONAL

Whether to record the call audio.

waitUntilAnswered

OPTIONAL

Wait until call is answered before connecting.

ringingTimeout

OPTIONAL

Maximum time (in seconds) to wait for the call to be answered before hanging up.

dtmf

OPTIONAL

DTMF digits to send automatically after call connects.

maxCallDuration

OPTIONAL

Maximum call duration in seconds.

mediaEncryption

OPTIONAL

Media encryption preference (e.g., SRTP). If not provided, defaults to gateway settings.

hidePhoneNumber

OPTIONAL

Mask phone number for privacy.

headers

OPTIONAL

Custom SIP headers to include in the call.

includeHeaders

OPTIONAL

List of SIP headers to include from inbound INVITE in response events.

metadata

OPTIONAL

Custom metadata associated with the call.

Response Parameters

message

Confirmation message about the call status.

data.callId

Unique ID of the call.

data.status

Current status of the call (e.g., INITIATED).

data.roomId

Room ID associated with the call.

data.sipCallTo

Destination number of the call.

data.sipCallFrom

Source number of the call.

data.gatewayId

Gateway ID used for the call.

data.metadata

Custom metadata associated with the call.

data.timelog

Array of status change logs with timestamps.

POST

|

https://api.videosdk.live/v2/sip/call

NodeJS

• cURL
• NodeJS
• PHP
• Python

import fetch from 'node-fetch';
const options = {
	method: "POST",
	headers: {
		"Authorization": "$YOUR_TOKEN",
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		"gatewayId" : "gw_123456789",
		"sipCallTo" : "+14155550123",
		"sipCallFrom" : "+14155559876",
		"destinationRoomId" : "room_123456",
		"participant" : {"name":"John Doe"},
		"recordAudio" : "true",
		"waitUntilAnswered" : "false",
		"ringingTimeout" : "30",
		"dtmf" : "1234#",
		"maxCallDuration" : "3600",
		"mediaEncryption" : "SRTP",
		"hidePhoneNumber" : "true",
		"headers" : {"X-Custom-Header":"my-value"},
		"includeHeaders" : ["User-Agent","X-Trace-Id"],
		"metadata" : {"campaignId":"cmp_123","source":"crm"}
	}),
};
const url= `https://api.videosdk.live/v2/sip/call`;
const response = await fetch(url, options);
const data = await response.json();
console.log(data);

RESPONSE

{
  "message": "Call initiated successfully",
  "data": {
    "callId": "call_123456789",
    "status": "INITIATED",
    "roomId": "room_123456",
    "sipCallTo": "+14155550123",
    "sipCallFrom": "+14155559876",
    "gatewayId": "gw_123456789",
    "metadata": {
      "campaignId": "cmp_123",
      "source": "crm"
    },
    "timelog": [
      {
        "status": "INITIATED",
        "timestamp": "2025-08-21T11:45:00.000Z"
      }
    ]
  }
}