Incoming Phone Numbers

IncomingPhoneNumbers

An IncomingPhoneNumber instance resource represents a Restcomm phone number.

The IncomingPhoneNumbers list resource represents an account’s Restcomm phone numbers. You can POST to the list resource to provision a new Restcomm number. To find a new number to provision use the subresources of the AvailablePhoneNumbers resource.

Provisioning a phone number is a two-step process. First, you must find an available phone number to provision using the subresources of the AvailablePhoneNumbers resource. Second, you must POST to the IncomingPhoneNumbers list resource, documented below.

IncomingPhoneNumber Instance Resource

Resource URI

/2012-04-24/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}

Resource Properties

Property

Description

Sid

A 34 character string that uniquely identifies this resource.

DateCreated

The date that this resource was created, given as GMT RFC 2822 format.

DateUpdated

The date that this resource was last updated, given as GMT RFC 2822 format.

FriendlyName

A human readable descriptive text for this resource, up to 64 characters long. By default, the FriendlyName is a nicely formatted version of the phone number.

AccountSid

The unique id of the Account responsible for this phone number.

PhoneNumber

The incoming phone number. e.g., +16175551212 ( E.164 format)

ApiVersion

Calls to this phone number will start a new RCML session with this API version.

VoiceCallerIdLookup

Look up the caller’s caller-ID name from the CNAM database ($0.01 per look up). Either true or false.

VoiceUrl

The URL Restcomm will request when this phone number receives a call.

VoiceMethod

The HTTP method Restcomm will use when requesting the above Url. Either GET or POST.

VoiceFallbackUrl

The URL that Restcomm will request if an error occurs retrieving or executing the RCML requested by Url.

VoiceFallbackMethod

The HTTP method Restcomm will use when requesting the VoiceFallbackUrl. Either GET or POST.

StatusCallback

The URL that Restcomm will request to pass status parameters (such as call ended) to your application.

StatusCallbackMethod

The HTTP method Restcomm will use to make requests to the StatusCallback URL. Either GET or POST.

VoiceApplicationSid

The 34 character sid of the application Restcomm should use to handle phone calls to this number. If a VoiceApplicationSid is present, Restcomm will ignore all of the voice urls above and use those set on the application.

VoiceApplicationName

The application name.

SmsUrl

The URL Restcomm will request when receiving an incoming SMS message to this number.

SmsMethod

The HTTP method Restcomm will use when making requests to the SmsUrl. Either GET or POST.

SmsFallbackUrl

The URL that Restcomm will request if an error occurs retrieving or executing the RCML from SmsUrl.

SmsFallbackMethod

The HTTP method Restcomm will use when requesting the above URL. Either GET or POST.

SmsApplicationSid

The 34 character SID of the application Restcomm should use to handle SMS sent to this number. If a SmsApplicationSid is present, Restcomm will ignore all of the SMS urls above and use those set on the application.

SmsApplicationName

The application name.

ReferUrl

The URL Restcomm will request when receiving a SIP Refer request to this number.

ReferMethod

The HTTP method Restcomm will use when making requests to the ReferUrl. Either GET or POST.

ReferApplicationSid

The 34 character sid of the application Restcomm should use to handle SIP Refer requests to this number. If a ReferApplicationSid is present, Restcomm will ignore all of the Refer urls above and use those set on the application.

ReferApplicationName

The application name.

Capabilities

This is a set of boolean properties that indicate whether a phone number can receive calls or messages. Possible capabilities are Voice, SMS, and MMS with each having a value of either true or false.

Uri

The URI for this resource, relative to \https://$DOMAIN/api/2012-04-24/.

HTTP Methods

HTTP GET

HTTP POST and PUT

Tries to update the incoming phone number’s properties, and returns the updated resource representation if successful. The returned response is identical to that returned above when making a GET request.

Optional Parameters

You may specify one or more of the following parameters to update this phone number’s respective properties:

Parameter

Description

FriendlyName

A human readable description of the new incoming phone number resource, with maximum length 64 characters.

ApiVersion

Calls to this phone number will start a new RCML session with this API version - 2012-04-24

VoiceUrl

The URL that Restcomm should request when somebody dials the phone number.

VoiceMethod

The HTTP method that should be used to request the VoiceUrl. Either GET or POST.

VoiceFallbackUrl

A URL that Restcomm will request if an error occurs requesting or executing the RCML defined by VoiceUrl.

VoiceFallbackMethod

