Handling Inbound Calls with VideoSDK

Inbound SIP calls allow you to connect external phone numbers or SIP endpoints (from providers like Twilio, Vonage, Plivo, Telnyx, etc.) directly to your VideoSDK meetings. This enables seamless participation of traditional telephony users in your web-based meetings.

Understanding Inbound Flow

Inbound SIP Flow

The diagram above illustrates the end-to-end flow for handling inbound SIP calls with VideoSDK:

User Initiates Call:

A user dials a phone number using their phone or SIP device.

SIP Provider Receives Call:

The call is received by your SIP provider (such as Twilio, Plivo, Telnyx, or Vonage).

Forward to VideoSDK:

The SIP provider is configured to forward the call to your organization’s VideoSDK SIP URI (e.g., orgId.sip.videosdk.live).

Inbound Gateway:

The call reaches the Inbound Gateway in VideoSDK, which acts as the entry point for all SIP traffic.

Routing Rules:

The Inbound Gateway applies your configured Routing Rules to determine how the call should be handled. Routing will be decided based on the number.

VideoSDK Cloud:

Based on the routing, the call is:
- Connected to a User: The SIP user is joined into a VideoSDK meeting room with other participants.
- Dispatchs an AI Agent: An AI agent is dispatched to the the same roo.

This architecture allows you to flexibly connect traditional telephony users to modern VideoSDK-powered meetings or AI agents, using your preferred SIP provider and custom routing logic.

Lets now setup the inbound calls.

Configure an Inbound Gateway

Configure your provider

To receive inbound calls, you must first configure an Inbound Gateway in VideoSDK. The Inbound Gateway acts as the entry point for SIP calls from your provider.

SIP Provider Setup:

Configure your SIP provider to send calls to VideoSDK using the following SIP URI format:
```
sip:$YOUR_ORG_ID.sip.videosdk.live
```
Replace $YOUR_ORG_ID with your actual VideoSDK organization ID.
note
If you want to restrict calls to a specific region, you can use:
sip:$YOUR_ORG_ID.<region>.sip.videosdk.live
Available regions:
- in1 → India
- us2 → US

Create Inboung Gateway

Create the inbound gateway by providing the number from your SIP provider. This will act as an entry point for you incoming SIP Calls.

Setup Routing Rules

Once your inbound gateway is configured, you need to define Routing Rules. Routing rules determine how incoming calls are dispatched—either to a VideoSDK room or to a specific agent.

Routing Rule Configuration:
- Gateway: Select the inbound gateway you created.
- Number: Specify the phone number(s) associated with this rule.
- Dispatch: Choose how calls should be routed.
Room Configuration:
- Dynamic: A new room is created for each call. You can customize the room ID using a prefix:
  - random: Generates a random room ID for each call.
  - participant number: Uses the caller's phone number as part of the room ID.
  - SIP number: Uses the SIP number (the number you purchased) as part of the room ID.
- Static: All calls are routed to a fixed, pre-defined room.

Configure using Dashboard

Configure using APIs

You can also create an inbound gateway using the API:

POST

https://api.videosdk.live/v2/sip/inbound-gateways

import fetch from 'node-fetch';
const options = {
	method: "POST",
	headers: {
		"Authorization": "$YOUR_TOKEN",
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		"name" : "Twilio Inbound Gateway",
		"numbers" : ["+11234567890","+19876543210"]
	}),
};
const url= `https://api.videosdk.live/v2/sip/inbound-gateways`;
const response = await fetch(url, options);
const data = await response.json();
console.log(data);

Once the inbound gateway and routing rules are set up, your VideoSDK project is ready to accept inbound SIP connections. Incoming calls will be routed to the configured room or agent as per your rules.

tip

All configurations can be managed via the VideoSDK dashboard or automated using the VideoSDK API. For detailed information on each API endpoint, refer to the VideoSDK API Documentation.

API Reference

Inbound Gateway APIs

Routing Rule APIs

Got a Question? Ask us on discord

Understanding Inbound Flow​

Configure an Inbound Gateway​

Configure your provider​

Create Inboung Gateway​

Setup Routing Rules​

Configure using Dashboard​

Configure using APIs​

API Reference​

Inbound Gateway APIs​

Routing Rule APIs​