SIP Connect

SIP Connect allows you to connect any SIP-compatible device or softphone to a VideoSDK room. This guide explains how to configure SIP for your VideoSDK account and connect a SIP user to an existing meeting.

Architecture

The following diagram illustrates how SIP Connect works. A SIP user connects to the VideoSDK SIP Gateway, which then bridges the call to the VideoSDK Room.

Steps

In this guide, we are using Twilio as the SIP provider, but you can choose from other providers like Plivo, Exotel, Telnyx, Ozontel, etc. The configuration process is similar across most providers.

1. Create VideoSDK Meeting

1

Create VideoSDK Meeting

note

Ensure you have a VideoSDK meeting setup. If you don't have one, follow the Quick Start Guide to create a basic video calling app.

You can connect a SIP user to any active VideoSDK meeting. If you already have a meeting ID, you can proceed to the next step.

2. Create Inbound Gateway

2

Create Inbound Gateway

An Inbound Gateway is required to receive calls from a SIP provider (like Twilio, Vonage, Telnyx) and route them to VideoSDK.

Via Twilio

1. Go to the VideoSDK Dashboard.
2. Navigate to Telephony > Inbound Gateways.
3. Click Add Inbound Gateway.
4. Enter a name and the phone number you purchased from your SIP provider.
5. Click Create.
6. Copy the Inbound Gateway SIP URI (e.g., sip:orgId.sip.videosdk.live).
7. Configure this URI as the Origination SIP URI in your SIP provider's dashboard (e.g., Twilio, Vonage, Telnyx).

Via Vonage

1. Go to the VideoSDK Dashboard.
2. Navigate to Telephony > Inbound Gateways.
3. Click Add Inbound Gateway.
4. Enter a name and the phone number you purchased from Vonage.
5. Click Create.
6. Copy the Inbound Gateway SIP URI (e.g., sip:orgId.sip.videosdk.live).
7. In your Vonage Console, go to your SIP Trunk settings.
8. Under Inbound Calls, select your region.
9. In the URI section, paste the Inbound Gateway SIP URI you copied.
10. Link the phone number you purchased to this trunk.

Via Telnyx

1. Go to the VideoSDK Dashboard.
2. Navigate to Telephony > Inbound Gateways.
3. Click Add Inbound Gateway.
4. Enter a name and the phone number you purchased from Telnyx.
5. Click Create.
6. Copy the Inbound Gateway SIP URI (e.g., sip:orgId.sip.videosdk.live).
7. In your Telnyx Console, go to Connections and create a new SIP Connection.
8. Set the type as FQDN.
9. Under FQDN, add the VideoSDK Inbound Gateway SIP URI you copied.
10. Assign the phone number you purchased to this connection.

Via API

You can create an inbound gateway programmatically using the API.

cURL

curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Inbound Gateway",
    "numbers": ["+1234567890"]
  }'

API Reference: Create Inbound Gateway

3. Create Outbound Gateway

3

Create Outbound Gateway

An Outbound Gateway is used if you want to dial out to a SIP user from a VideoSDK meeting.

Via Twilio

1. Go to the VideoSDK Dashboard.
2. Navigate to Telephony > Outbound Gateways.
3. Click Add Outbound Gateway.
4. Enter a name.
5. Enter the Termination SIP URI provided by your SIP provider.
6. Enter the Username and Password for your SIP provider.
7. Click Create.

Via Vonage

1. Go to the VideoSDK Dashboard.
2. Navigate to Telephony > Outbound Gateways.
3. Click Add Outbound Gateway.
4. Enter a name.
5. Enter the Domain you set up in your Vonage SIP Trunk settings.
6. Enter the Username and Password you configured in Vonage under Outbound Calls.
7. Click Create.
8. Note: For outbound gateway numbers, do not use the + sign—just use the country code and number.

Via Telnyx

1. Go to the VideoSDK Dashboard.
2. Navigate to Telephony > Outbound Gateways.
3. Click Add Outbound Gateway.
4. Enter a name.
5. Enter the SIP Domain you configured in your Telnyx SIP Connection.
6. Enter the Username and Password you set up in Telnyx under Outbound Authentication.
7. Click Create.

Via API

cURL

curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Outbound Gateway",
    "numbers": ["+1234567890"],
    "address": "sip.provider.com",
    "auth": {
      "username": "sip_username",
      "password": "sip_password"
    }
  }'

API Reference: Create Outbound Gateway

4. Create Routing Rules

4

Create Routing Rules

Routing rules determine how calls are handled.

Inbound Routing

For inbound calls, you need to route the call to a specific meeting room.

1. Go to Telephony > Routing Rules.
2. Click Add Routing Rule.
3. Select your Inbound Gateway.
4. Select the Phone Number.
5. Under Dispatch, select Room.
6. Choose Dynamic (creates a new room) or Static (connects to a specific room ID).
7. Click Create.

Outbound Routing

For outbound calls, the routing rule selects which Outbound Gateway to use based on the dialed number.

1. Go to Telephony > Routing Rules.
2. Click Add Routing Rule.
3. Select your Outbound Gateway.
4. Enter the Phone Number pattern (e.g., +1*).
5. Click Create.

Connect SIP User

Inbound Call

Now that everything is configured, a SIP user can join the meeting by simply dialing the phone number configured in the Inbound Gateway.

1. The call reaches your SIP provider.
2. The provider forwards it to VideoSDK.
3. VideoSDK checks the Routing Rule.
4. The user is connected to the VideoSDK Room.

Outbound Call

To dial a SIP user from the meeting, you can use the dispatch API or the SDK method if available.

cURL

curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "outbound-gateway-id",
    "sipCallTo": "+1234567890",
    "destinationRoomId": "room-id"
  }'

API Reference: Make Outbound Call

Webhooks

You can configure webhooks to receive real-time updates about SIP calls.

Available Webhook Events

Below is the list of all supported webhook events:

Event Name	Description
call-started	Triggered when a new outbound or inbound call is initiated.
call-answered	Triggered when the call is answered by the recipient.
call-hangup	Triggered when the call is completed or hung up by either party.
call-transferred	Call transferred to another destination.
call-missed	Triggered when the call is not answered or missed by the recipient.
call-update	Triggered when there is an update in the call status.
call-ringing	Triggered when the call is ringing at the destination endpoint.
call-transfer-initiated	Call transfer has been initiated.
call-transfer-accepted	Call transfer has been accepted by the target.
call-transferring	Call is being transferred to another destination.
call-transfer-ringing	Call is ringing at the transfer target.
call-transfer-failed	Call transfer failed.

You can configure these in the Telephony > Webhooks section of the dashboard.

Configuring Webhooks

You can set up webhooks using:

• Dashboard: Navigate to the SIP section and add a webhook by specifying your target URL and selecting the events you want to subscribe to.
• API: Use the POST /v2/sip/webhooks endpoint to register a webhook.

POST

|

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

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({
		"url" : "https://example.com/webhook",
		"events" : ["call-started","call-answered"]
	}),
};
const url= `https://api.videosdk.live/v2/sip/webhooks`;
const response = await fetch(url, options);
const data = await response.json();
console.log(data);

API Reference

• Create Webhook API
• Fetch all Webhook API
• Fetch a Webhook API
• Update Webhook API
• Delete Webhook API