The HTTP method that should be used to request the VoiceFallbackUrl. Either GET or POST.

StatusCallback

The URL that Restcomm will request to pass status parameters (such as call ended) to your application.

StatusCallbackMethod

The HTTP method Restcomm will use to make requests to the StatusCallback URL. Either GET or POST.

VoiceCallerIdLookup

Do a lookup of a caller’s name from the CNAM database and post it to your app. Either true or false.

VoiceApplicationSid

SmsUrl

The URL that Restcomm should request when somebody sends an SMS to the new phone number.

SmsMethod

The HTTP method that should be used to request the SmsUrl. Either GET or POST.

SmsFallbackUrl

A URL that Restcomm will request if an error occurs requesting or executing the RCML defined by SmsUrl.

SmsFallbackMethod

The HTTP method that should be used to request the SmsFallbackUrl. Either GET or POST.

SmsApplicationSid

AccountSid

The unique 34 character id of the account to which you wish to transfer this phone number.

statusCallback

With IncomingPhoneNumber statusCallback, you can subscribe to receive webhooks for different events on the incoming phone number.

The statusCallback events are:

RINGING
IN_PROGRESS
COMPLETED

statusCallbackMethod

The statusCallbackMethod attribute allows you to specify which HTTP method Restcomm should use when requesting the URL in the statusCallback attribute. The default is POST.

Status Callback HTTP Parameters

The Restcomm parameters passed to your application in its asynchronous request to the StatusCallback URL include all parameters passed in a synchronous request to retrieve RCML when CPaaS receives a call to one of your numbers. The full list of parameters can be found in the RCML Voice Request documentation Request Parameters.

When the call progress events are fired, the Status Callback request also passes these additional parameters:

Parameter Description

Parameter	Description
OutboundCallSid	optional - A unique identifier for the outbound leg of this call
ForwardedFrom	optional A string that represents the number that the call was forwarded from
Timestamp	The timestamp when the event was fired in a UTC RFC 2822 format.
ReferTarget	optional A string that describes the transfer target, if this call started by a transfer
Transferor	optional A string that describes the transferor, if this call started by a transfer
Transferee	optional A string that describes the transferee, if this call started by a transfer
SequenceNumber	The order in which the events were fired, starting from `0`. Although events are fired in order, they are made as separate HTTP requests and there is no guarantee they will arrive in the same order.

OutboundCallSid

optional - A unique identifier for the outbound leg of this call

ForwardedFrom

optional A string that represents the number that the call was forwarded from

Timestamp

The timestamp when the event was fired in a UTC RFC 2822 format.

ReferTarget

optional A string that describes the transfer target, if this call started by a transfer

Transferor

optional A string that describes the transferor, if this call started by a transfer

Transferee

optional A string that describes the transferee, if this call started by a transfer

SequenceNumber

The order in which the events were fired, starting from 0. Although events are fired in order, they are made as separate HTTP requests and there is no guarantee they will arrive in the same order.

HTTP DELETE

Release this phone number from your account. Restcomm will no longer answer calls to this number, and you will stop being billed the monthly phone number fee. The phone number will eventually be recycled and potentially given to another customer, so use with care. If you make a mistake, contact us. We may be able to give you the number back. If successful, returns an HTTP 204 response with no body.

IncomingPhoneNumbers List Resource

Resource URI

/2012-04-24/Accounts/{AccountSid}/IncomingPhoneNumbers

HTTP Methods

HTTP GET

Returns a list of IncomingPhoneNumber resource representations, each representing a phone number given to your account. The list includes paging information.

List Filters

The following query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

Parameter

Description

PhoneNumber

Only show the incoming phone number resources that match this pattern. You can specify partial numbers and use '*' as a wildcard for any digit.

FriendlyName

Only show the incoming phone number resources with friendly names that exactly match this name.

Beta

Include phone numbers new to the Restcomm platform. Possible values are either true or false. Default is true.

Example - List of phone numbers

Gets all numbers created using IncomingPhoneNumbers.json

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/IncomingPhoneNumbers.json  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/IncomingPhoneNumbers.json");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Result of the above command

