SIP

Nexmo is now called Vonage, but there are still references to Nexmo in our URLs, code snippets and message templates.

Introduction

Use Session Initiation Protocol (SIP) to forward inbound voice calls and send outbound voice calls. Session Initiation Protocol (SIP) in general is used for initiating, maintaining and terminating real-time sessions that include voice, video and messaging applications. SIP is used for signaling and controlling multimedia communication sessions in applications of Internet telephony for voice and video calls, in private IP telephone systems, in instant messaging over Internet Protocol (IP) networks as well as mobile phone calling over LTE (VoLTE).

The protocol defines the specific format of messages exchanged and the sequence of communications for cooperation of the participants. A call established with SIP may consist of multiple media streams. No separate streams are required for applications, such as text messaging, that exchange data as payload in the SIP message.

Definitions

Endpoint

You can send your INVITE request to the Nexmo SIP endpoint: sip.nexmo.com

Service records

A Service record (SRV record) is a specification of data in the Domain Name System defining the location, i.e. the hostname and port number, of servers for specified services

A SRV record has the form:

_service._proto.name. TTL class SRV priority weight port target.

• service: the symbolic name of the desired service.

• proto: the transport protocol of the desired service; this is usually either TCP or UDP.

• name: the domain name for which this record is valid, ending in a dot.

• TTL: standard DNS time to live field.

• class: standard DNS class field (this is always IN).

• priority: the priority of the target host, lower value means more preferred.

• weight: A relative weight for records with the same priority, higher value means more preferred.

• port: the TCP or UDP port on which the service is to be found.

• target: the canonical hostname of the machine providing the service, ending in a dot.

Example: _sip._tcp.example.com. 86400 IN SRV 0 5 5060 sipserver.example.com.

Recipient

Recipient numbers must be numbers following the E.164 format.

Example: +31622222222

Caller ID

Set the Caller Line Identity (CLI) in the From header using E.164 format.

For example: sip:447700900000@sip.nexmo.com.

Codecs

The following codecs are supported:

• PCMA (G711a)

• PCMU (G711u)

• iLBC

• g729 (without annexb)

• g722

• Speex16

Media traffic

The list of IPs/subnets is subject to change. Rather than white-listing specific subnets, open traffic from all IP ranges to port range 10000:20000.

DTMF

Nexmo supports out-of-band DTMF. For more information, see RFC2833.

Health checks

Use the OPTIONS method to run a health check on our SIP trunks.

Protocols

You can use the following protocols:

• UDP on port 5060

• TCP on port 5060

• TLS on port 5061

Transport Layer Security (TLS) is a cryptographic protocol designed to provide communications security to your SIP connection. You can use self-signed certificates on your user agent, Nexmo does not validate the certificate on the client side.

Prerequisites

• To use this API, you need to already have access to Vonage's

  Phone Numbers API

  .

Constraints

Nexmo SIP endpoint: sip.nexmo.com

Default timeout value is 5000ms

Default port for traffic 5061

Connections using TLS 1.0 or more recent are accepted. Older protocols are disabled as they are considered insecure.

Resources

SIP request methods

SIP Service records

If your system is not enabled for Service records (SRV records), you should load balance between the two closest endpoints and set the remaining ones as backup. The Nexmo SIP endpoints are:

• sip-us1.nexmo.com (Washington)

• sip-us2.nexmo.com (Washington)

• sip-eu1.nexmo.com (London)

• sip-eu2.nexmo.com (London)

• sip-ap1.nexmo.com (Singapore)

• sip-ap2.nexmo.com (Singapore)

• sip-us-2-1.nexmo.com (Dallas)

• sip-us-2-2.nexmo.com (Dallas)

Inbound configuration

Configuring your system for SIP forwarding

To configure for SIP forwarding:

1. Configure your phone number to use SIP forwarding by updating your phone number configuration using Nexmo - Phone Numbers API.

