Reference Turnkey Applications Tutorials Visual Designer
Reference Turnkey Applications Tutorials Visual Designer
    • REST API
      • Overview
      • API Endpoint
      • Authentication
      • Requests
      • Responses
      • Paging
      • Reason Codes Dictionary
    • Management APIs
      • Accounts
      • Identity Access Management BETA
        • Identity Access Management Overview
        • Identity Access Management API
          • User Management
            • Create a User
            • Update a User
            • Retrieve a User
            • Delete a User
          • API Keys Management
            • Create an API Key
            • Update an API Key
            • Retrieve an API Key
            • Delete an API Key
      • Applications
      • Clients
        • Create a Client
        • Delete a Client
        • Change Client’s Password
        • Get a List of Available Clients
      • Incoming Phone Numbers
        • IncomingPhoneNumber Instance Resource
        • IncomingPhoneNumbers List Resource
        • Local IncomingPhoneNumber Factory Resource
        • Toll-Free IncomingPhoneNumber Factory Resource
        • Mobile IncomingPhoneNumber Factory Resource
        • Attach a phone number to an application
        • Enable Incoming MMS for an Application
        • Delete a phone number
        • List of Phone Numbers
        • Incoming Phone Number Regex Support
      • Notifications
      • Usage Records
      • Trace Records
    • Voice
      • Calls
        • Call List Resource URI
        • Making a Call
        • Modifying Live Calls
        • Examples
        • List Filter
        • Paging Information
      • Conference Management
        • Supported Operations
        • Conference List Resource URI
      • Conference Participants Management
        • Participants List Resource URI
      • Gather DTMF
      • Gather Speech
      • Say
      • Play
      • Hold
      • Recordings
      • Refers
        • Resource Properties
        • Supported Operations
        • Paging Information
      • Resume
      • SIP Refer Support
    • Messages API - BETA
      • Overview
      • Channel Identities
      • Send Message
      • Status Callback Parameters
      • Status Callback Events
      • Receive Message
        • Incoming Message Request Parameters
      • Get Message List
      • Get Single Message
      • Message Attributes
      • Status Description
    • SMS
      • Messages
        • Send SMS
        • Get SMS List
        • Get single SMS Information
        • SMS Attributes
      • Error Codes
    • Email
    • RCML
      • Overview
        • Interacting with Your Application
        • RCML Verbs
      • Dial
        • Client
        • Conference
        • Number
        • SIP
      • Email
      • Gather
      • Say
      • Play
      • SMS
      • Message - Beta
      • Hold
      • Resume
      • Hangup
      • Pause
      • Redirect
      • Record
      • Reject
      • Refer
    • Visual Designer API
      • List Application Templates
      • :List a Specific Application Template
      • Create a Visual Designer Application
      • Get Application Details
      • Save Application Changes
      • Create Application Parameters
      • List Application Parameters
      • Delete Application Parameters
      • Upload Application Media Files
      • List Application Media Files
      • Play Application Media Files
      • Delete Application Media Files
      • Get Application Logs
      • Delete Application Logs
      • Get Application Settings
      • Modify Application Settings
      • Rename an Application
      • Delete an Application
      • Get Visual Designer Configuration
    • Turnkey Apps APIs
      • Smart 2FA
        • Sending One-Time Passwords
        • Verifying One-Time Passwords
        • Cancel One-Time Passwords
        • Session Detail Record (SDR)
        • Get list of One-Time Passwords
        • Get a Single One-Time Password
        • Usage Record One-Time Passwords
        • Common Response Error Code
        • Limit
          • Create Limit
          • Update Limit
          • Delete Limit
          • Get List of Limits
      • Call Queuing
      • Auto Attendant
        • Users
        • Announcement
        • Auto Attendant System
        • Menu
        • Schedule
        • Phone Number
        • Usage Records
        • Third Party Integration
      • Number Masking
        • Application
        • Mask Number Pool
        • Context
        • Participants
        • Interactions
        • Usage Records
      • Task Router
docs 1.0
  • docs
    • 1.0
  • docs
  • Enterprise:Management APIs
  • Enterprise:Clients

Clients

Clients