[
  {
    "sid": "PN0b4201c6c87749f29367e6cf000686cb",
    "account_sid": "\{account_sid}",
    "friendly_name": "This app calls registered client Alice ",
    "phone_number": "+1238",
    "voice_url": "/restcomm/demos/dial/client/dial-client.xml",
    "voice_method": "POST",
    "voice_fallback_url": null,
    "voice_fallback_method": "POST",
    "status_callback": null,
    "status_callback_method": "POST",
    "voice_caller_id_lookup": false,
    "voice_application_sid": null,
    "date_created": "Mon, 4 Nov 2013 12:14:11 +0000",
    "date_updated": "Mon, 4 Nov 2013 12:14:11 +0000",
    "sms_url": null,
    "sms_method": "POST",
    "sms_fallback_url": null,
    "sms_fallback_method": "POST",
    "sms_application_sid": null,
    "refer_url": null,
    "refer_method": null,
    "refer_application_sid": null,
    "capabilities": {
      "voice_capable": true,
      "sms_capable": false,
      "mms_capable": false,
      "fax_capable": false
    },
    "api_version": "2012-04-24",
    "uri": "/api/2012-04-24/Accounts/\{account_sid}/IncomingPhoneNumbers/PN0b4201c6c87749f29367e6cf000686cb.json"
  },...

HTTP POST

Purchases a new phone number for your account. If a phone number is found for your request, Restcomm will add it to your account and bill you for the first month’s cost of the phone number. If Restcomm cannot find a phone number to match your request, you will receive an HTTP 400 with Restcomm error code. To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.

Required Parameters

Your request must include exactly one of the following parameters:

Parameter

Description

PhoneNumber

The phone number you want to purchase. The number should be formatted starting with a '+' followed by the country code and the number inhttp://en.wikipedia.org/wiki/E.164[E.164] format e.g., '+15105555555'. You must include either this or an AreaCode parameter to have your POST succeed.

AreaCode

The desired area code for your new incoming phone number. Any three digit, US or Canada area code is valid. Restcomm will provision a random phone number within this area code for you. You must include either this or a PhoneNumber parameter to have your POST succeed. (US and Canada only)

If you include both parameters, we will use the AreaCode parameter and ignore the PhoneNumber provided.

Optional Parameters

Your request may include the following parameters:

Parameter

Description

FriendlyName

A human readable description of the new incoming phone number. Maximum 64 characters. Defaults to a formatted version of the number.

VoiceUrl

The URL that Restcomm should request when somebody dials the new phone number.

VoiceMethod

The HTTP method that should be used to request the VoiceUrl. Must be either GET or POST. Defaults to POST.

VoiceFallbackUrl

A URL that Restcomm will request if an error occurs requesting or executing the RCML at Url.

VoiceFallbackMethod

The HTTP method that should be used to request the VoiceFallbackUrl. Either GET or POST. Defaults to POST.

StatusCallback

The URL that Restcomm will request to pass status parameters (such as call ended) to your application.

StatusCallbackMethod

The HTTP method Restcomm will use to make requests to the StatusCallback URL. Either GET or POST. Defaults to POST.

VoiceCallerIdLookup

Do a lookup of a caller’s name from the CNAM database and post it to your app. Either true or false. Defaults to false.

VoiceApplicationSid

The 34 character sid of the application Restcomm should use to handle phone calls to the new number. If a VoiceApplicationSid is present, Restcomm will ignore all of the voice urls above and use those set on the application.

SmsUrl

The URL that Restcomm should request when somebody sends an SMS to the phone number.

SmsMethod

The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST.

SmsFallbackUrl

A URL that Restcomm will request if an error occurs requesting or executing the RCML defined by SmsUrl.

SmsFallbackMethod

The HTTP method that should be used to request the SmsFallbackUrl. Must be either GET or POST. Defaults to POST.

SmsApplicationSid

The 34 character SID of the application Restcomm should use to handle SMS sent to the new number. If a SmsApplicationSid is present, Restcomm will ignore all of the SMS urls above and use those set on the application.

ApiVersion

The Restcomm REST API version to use for incoming calls made to this number. If omitted, uses 2012-04-24.

If successful, Restcomm responds with a representation of the new phone number that was assigned to your account.

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Local IncomingPhoneNumber Factory Resource

POSTing to this resource allows you to request a new local phone number be added to your account. This subresource represents only Local phone numbers.

Resource URI

/2012-04-24/Accounts/{YourAccountSid}/IncomingPhoneNumbers/Local

HTTP Methods

HTTP GET

Returns a list of local <IncomingPhoneNumber> elements, each representing a local (not toll-free) phone number given to your account, under an <IncomingPhoneNumbers> list element that includes paging information. Works exactly the same as the IncomingPhoneNumber resource, but filters out toll-free numbers.

HTTP POST

Adds a new phone number to your account. If a phone number is found for your request, Restcomm will add it to your account and bill you for the first month’s cost of the phone number. If Restcomm can’t find a phone number to match your request, you will receive an HTTP 400 with Restcomm error code. To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.

Required Parameters

Your request must include PhoneNumber. We do not support AreaCode for this subresource:

Parameter

Description

PhoneNumber

Optional Parameters

The optional parameters for this request are exactly the same as POSTing directly to the IncomingPhoneNumbers/ resource. If successful, Restcomm responds with a representation of the new phone number that was assigned to your account.

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Toll-Free IncomingPhoneNumber Factory Resource

This subresource represents only toll-free phone numbers. POSTing to this resource allows you to request a new toll-free phone number be added to your account.

Resource URI

/2012-04-24/Accounts/{YourAccountSid}/IncomingPhoneNumbers/TollFree

HTTP Methods

HTTP GET

Returns a list of local <IncomingPhoneNumber> elements, each representing a toll-free phone number given to your account, under an <IncomingPhoneNumbers> list element that includes paging information. Works exactly the same as the IncomingPhoneNumber resource, but filters out all numbers that aren’t toll-free.

HTTP POST

Required Parameters

Your request must include PhoneNumber. We do not support AreaCode for this subresource:

Parameter

Description

PhoneNumber

The phone number you want to purchase. The number should be formatted starting with a '+' followed by the country code and the number in E.164 format e.g., '+15105555555'. You must include this to have your POST succeed.

Optional Parameters

The optional parameters for this request are exactly the same as POSTing directly to the IncomingPhoneNumbers/ resource. If successful, Restcomm will respond with a representation of the new phone number that was assigned to your account.

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Mobile IncomingPhoneNumber Factory Resource

POSTing to this resource allows you to request a new mobile phone number be added to your account. This subresource represents only mobile phone numbers, i.e. not toll free numbers or local numbers.

Resource URI

/2012-04-24/Accounts/{YourAccountSid}/IncomingPhoneNumbers/Mobile

HTTP Methods

HTTP GET

Returns a list of local <IncomingPhoneNumber> elements, each representing a mobile phone number given to your account, under an <IncomingPhoneNumbers> list element that includes paging information. Works exactly the same as the IncomingPhoneNumber resource, but filters out local and toll free numbers.

HTTP POST

Required Parameters

Your request must include PhoneNumber. We do not support AreaCode for this subresource:

Parameter

Description

PhoneNumber

Optional Parameters

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Attach a phone number to an application

Attach a DID phone number to an application

This one uses the default application

curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/IncomingPhoneNumbers.json  \
   -d 'PhoneNumber=+15105555555' \
   -d 'VoiceUrl=https://mycompany.com/restcomm/demos/hello-play.xml' \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request.({
      method: 'POST',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN },
      form: {
         'PhoneNumber': '+15105555555',
         'VoiceUrl': 'https://mycompany.com/restcomm/demos/hello-play.xml'
      }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
});