2. Call the /update endpoint setting the following parameters: voiceCallbackType and voiceCallbackValue to SIP and a valid SIP URI respectively.

   Example:

   
   curl -X POST "https://api-prd.kpn.com/communication/nexmo/phone-numbers/number/update" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "country=XX&msisdn=31XXXXXXXXX&moHttpUr=https://example.com/mo&moSmppSysType=inbount&voiceCallbackType=sip&voiceCallbackValue=sip:1234@example.com&voiceStatusCallback="
   

3. You can specify a timeout for non responding SIP endpoints, by appending a ;timeout=xxxxx to the related URI. Timeouts are expressed in milliseconds and can range from 2000 to 20000. This is useful to quickly failover when an endpoint is temporarily unavailable. The default value is 5000 ms.

   TLS for inbound connections is supported. To enable this, append ;transport=tls to your SIP URI.

   Example: sip:1234@example.com;transport=tls

   The default port (5061) can be changed by appending :new_port to the end of your domain or IP address.

   Example: sip:1234@example.com:5062;transport=tls

4. Ensure that the traffic generated from the following IP addresses can pass your firewall:

   • 173.193.199.24

   • 174.37.245.34

   • 5.10.112.121

   • 5.10.112.122

   • 119.81.44.6

   • 119.81.44.7

   • 169.60.141.29

   • 169.60.141.30

Example configurations

Asterisk

Inbound configuration

[nexmo-sip]
fromdomain=sip.nexmo.com
type=peer
context=nexmo
insecure=port,invite
nat=no
; Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw
allow=alaw
allow=G729
dtmfmode=rfc2833

[nexmo-sip-01](nexmo-sip)
host=173.193.199.24

[nexmo-sip-02](nexmo-sip)
host=174.37.245.34

[nexmo-sip-03](nexmo-sip)
host=5.10.112.121

[nexmo-sip-04](nexmo-sip)
host=5.10.112.122

[nexmo-sip-05](nexmo-sip)
host=119.81.44.6

[nexmo-sip-06](nexmo-sip)
host=119.81.44.7

[nexmo-sip-07](nexmo-sip)
host=169.60.141.29

[nexmo-sip-08](nexmo-sip)
host=169.60.141.30

Outbound configuration

[general]
register => <key>:<secret>@sip.nexmo.com
[nexmo]
username=<key>
host=sip.nexmo.com
defaultuser=<key>
fromuser=<long_virtual_number>
fromdomain=sip.nexmo.com
secret=<secret>
type=peer
context=nexmo
insecure=very
qualify=yes
nat=no
; Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw
allow=alaw
allow=G729
dtmfmode=rfc2833

Asterisk version 12+ with chan_pjsip

; Basic UDP only endpoint.
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0
[nexmo]
type = endpoint
aors = nexmo
outbound_auth = nexmo-auth
context = inbound
transport=transport-udp
from_user = <long_virtual_number> ; This is optional. CLI can be set in the dialplan
allow=alaw
allow=ulaw
allow=g729
[nexmo]
type = aor
contact = sip:sip.nexmo.com
qualify_frequency = 120
[nexmo-auth]
type = auth
auth_type = userpass
username = <key>
password = <secret>
[nexmo-reg]
type = registration
outbound_auth = nexmo-auth
server_uri = sip:sip.nexmo.com
client_uri = sip:<key>@sip.nexmo.com
[nexmo-identify]
type = identify
endpoint = nexmo
match = 5.10.112.122
match = 5.10.112.121
match = 173.193.199.24
match = 174.37.245.34
match = 119.81.44.6
match = 119.81.44.7
match = 169.60.141.29
match = 169.60.141.30

Avaya SBCe

The document linked below describes how to set up Nexmo's SIP service with Avaya SBCe

Avaya Configuration Guide

Cisco CUCM/CUBE

The document linked below describes how to set up Nexmo's SIP service with CISCO CUCM/CUBE.

CISCO CUCM/CUBE Configuration Guide

FreePBX

