SIP Outbound

Overview

100ms’ SIP bridge allows you to bridge participants on SIP calls by using a third-party service (like Twilio, Telnyx) into your 100ms room.

A SIP outbound trunk enables customers to set up credentials for outbound communication from 100ms room.

This documentation details the steps to create and update a SIP outbound trunk for outbound communication, as well as to initiate an outbound call. It includes API endpoints and sample JSON payloads for these procedures.

Create an outbound trunk - Provision 100ms room for SIP dial-out

This API allows you to set up a dedicated trunk and generate a trunk_id which is required before initiating an outbound call from a 100ms room.

Most SIP trunks provide a username and password for authentication along with a SIP address. Additionally, you are also required to purchase a phone number from the PSTN to the SIP service provider. For our example requests and tests, we’ve used Twilio.

Request

API Endpoint

POST https://api.100ms.live/v2/sip/outbound/trunks

//Request Body
{
    "username": "<USERNAME>",
    "password": "<PASSWORD>",
    "address": "<trunk-name>.pstn.twilio.com", // Twilio has been used as an example. This could be any SIP trunk provider's address.
    "from": "+971667*****"
}

Request arguments

These credentials are used for authentication when bridging the call between the SIP Trunk and 100ms' SIP bridge. They are usually provided by all major service providers. For Twilio, follow these steps:

1. Create an account on Twilio.
2. Get a phone number. Refer this.
3. Create a SIP Credential Resource - username and password.
4. Get the address → Twilio Documentation

Response

{
    "id": "4a3b7c9d91"
}

Trunk Object

Initiating an outbound call

This API initiates a SIP call from a 100ms room to the SIP destination.

The API will be blocked and will not share a response until the caller has either received or denied the call. In case, you want to initiate another call from the same trunk, the API can be called again.

Request

API Endpoint

POST https://api.100ms.live/v2/sip/outbound/call

Headers: Authorization: Bearer <Management Token>

//Request body
{
    "to": "+971776656",
    "name": "Alex",
    "user_id": "",
    "room_code": "xxx-xxxx-xxx",
    "trunk_id": "4a3b7c9d91",
    "video": true,
    "headers": {
        "x-language-id": "5",
        "x-mrn": "1234567"
    }
}

Request cURL Example

curl --location --request POST 'https://api.100ms.live/v2/sip/outbound/call' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <MANAGEMENT TOKEN>' \
--data '{
	"to": "+16692418750", // Phone Number
	"name": "Alex",       // Name shown when the peer accepts the call and joins the room through SIP
	"user_id": "",
	"room_code": "***-abc-***",
    "trunk_id": "65c6700f340713c4f7d*****",
    "video": true,
    "headers": {                       // Optional custom SIP headers (see below)
        "x-language-id": "5",
        "x-mrn": "1234567"
    }
}

'

Request Arguments

To get a room code, refer to the following documentation:

1. Getting room codes from the dashboard and authentication
2. Room Code API

Response

{
    "id": "a8b7c9d9e7f74" // This is the call ID
}

Error Responses

Passing custom SIP headers

Some SIP destinations need extra context on the call to route it correctly. A common example is a language-interpreter service that decides which interpreter to connect based on headers on the incoming SIP INVITE.

You can pass this context using the optional headers field on the Initiating an outbound call request. Each key/value pair is attached as a header on the outgoing SIP INVITE, so the destination receives it verbatim.

//Request body (partial)
{
    ...
    "headers": {
        "x-language-id": "5",
        "x-mrn": "1234567",
        "x-provider-name": "Dr. Gregory House"
    }
}

The exact header names and expected values are defined by your SIP destination/provider — check their integration guide for the headers they support.

We recommend prefixing custom headers with X- (the SIP convention for non-standard headers). This is not strictly required by 100ms, but it avoids collisions with reserved headers, and many SIP providers only forward X--prefixed headers to their application layer.

Update an outbound trunk

This API allows you to update an existing outbound trunk in case of any changes in the SIP trunk credentials, SIP address, or phone number.

Request

API Endpoint

POST https://api.100ms.live/v2/sip/outbound/trunks/:trunkId

//Request Body
{
    "username": "<USERNAME>",
    "password": "<PASSWORD>",
    "address": "xx.pstn.twilio.com",
    "from": "+1667666****"
}

Response

{
	"id": "4a3b7c9d91"
}

Trunk Object