Create Routing Rule - API

Creates a new routing rule for a specific SIP gateway. A routing rule defines how inbound calls should be dispatched (to a room or agent).

HTTP method and endpoint

POST

|

https://api.videosdk.live/v2/sip/routing-rules

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

The ID of the gateway this routing rule belongs to.

name

REQUIRED

A descriptive name for the routing rule.

numbers

REQUIRED

Array of phone numbers associated with this rule.

dispatch

REQUIRED

Defines how calls should be dispatched, either to a VideoSDK room or to an agent. This provides flexibility in routing SIP calls based on your application needs.

• room : Route calls into a VideoSDK room.

  • type : "static"
  | "dynamic"
  • prefix : Optional prefix added before creating/joining the room.
  • id : Room ID (used when type = static).
  • pin : Optional room PIN for authentication.

• agent : Route calls to a specific agent.

  • type : "cloud"
  | "self"
  • id : Agent ID to receive the call.
  • metadata : Key-value metadata for context (e.g., { department: "sales" }).

hidePhoneNumber

OPTIONAL

Boolean flag to hide caller phone number when dispatching calls.

metadata

OPTIONAL

Custom metadata key-value pairs for this rule.

tags

OPTIONAL

Custom tags associated with the routing rule.

Response Parameters

id

Unique identifier of the routing rule.

name

Name of the routing rule.

type

Gateway type (e.g., inbound, outbound).

numbers

Numbers associated with this routing rule.

gatewayId

Associated gateway ID.

dispatch

Dispatch configuration (room/agent).

hidePhoneNumber

Whether the caller number is hidden.

metadata

Custom metadata key-value pairs.

tags

Tags for this routing rule.

POST

|

https://api.videosdk.live/v2/sip/routing-rules

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" : "gateway_in_123456789",
		"name" : "Support Line Rule",
		"numbers" : ["+14150001111","+14150002222"],
		"dispatch" : {"room":{"type":"dynamic","prefix":"prefix","id":"room_123","pin":"4321"},"agent":{"type":"cloud","id":"agent_789","metadata":{"department":"sales"}}},
		"hidePhoneNumber" : "false",
		"metadata" : {"env":"production"},
		"tags" : ["priority","support"]
	}),
};
const url= `https://api.videosdk.live/v2/sip/routing-rules`;
const response = await fetch(url, options);
const data = await response.json();
console.log(data);

RESPONSE

{
  "id": "rule_123456789",
  "name": "Support Line Rule",
  "type": "INBOUND",
  "numbers": [
    "+14150001111",
    "+14150002222"
  ],
  "gatewayId": "gateway_in_123456789",
  "dispatch": {
    "room": {
      "type": "dynamic",
      "prefix": "prefix",
      "id": "room_123",
      "pin": "4321"
    },
    "agent": {
      "type": "user",
      "id": "user_789",
      "metadata": {
        "department": "sales"
      }
    }
  },
  "hidePhoneNumber": false,
  "metadata": {
    "env": "production"
  },
  "tags": [
    "priority",
    "support"
  ]
}