Inbound configuration

host=173.193.199.24
type=friend
insecure=port,invite
;Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

host=174.37.245.34
type=friend
insecure=port,invite
;Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

host=5.10.112.121
type=friend
insecure=port,invite
;Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

host=5.10.112.122
type=friend
insecure=port,invite
;Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

host=119.81.44.6
type=friend
insecure=port,invite
;Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

host=119.81.44.7
type=friend
insecure=port,invite
;Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

host=169.60.141.29
type=friend
insecure=port,invite
;Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

host=169.60.141.30
type=friend
insecure=port,invite
;Add your codec list here.
; Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

Outbound configuration

host=sip.nexmo.com
type=friend
insecure=port,invite
qualify=yes
;Add your codec list here.
;Note: Use "ulaw" for US only, "alaw" for the rest of the world.
allow=ulaw,alaw,g729
dtmfmode=rfc2833

username=<key>
fromuser=<long_virtual_number>
secret=<secret>

Register String
<key>:<secret>@sip.nexmo.com

PJSIP configuration

For PJSIP configuration use the following information:

FreeSWITCH

Inbound configuration Modify autoload_configs/acl.conf.xml and allow traffic from Nexmo's IPs:

<list name="nexmo" default="deny">
<node type="allow" cidr="173.193.199.24/32"/>
<node type="allow" cidr="174.37.245.34/32"/>
<node type="allow" cidr="5.10.112.121/32"/>
<node type="allow" cidr="5.10.112.122/32"/>
<node type="allow" cidr="119.81.44.6/32"/>
<node type="allow" cidr="119.81.44.7/32"/>
<node type="allow" cidr="169.60.141.29/32"/>
<node type="allow" cidr="169.60.141.30/32"/>
</list>

Add the following to sip_profiles/internal.xml:

Create a public dial plan for Nexmo in dialplan/public/nexmo_sip.xml:

<include>
<extension name="nexmo_sip">
<condition field="destination_number" expression="^(\d+)$">
<action application="set" data="domain_name=$${domain}"/>
<action application="transfer" data="1000 XML default"/>
</condition>
</extension>
</include>

If you want to match a specific number from request URI, modify the expression: (\d+)

> This forwards incoming calls to registered extension 1000.

Outbound configuration

Create an external profile:

<include>
<gateway name="nexmo">
<param name="proxy" value="sip.nexmo.com"/>
<param name="register" value="true"/>
<param name="caller-id-in-from" value="false"/>
<param name="from-user" value="<long_virtual_number>"/>
<param name="username" value="<key>"/>
<param name="password" value="<secret>"/>
</gateway>
</include>

Make a dial plan:

<include>
<extension name="international.mycompany.com">
<condition field="destination_number" expression="^(00\d+)$">
<action application="set" data="effective_caller_id_number=${outbound_caller_id_number}"/>
<action application="set" data="effective_caller_id_name=${outbound_caller_id_name}"/>
<action application="bridge" data="{origination_caller_id_name=<CALLER_ID>}sofia/gateway/nexmo/$1"/>
</condition>
</extension>
</include>

MiTel MiVoice and MiTel Border Gateway

The document linked below describes how to set up Nexmo's SIP service with MiTel MiVoice and MiTel Border Gateway.

MiTel MiVoice and MiTel Border Gateway Configuration Guide

ShoreTel Director and InGate SIParator

The document linked below describes how to set up Nexmo's SIP service with ShoreTel Director 14.2 and InGate SIParator 5.0.11.

ShoreTel Director and InGate SIParator Configuration Guide

Skype for Business with Oracle E-SBC

The document linked below describes how to set up Nexmo's SIP service with Skype for Business 6.0.9319 with Oracle E-SBC Acme Packet 3820

Skype for Business with Oracle E-SBC Acme Packet Configuration Guide

NEC SV9100

The document linked below describes how to set up Nexmo's SIP service with NEC SV9100 version 6.00.50

NEC SV9100 Configuration Guide