A Client represents a user agent that can make and receive calls as well as send and receive text messages using the Restcomm Cloud. This means that you can configure any software or hardware VoIP phone with the Client Username and Password in order to register with Restcomm Cloud. Once you do that you will be able to do things like:

  • Call or text any Restcomm Number to trigger the associated Voice or SMS Application. Notice that you first need to setup the Application with the logic you want and associate it with a Restcomm Number. For more information please check here.

  • Call out to any PSTN number

  • Send SMS to any mobile number

  • Call or text any other registered Client

The Client can also be associated with a Restcomm Application, either in the form of Visual Designer Application or externally hosted. If that is the case then this application will be called no matter what digits the user of the VoIP phone dials

Client Resource URI

/2012-04-24/Accounts/{AccountSid}/Clients/{ClientSid}

  • Using SIP User Agents. When using Restcomm to handle SIP user agent you have to create a new Client resource, this resource acts as an account for your user agent and also dictates how calls made by the user agent should be handled.

  • Client without VoiceUrl Restcomm has a new implied behavior when VoiceUrl is not provided for a Client account. Restcomm will proxy calls from such Clients to the destination Client (only if registered) or to the destination Application DID.

Only registered Clients are allowed to use the B2BUA/P2P/Proxy functionalities of Restcomm. Proxying and P2P calls are only allowed between registered(authenticated) Clients.

The CDR records generated for calls made by Clients, will have account SID the account that the Client belongs to.

Clients Attributes

Attribute Description

Sid

A string that uniquely identifies this client.

DateCreated

The date that this client was created.

DateUpdated

The date that this clientr was last updated.

FriendlyName

A friendly name for this client.

AccountSid

The unique id of the Account that owns this client.

ApiVersion

Calls to this client will create a new RCML session with this API version.

Login

The name that is used inside the <Client> noun. This is also used by the user agent as the user name used for registration and outbound dialing. This must conform to "userinfo" part as defined in RFC2396.

Password

The password used by the user agent during registration and outbound dialing.

Status

The client status the possible values are 0 for disabled and 1 for enabled.

VoiceUrl

The URL Restcomm will request when this client makes an outbound 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 execution of VoiceUrl fails for any reason.

VoiceFallbackMethod

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

VoiceApplicationSid

If this entry contains an Sid to a voice application then Restcomm will ignore these voice URLs and use the voice URLs specified by the voice application.

Uri

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

Supported Operations

HTTP GET. Returns the representation of an Client resource, including the properties above.

HTTP POST/PUT. Modifies a Client resource and returns the representation, including the properties above. Below you will find a list of optional parameters.

Request Parameters

Parameter Description

FriendlyName

A formatted version of this client.

Password

The password used by the user agent during registration and outbound dialing.

Status

The client status the possible values are 0 for disabled and 1 for enabled.

VoiceUrl

The URL Restcomm will request when this client 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 execution of VoiceUrl fails for any reason.

VoiceFallbackMethod

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

VoiceApplicationSid

If this entry contains an Sid to a voice application then Restcomm will ignore these voice URLs and use the voice URLs specified by the voice application.

HTTP DELETE. Deletes a Client from the user’s Account.

Client List Resource

Client List Resource URI.

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

Supported Operations

HTTP GET. Returns the list representation of all the Client resources for this Account, including the properties above.

HTTP POST. Creates a new Client and returns the representation of the resource, including the properties above. Below you will find a list of required and optional parameters.

Request Parameters

Parameter Description

FriendlyName

A formatted version of this client.

Login

The name that is used inside the <Client> noun.This is also used by the user agent as the username used for registration and outbound dialing.

Password

The password used by the user agent during registration and outbound dialing.

Status

The client status the possible values are 0 for disabled and 1 for enabled.

VoiceUrl

The URL Restcomm will request when this client makes an outbound 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 execution of VoiceUrl fails for any reason.

VoiceFallbackMethod

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

VoiceApplicationSid

If this entry contains an Sid to a voice application then Restcomm will ignore these voice URLs and use the voice URLs specified by the voice application.

Create a Client

The client name will be Alice as shown below

curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Clients.json  \
   -d 'Login=alice' \
   -d 'Password=test' \
   -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 + '/Clients.json',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN },
      form: {
         'Login': 'alice',
         'Password': 'test'
      }
   },
   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({
   'Login': 'alice',
   'Password': 'test'
})

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("POST", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Clients.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 + "/Clients.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("Login=alice&" +
        "Password=test");
      os.close();

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

The output of the command will be similar to the one below

{
  "sid": "CL4e10e3b56a614414bcc1eeca5d96effe",
  "date_created": "2013-10-16T08:51:32.460-06:00",
  "date_updated": "2013-10-16T08:51:32.460-06:00",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "2012-04-24",
  "friendly_name": "alice",
  "login": "alice",
  "password": "test",
  "status": "1",
  "voice_method": "POST",
  "voice_fallback_method": "POST",
  "uri": "/api/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Clients/CL4e10e3b56a614414bcc1eeca5d96effe.json"

Delete a Client

You must use the Client SID

curl -X DELETE https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Clients/CLIENT_SID  \
   -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 CLIENT_SID = 'my_CLIENT_SID'

request({
      method: 'DELETE',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Clients/' + CLIENT_SID + '',
      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
CLIENT_SID = 'my_CLIENT_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 + '/Clients/' + CLIENT_SID + '',
      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 CLIENT_SID = "my_CLIENT_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 + "/Clients/" + CLIENT_SID + "");
      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()'
      ...
  }
}

Change Client’s Password

You must use the Client SID as shown below:

curl -X PUT https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Clients/CLIENT_SID  \
   -d 'Password=NewPassword' \
   -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 CLIENT_SID = 'my_CLIENT_SID'

request.({
      method: 'PUT',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Clients/' + CLIENT_SID + '',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN },
      form: {
         'Password': 'NewPassword'
      }
   },
   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'
// Provide additional path parameters if applicable
CLIENT_SID = 'my_CLIENT_SID'

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({
   'Password': 'NewPassword'
})

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("PUT", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Clients/' + CLIENT_SID + '',
      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";
   // Provide additional path parameters if applicable
   public static final String CLIENT_SID = "my_CLIENT_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 + "/Clients/" + CLIENT_SID + "");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("PUT");
      conn.setDoOutput(true);
      DataOutputStream os = new DataOutputStream(conn.getOutputStream());

      // Update POST parameters accordingly
      os.writeBytes("Password=NewPassword");
      os.close();

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

Get List of available Clients

The command below shows all Clients created using the default Admin Account

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Clients.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 + '/Clients.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 + '/Clients.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 + "/Clients.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()'
      ...
  }
}

JSON GET Response

[
  {
    "sid": "CL3003328d0de04ba68f38de85b732ed56",
    "date_created": "Mon, 4 Nov 2013 16:33:39 -0500",
    "date_updated": "Mon, 4 Nov 2013 16:33:39 -0500",
    "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
    "api_version": "2012-04-24",
    "friendly_name": "bob",
    "login": "bob",
    "password": "i-1c8468a2",
    "status": "1",
    "voice_method": "POST",
    "voice_fallback_method": "POST",
    "uri": "/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Clients/CL3003328d0de04ba68f38de85b732ed56.json"
  },
  {
    "sid": "CLa2b99142e111427fbb489c3de357f60a",
    "date_created": "Mon, 4 Nov 2013 12:52:44 -0500",
    "date_updated": "Mon, 4 Nov 2013 12:52:44 -0500",
    "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
    "api_version": "2012-04-24",
    "friendly_name": "alice",
    "login": "alice",
    "password": "i-1c8468a2",
    "status": "1",
    "voice_method": "POST",
    "voice_fallback_method": "POST",
    "uri": "/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Clients/CLa2b99142e111427fbb489c3de357f60a.json"
  }
]

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.

  • Accounts

  • Clients

  • Incoming Phone Numbers

Platform

Programmable Voice

Programmable SMS

Turnkey Applications

Smart 2FA

Call Queue

Auto Attendant

Number Masking

Task Router

Campaign Manager

Learn

Terms And Conditions

About

ABOUT

CONTACT US

© 2020, All rights reserved.