from http.client import HTTPSConnection
from base64 import b64encode
from urllib.parse import urlencode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass,
    'Content-type': 'application/x-www-form-urlencoded',
    'Accept': 'text/plain' }

# Update POST parameters accordingly
params = urlencode({
   'PhoneNumber': '+15105555555',
   'VoiceUrl': 'https://mycompany.com/restcomm/demos/hello-play.xml'
})

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("POST", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      params, headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL(("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/IncomingPhoneNumbers.json");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("POST");
      conn.setDoOutput(true);
      DataOutputStream os = new DataOutputStream(conn.getOutputStream());

      // Update POST parameters accordingly
      os.writeBytes("PhoneNumber=+15105555555&" +
        "VoiceUrl=https://mycompany.com/restcomm/demos/hello-play.xml");
      os.close();

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Result of the above command

{
  "sid": "PNdd7a0a0248244615978bd5781598e5eb",
  "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
  "friendly_name": "15105555555",
  "phone_number": "+15105555555",
  "voice_url": "https://127.0.0.1/restcomm/demos/hello-play.xml",
  "voice_method": "POST",
  "voice_fallback_method": "POST",
  "status_callback_method": "POST",
  "voice_caller_id_lookup": false,
  "date_created": "2013-10-04T17:42:02.500-06:00",
  "date_updated": "2013-10-04T17:42:02.500-06:00",
  "sms_method": "POST",
  "sms_fallback_method": "POST",
  "api_version": "2012-04-24",
  "uri": "/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/IncomingPhoneNumbers/PNdd7a0a0248244615978bd5781598e5eb.json"

If you are trying to attach a number that is Virtual (SIP Number) and not attached to a particular DID provider, you need to add -D "isSIP=true" as shown below

Attach a SIP Virtual number to an application

This one uses the default application

curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/IncomingPhoneNumbers.json  \
   -d 'PhoneNumber=1234' \
   -d 'VoiceUrl=https://mycompany.com/restcomm/demos/hello-play.xml' \
   -d 'isSIP=true' \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request.({
      method: 'POST',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN },
      form: {
         'PhoneNumber': '1234',
         'VoiceUrl': 'https://mycompany.com/restcomm/demos/hello-play.xml',
         'isSIP': 'true'
      }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
});

from http.client import HTTPSConnection
from base64 import b64encode
from urllib.parse import urlencode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass,
    'Content-type': 'application/x-www-form-urlencoded',
    'Accept': 'text/plain' }

# Update POST parameters accordingly
params = urlencode({
   'PhoneNumber': '1234',
   'VoiceUrl': 'https://mycompany.com/restcomm/demos/hello-play.xml',
   'isSIP': 'true'
})

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("POST", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      params, headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL(("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/IncomingPhoneNumbers.json");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("POST");
      conn.setDoOutput(true);
      DataOutputStream os = new DataOutputStream(conn.getOutputStream());

      // Update POST parameters accordingly
      os.writeBytes("PhoneNumber=1234&" +
        "VoiceUrl=https://mycompany.com/restcomm/demos/hello-play.xml&" +
        "isSIP=true");
      os.close();

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Result of the above command

{
  "sid": "PNdd7a0a0248244615978bd5781598e5eb",
  "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
  "friendly_name": "234",
  "phone_number": "+1234",
  "voice_url": "https://127.0.0.1/restcomm/demos/hello-play.xml",
  "voice_method": "POST",
  "voice_fallback_method": "POST",
  "status_callback_method": "POST",
  "voice_caller_id_lookup": false,
  "date_created": "2013-10-04T17:42:02.500-06:00",
  "date_updated": "2013-10-04T17:42:02.500-06:00",
  "sms_method": "POST",
  "sms_fallback_method": "POST",
  "api_version": "2012-04-24",
  "uri": "/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/IncomingPhoneNumbers/PNdd7a0a0248244615978bd5781598e5eb.json"

Enable Incoming MMS for an Application

As part of the Omnichannel Messaging API, you may create an IncomingPhoneNumber to trigger your application from various Messaging Channels. The number will be created as a SIP, and the Phone Number property will correspond to the Omnichannel URI. When a new message is received from the Channel network, the SMS Url will trigger your application. You can create multiple IncomingPhoneNumbers matching different Omnichannel URIs, and trigger the same application.

Sending an MMS

curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/IncomingPhoneNumbers.json  \
   -d 'PhoneNumber=mms:+12345678' \
   -d 'SmsUrl=https://mycompany.com/api/demos/echo.xml' \
   -d 'isSIP=true' \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request.({
      method: 'POST',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN },
      form: {
         'PhoneNumber': 'mms:+12345678',
         'SmsUrl': 'https://mycompany.com/api/demos/echo.xml',
         'isSIP': 'true'
      }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
});

from http.client import HTTPSConnection
from base64 import b64encode
from urllib.parse import urlencode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass,
    'Content-type': 'application/x-www-form-urlencoded',
    'Accept': 'text/plain' }

# Update POST parameters accordingly
params = urlencode({
   'PhoneNumber': 'mms:+12345678',
   'SmsUrl': 'https://mycompany.com/api/demos/echo.xml',
   'isSIP': 'true'
})

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("POST", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      params, headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL(("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/IncomingPhoneNumbers.json");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("POST");
      conn.setDoOutput(true);
      DataOutputStream os = new DataOutputStream(conn.getOutputStream());

      // Update POST parameters accordingly
      os.writeBytes("PhoneNumber=mms:+12345678&" +
        "SmsUrl=https://mycompany.com/api/demos/echo.xml&" +
        "isSIP=true");
      os.close();

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Example Response

{
  "sid": "PNdd7a0a0248244615978bd5781598e5eb",
  "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
  "friendly_name": "MMSApp",
  "phone_number": "mms:+12345678",
  "sms_url": "https://yourcompany.com/api/demos/echo.xml",
  "sms_method": "POST",
  "voice_fallback_method": "POST",
  "status_callback_method": "POST",
  "voice_caller_id_lookup": false,
  "date_created": "2013-10-04T17:42:02.500-06:00",
  "date_updated": "2013-10-04T17:42:02.500-06:00",
  "api_version": "2012-04-24",
  "uri": "/api/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/IncomingPhoneNumbers/PNdd7a0a0248244615978bd5781598e5eb.json"
}

Delete a phone number

You have to get the SID of the phone and use curl to delete as follows

curl -X DELETE https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/IncomingPhoneNumbers/PHONENUMBER_SID.json  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';
// Provide additional path parameters if applicable
const PHONENUMBER_SID = 'my_PHONENUMBER_SID'

request({
      method: 'DELETE',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers/' + PHONENUMBER_SID + '.json',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'
// Provide additional path parameters if applicable
PHONENUMBER_SID = 'my_PHONENUMBER_SID'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("DELETE", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers/' + PHONENUMBER_SID + '.json',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";
   // Provide additional path parameters if applicable
   public static final String PHONENUMBER_SID = "my_PHONENUMBER_SID"

   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/IncomingPhoneNumbers/" + PHONENUMBER_SID + ".json");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("DELETE");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

List of phone numbers

Gets all numbers created using IncomingPhoneNumbers.json

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/IncomingPhoneNumbers.json  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/IncomingPhoneNumbers.json',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/IncomingPhoneNumbers.json");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Incoming Phone Number Regex Support

Logic

The following diagram depicts the main logic regarding incoming phone numbers, and regular expressions during an actual call:

:Retrieve Number from DB (In IncomingOrganization);

if (Number Matched?) then (yes)
  :Trigger linked Application;
else (no)
  if (IncomingOrganization != null?) then (yes)
    :Retrieve Regexes In IncomingOrganization;
    :Sort Regexes by Length;
    repeat
      if (Number Matched?) then (yes)
        :Trigger linked Application;
      endif
    repeat while (more regexes || !matched?)
  else (no)
    :No application found;
  endif
endif

As we can see, the perfect match against the incoming number will be attempted first. Then, if no matching is found the regular expressions associated to the Organization will be evaluated.

Regex has been disabled for incoming SMPP/SMS messages because SMPP is not supporting Organizations.

Regular Expression examples

The following table provides examples on how the logic is exercised depending on current contents of DB.

IncomingPhoneNumber

DB Table

Description

16508251255

"16508251255" "16.*"

Perfect match against "16508251255"

16508251255

"16508251256" "16.*"

No Perfect match found. regex "16.*" applies

16508251255

"16508251256" "16.*","16508.*"

No Perfect match found. longest regex "16508.*" applies

The following table provides examples on how a single regular expression may match different numbers.

Regex Sample

Description

7777\8888

Matches the numbers 7777 or 8888

^*77…33#$

Matches any number that starts with *77 and and the three dots matches any character and it must end with a # sign

^[12]2233#$

Matches any number that starts with 1 or 2 and ends with 2233#

^7688[456]#$

matches any number that starts with 76884# or 76885# or 76886#

[45]234[23]

matches 42342, 42343, 52342 and 52343

^222…*…*500#$

the Regext (^222…*…*500#$) matches *222*888*999*500# or *222*444*321*500# the dots maches any character

999…

Matches 999222, 999123, 999555 the dots matches any character

Resource URI

/2012-04-24/Accounts/{TargetAccountSid}/IncomingPhoneNumbers/migrate

HTTP Methods

HTTP POST

Migrates all numbers of TargetAccountSid’s account tree to provided destination organization. Only super admins have permission to perform this operation.

This operation will impact all child accounts in downwards hierarchy.

Required Parameters

Your request must include OrganizationSid.

Parameter

Description

OrganizationSid

Sid of destination organization, where we want to migrate numbers.

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Distributed Request Processing

The CPaaS platform has a distributed microservice architecture, that enables linear scalability during traffic growth and handles a high volume of REST API requests, voice calls, and SMS messages. Each architecture component handles different types of requests.

When you modify the provisioning data via the Management REST APIs, up to few minutes are needed for the update to reflect the changes in all call processing units that handle calls and SMS. Provisioning data modifications are done using the HTTP POST, PUT and DELETE methods. The POST method updates records immediately with no delay during the operation.

Distributed request processing is available for the following Management APIs, as well as the CPaaS Console.