Return codes

1xx - Provisional responses

100 Trying

Extended search being performed may take a significant time so a forking proxy must send a 100 Trying response.

180 Ringing

Destination user agent received INVITE, and is alerting user of call.

181 Call is Being Forwarded

Servers can optionally send this response to indicate a call is being forwarded.

182 Queued

Indicates that the destination was temporarily unavailable, so the server has queued the call until the destination is available. A server may send multiple 182 responses to update progress of the queue.

183 Session Progress

This response may be used to send extra information for a call which is still being set up.

199 Early Dialog Terminated

Can be used by User Agent Server to indicate to upstream SIP entities (including the User Agent Client (UAC)) that an early dialog has been terminated.

2xx - Successful Responses

200 OK

Indicates the request was successful.

202 Accepted (Deprecated)

Indicates that the request has been accepted for processing, but the processing has not been completed.

204 No Notification

Indicates the request was successful, but the corresponding response will not be received.

3xx - Redirection responses

300 Multiple Choices

The address resolved to one of several options for the user or client to choose between, which are listed in the message body or the message's Contact fields.

301 Moved Permanently

The original Request-URI is no longer valid, the new address is given in the Contact header field, and the client should update any records of the original Request-URI with the new value.

302 Moved Temporarily

The client should try at the address in the Contact field. If an Expires field is present, the client may cache the result for that period of time.

305 Use Proxy

The Contact field details a proxy that must be used to access the requested destination.

380 Alternative Service

The call failed, but alternatives are detailed in the message body.

4xx - Client failure responses

400 Bad Request

The request could not be understood due to malformed syntax.

401 Unauthorized

The request requires user authentication. This response is issued by UASs and registrars.

402 Payment Required

Reserved for future use.

403 Forbidden

The server understood the request, but is refusing to fulfill it. the receiver.

404 Not Found

The server has definitive information that the user does not exist at the domain specified in the Request-URI. This status is also returned if the domain in the Request-URI does not match any of the domains handled by the recipient of the request.

405 Method Not Allowed

The method specified in the Request-Line is understood, but not allowed for the address identified by the Request-URI.

406 Not Acceptable

The resource identified by the request is only capable of generating response entities that have content characteristics but not acceptable according to the Accept header field sent in the request.

407 Proxy Authentication Required

The request requires user authentication. This response is issued by proxys.

408 Request Timeout

Couldn't find the user in time. The server could not produce a response within a suitable amount of time, for example, if it could not determine the location of the user in time. The client MAY repeat the request without modifications at any later time.

409 Conflict (Deprecated)

User already registered. Deprecated by omission from later RFCs

410 Gone

The user existed once, but is not available here any more.

411 Length Required (Deprecated)

The server will not accept the request without a valid Content-Length. Deprecated by omission from later RFCs non-registration with the IANA.

412 Conditional Request Failed

The given precondition has not been met.

413 Request Entity Too Large

Request body too large.

414 Request-URI Too Long

The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.

415 Unsupported Media Type

Request body in a format not supported.

416 Unsupported URI Scheme

Request-URI is unknown to the server.

417 Unknown Resource-Priority

There was a resource-priority option tag, but no Resource-Priority header.

420 Bad Extension

Bad SIP Protocol Extension used, not understood by the server.

421 Extension Required

The server needs a specific extension not listed in the Supported header.

422 Session Interval Too Small

The received request contains a Session-Expires header field with a duration below the minimum timer.

423 Interval Too Brief

Expiration time of the resource is too short.

424 Bad Location Information

The request's location content was malformed or otherwise unsatisfactory.

428 Use Identity Header

The server policy requires an Identity header, and one has not been provided.

429 Provide Referrer Identity

The server did not receive a valid Referred-By token on the request. A specific flow to a user agent has failed, although other flows may succeed. This response is intended for use between proxy devices, and should not be seen by an endpoint (and if it is seen by one, should be treated as a 400 Bad Request response).

