Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

SIP Interconnect

You can use the OpenTok REST API to connect your SIP platform to OpenTok sessions. This lets you add audio (and, optionally, video) from a SIP call as a stream in the OpenTok session. The audio from other streams in the OpenTok session are mixed together and sent to your SIP endpoint. If you include video in the SIP call, the video from the other participant's streams (up to 9) are arranged in a grid layout and sent as as a single video stream 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 calls, while simultaneously browsing the website or mobile application.

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,
    "video": true|false,
    "observeForceMute": true|false,
    "streams": ["stream-id-1", "stream-id-2"]
  }
}

The JSON object includes the following properties:

A successful call results in a HTTP 200 response, with the connection ID and stream ID included in the JSON response data:

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
  "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036",
}

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 (and video, if included) 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.

Sending DTMF signals

You can send DTMF (Dual-tone multi-frequency) signals to SIP endpoints using the REST API. See Sending DTMF digits to SIP clients.

Telephony events are negotiated over SDP and transmitted as RFC4733/RFC2833 digits to the remote endpoint.

Monitoring call progress

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 (and video, if included) from a SIP call as a 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 Vonage Video API 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.

    Secure callbacks: You can secure webhook callback requests with signed callbacks, using a signature secret. See Secure callbacks.

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.

Mute Forced

Your endpoint will receive the following JSON when a SIP call is muted due to a force mute moderation event:

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

See JSON properties below for descriptions.

Note that you must set the observeForceMute option (to true) when creating the SIP connection to have it observe a force mute moderation event.

JSON properties of SIP monitoring events

The JSON object includes the following properties:

Security considerations

There are some best practices recommended by Vonage 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:

Contact us 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; and the H.264 and VP8 video codecs.

Signaling: The OpenTok SIP gateway supports RFC 3261 (SIP) over UDP, TCP, and TLS. Contact Vonage 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.

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 Nexmo:

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 (and video, if included) 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 Nexmo, 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 the Vonage Video API 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?

Yes. Set the video flag to true when initiating the SIP call using the REST API method.

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. Up to 16 video streams and the first 50 audio streams, including SIP audio and video streams, will be part of the archive.

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

You can use the REST API to send DTMF signals to SIP clients to support Interactive Voice Response (IVR) systems. See Sending DTMF signals.

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 (Nexmo, and others), 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?

Known issue

When a SIP video call is made to a Linphone SIP client, and the video call is negotiated on VP8 codec, the incoming video from Linphone to the OpenTok SIP gateway appears as black frames.