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:

Intro to SIP

OpenTok SIP Interconnect enables interoperability between WebRTC endpoints and existing telephony systems so that users can make in-context SIP-based audio calls, while simultaneously browsing the website or mobile application.

Note: OpenTok SIP Interconnect supports only audio through the SIP interface. It does not currently support video. All the existing functionality of OpenTok, such as multiparty sessions and archiving, are compatible with OpenTok SIP Interconnect. OpenTok SIP Interconnect does not include any built-in PSTN functionality.

OpenTok SIP Architechture

Target Use-cases

Contact center use-case

PSTN Fallback

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": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "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.

Monitoring call progress (beta)

Register to receive real-time event callbacks for your SIP call on your app server.

Developers can use the OpenTok REST API to connect their SIP platform to OpenTok sessions. This lets you add audio from a SIP call as an audio-only stream in the OpenTok session. With SIP call monitoring, developers can monitor the progress of the SIP call, from within their app server. By registering for callbacks, your callback URL will receive HTTP POST requests with information about the progress of the SIP call.

Registering callbacks

SIP call events information can be registered to HTTP endpoints within your server. Whenever registered activity occurs, an HTTP request is issued from the OpenTok infrastructure to your endpoint.

To register a callback URL:

  1. Visit your TokBox account page.

  2. Select the OpenTok project for which you want to register a callback.

  3. Set the callback URL in the SIP Monitoring section.

Monitoring SIP call activity

Once properly registered, the OpenTok infrastructure sends HTTP requests for all SIP calls for a specific project. This is useful for tracking progress of SIP calls and taking action if an error occurs. You should expect:

Call Created

Your endpoint will receive the following JSON for each SIP call created:

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456", 
  "event":  "callCreated",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

See JSON properties below for descriptions.

Call Updated

Your endpoint will receive the following JSON when the state of each SIP call updates:

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456",
  "event":  "callUpdated",
  "state":  "HANGUP",
  "timestamp":  1470257688309,
  "call": {
     "id":  "<conference-id>",
     "connectionId":  "<sip-ot-connection-id>",
     "createdAt":  1470257688143
  }
}

See JSON properties below for descriptions.

Call Destroyed

Your endpoint will receive the following JSON when each SIP call ends:

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456",
  "event":  "callDestroyed",
  "reason_code":  "400",
  "reason_message":  "Bad Request",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

See JSON properties below for descriptions.

JSON properties of SIP monitoring events

The JSON object includes the following properties:

Security considerations

There are some best practices recommended by TokBox when using the 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 OpenTok. Here are the IP addresses of the OpenTok SIP gateway:

52.41.63.240
52.41.63.241
52.51.63.17
52.51.63.18
52.200.60.19
52.200.60.20

Contact support@tokbox.com if you have additional questions.

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

The OpenTok server SDKs for Node and PHP have sample OpenTok Dial API calls using the OpenTok SIP interconnect functionality. See examples at:

Below, you will find sample SIP Integrations using OpenTok SIP Interconnect with Plivo and Twilio:

FAQ

What is SIP? Why is SIP important?

The Session Initiation Protocol (SIP) is a communications protocol for signaling and controlling multimedia communication sessions. The most common applications of SIP are in Internet telephony for voice and video calls, as well as instant messaging, over Internet Protocol (IP) networks.

In our case it is used to establish a call from OpenTok sessions to a third-party SIP server. Once the call is established, the audio is sent using the RTP protocol.

What is the difference between SIP and PSTN? Does OpenTok provide a PSTN gateway?

The PSTN is the traditional telephone network. PSTN is not an IP network and doesn’t use SIP, but many providers, such as Telefonica, Twilio, and Plivo have gateways to convert SIP protocols to PSTN protocols. That way a SIP call over IP is converted to a phone call.

In practical terms, even if TokBox doesn’t support PSTN calls, we enable it by supporting SIP calls. From there it is just a matter of finding a provider to convert SIP calls to PSTN calls.

Can I call regular telephones with OpenTok SIP Interconnect feature?

OpenTok SIP Interconnect allows partners to initiate calls to any SIP endpoints. To make/receive calls to/from a regular phone, customers need a gateway on their side to convert the SIP call to the protocols used in mobile/fixed telephony networks.

Is there a way to handle dial-out to or dial-in from a regular phone number (PSTN)?

With OpenTok SIP Interconnect, customers can dial-out from an OpenTok session to any SIP destination. Furthermore, customers can configure a SIP gateway (their own or 3rd-party) to dial-out to a regular phone number.

Although the SIP Interconnect API does not support incoming SIP calls, customers can implement dialing in from a regular phone (PSTN) by using a SIP gateway (their own or 3rd-party) to bridge the incoming call received from regular phones with the dial-out SIP call coming from OpenTok. You can find sample applications demonstrating the conferencing use case here.

Does OpenTok SIP Interconnect support sending video?

No, it supports audio only. You could have multiple participants in an OpenTok session with video, but the participants joining that session using SIP will send and receive only audio.

Is there a noticeable difference in the perceived audio quality on the WebRTC endpoint vs. the SIP endpoint?

The expectation is to have the same quality, albeit with additional latency on the SIP endpoint.

How does the Archiving feature work with OpenTok SIP Interconnect?

The archiving capability works exactly as it does today for a WebRTC session. The first 9 streams, including a SIP audio stream, will be part of the Archive.

How does the user navigate the IVR? Will there be a dial pad in the web/mobile app?

Currently our client SDKs do not support Dual Tone Multiple Frequencies (DTMFs) required to support Interactive Voice Response (IVR) systems.

What SIP servers is OpenTok SIP Interconnect compatible with?

We have tested interoperability with some of the most popular telco equipment (ACME packet, Broadsoft), some popular SIP platforms (Twilio, Plivo), and the most popular open-source SIP server (freeswitch). It is impossible to ensure interoperability with every single SIP server, but we try to limit the use of SIP extensions/features to reduce the chances of failure. So far, we never had to change our solution to interoperate with any new SIP server.

How can one disconnect a call to a SIP client connected to an OpenTok session?