433 Anonymity Disallowed

The request has been rejected because it was anonymous.

436 Bad Identity-Info

The request has an Identity-Info header, and the URI scheme in that header cannot be dereferenced.

437 Unsupported Certificate

The server was unable to validate a certificate for the domain that signed the request.

438 Invalid Identity Header

The server obtained a valid certificate that the request claimed was used to sign the request, but was unable to verify that signature.

439 First Hop Lacks Outbound Support

The first outbound proxy the user is attempting to register through does not support the "outbound" feature of RFC 5626, although the registrar does.

440 Max-Breadth Exceeded

If a SIP proxy determines a response context has insufficient Incoming Max-Breadth to carry out a desired parallel fork, and the proxy is unwilling/unable to compensate by forking serially or sending a redirect, that proxy MUST return a 440 response. A client receiving a 440 response can infer that its request did not reach all possible destinations.

469 Bad Info Package

If a SIP UA receives an INFO request associated with an Info Package that the UA has not indicated willingness to receive, the UA MUST send a 469 response, which contains a Recv-Info header field with Info Packages for which the UA is willing to receive INFO requests.

470 Consent Needed

The source of the request did not have the permission of the recipient to make such a request.

480 Temporarily Unavailable

Callee currently unavailable.

481 Call/Transaction Does Not Exist

Server received a request that does not match any dialog or transaction.

482 Loop Detected

Server has detected a loop.

483 Too Many Hops

Max-Forwards header has reached the value '0'.

484 Address Incomplete

Request-URI incomplete.

485 Ambiguous

Request-URI is ambiguous.

486 Busy Here

Callee is busy.

487 Request Terminated

Request has terminated by bye or cancel.

488 Not Acceptable Here

Some aspect of the session description or the Request-URI is not acceptable, or Codec issue.

489 Bad Event

The server did not understand an event package specified in an Event header field.

491 Request Pending

Server has some pending request from the same dialog.

493 Undecipherable

Request contains an encrypted MIME body, which recipient can not decrypt.

494 Security Agreement Required

The server has received a request that requires a negotiated security mechanism, and the response contains a list of suitable security mechanisms for the requester to choose between, or a digest authentication challenge.

5xx - Server Failure Responses

500 Server Internal Error

The server could not fulfill the request due to some unexpected condition.

501 Not Implemented

The server does not have the ability to fulfill the request, such as because it does not recognize the request method. (Compare with 405 Method Not Allowed, where the server recognizes the method but does not allow or support it.)

502 Bad Gateway

The server is acting as a gateway or proxy, and received an invalid response from a downstream server while attempting to fulfill the request.

503 Service Unavailable

The server is undergoing maintenance or is temporarily overloaded and so cannot process the request. A "Retry-After" header field may specify when the client may reattempt its request.

504 Server Time-out

The server attempted to access another server in attempting to process the request, and did not receive a prompt response.

505 Version Not Supported

The SIP protocol version in the request is not supported by the server.

513 Message Too Large

The request message length is longer than the server can process.

580 Precondition Failure

The server is unable or unwilling to meet some constraints specified in the offer.

6xx - Global Failure responses

600 Busy Everywhere

All possible destinations are busy. Unlike the 486 response, this response indicates the destination knows there are no alternative destinations (such as a voicemail server) able to accept the call.

603 Decline

The destination does not wish to participate in the call, or cannot do so, and additionally the destination knows there are no alternative destinations (such as a voicemail server) willing to accept the call.

604 Does Not Exist Anywhere

The server has authoritative information that the requested user does not exist anywhere.

606 Not Acceptable

The user's agent was contacted successfully but some aspects of the session description such as the requested media, bandwidth, or addressing style were not acceptable.

607 Unwanted

The called party did not want this call from the calling party. Future attempts from the calling party are likely to be similarly rejected

Sources

List of SIP response codes
List of SIP request methods
Session Initiation Protocol
Nexmo SIP Trunk Overview
SRV Record