Suggestions

close search

SIP Interconnect

You can use the OpenTok REST API to connect your SIP platform to OpenTok sessions. This lets you add audio from a SIP call as an audio-only stream in the OpenTok session. The audio from all other streams in the OpenTok session are mixed together and sent to your SIP endpoint.

The SIP interconnect feature is only supported in routed sessions (sessions that use the OpenTok Media Router).

This page includes the following sections:

Initiating a SIP call

To start the SIP call, use the OpenTok REST API. Make an HTTPS POST request to the following URL

https://api.opentok.com/v2/project/:apiKey/dial

Replace apiKey with your OpenTok API key.

Set the Content-Type header to application/json. Set a custom X-OPENTOK-AUTH header to a JSON Web token that is valid for use with the OpenTok REST API calls. See the section on OpenTok REST API call authentication.

Set the body of the request to JSON data of the following format:

{
  "sessionId": "OpenTok session ID",
  "token": "A valid OpenTok token",
  "sip": {
    "uri": "user@sip.partner.com;transport=tls",
    "headers": {
      "headerKey": "headerValue"
    },
    "auth": {
      "username": "username",
      "password": "password"
    },
    "secure": true|false
  }
}

The JSON object includes the following properties:

The JSON object includes the following properties:

The OpenTok SIP gateway sends a standard SIP INVITE to the address you provide in the REST call. When your SIP endpoint connects, it is added as a new Connection to the OpenTok session, and its audio is added to a new stream in the OpenTok session. The new connection is added immediately to the OpenTok session without waiting for the SIP endpoint to receive or accept the call. In clients connected to the session, the OpenTok client SDK dispatches events indication the new connection and stream (just as it would for other OpenTok connections and streams). Clients can subscribe to the stream, just as they would subscribe to any other stream in the session.

Terminating a SIP call

The call ends when your SIP server sends a BYE message (to terminate the call). You can also end a call using the OpenTok REST API method to disconnect a client from a session. Use the connection ID of the SIP call when calling this method. (The REST method for initiating the SIP call returns the connection ID as part of the response data.)

When the SIP call ends, the OpenTok connection and stream for the SIP call also ends. In each client connected to the session, the OpenTok client-side SDK dispatches events indicating the connection and stream ended (just as it would when other clients disconnect from the session).

The OpenTok SIP gateway automatically ends a call after 5 minutes of inactivity (5 minutes without media received). Also, as a security measure, the OpenTok SIP gateway closes any SIP call that lasts longer than 6 hours.

Security considerations

There are some best practices recommended by TokBox when using this new SIP Interface with your SIP Servers. They try to mitigate the possible attacks by providing the mechanisms to authenticate and authorize that the SIP calls received in your server are legitimate and to encrypt all the signaling and media:

If required, you can also block the traffic not coming from the IP addresses of the OpenTok SIP gateway. Contact support@tokbox.com for details on the IP addresses used by the OpenTok SIP gateway.

Technical details

RFC3550 (RTP/RTCP) support: Media traffic can be encrypted (SRTP) or non-­encrypted (plain RTP). In case of encryption, both DTLS and SDES protocols are supported.

Codec support: The OpenTok SIP gateway supports the OPUS, G.711, and G.722 audio codecs.

Signaling: The OpenTok SIP gateway supports RFC3561 (SIP) over UDP, TCP, and TLS. Contact TokBox if you need information or support for any specific extension.

The OpenTok SIP gateway will not accept any SIP message coming from the a third-party SIP platform unless it is part of a SIP dialog initiated by the OpenTok SIP gateway. Calls initiated with the OpenTok SIP gateway can be put on ­hold using either a re-­INVITE with the sendonly/inactive direction in the SDP or a re-­INVITE with port 0 in the SDP.

Other considerations: Early media is disabled, and DTMFs are not currently supported.

Sample applications

A small selection of server SDKs have sample integrations using SIP interconnect functionality. See examples at: