Call Queuing

Introduction

Call Queuing is a feature that allows callers (A leg) to be placed in a Queue, hearing background music or announcement (text to speech) while waiting to get connected to called party (B leg). This is one of the most commonly needed features to build any kind of Inbound Contact Center solution.

The document below describes the Call Queue turnkey application from Telestax build on top of the Restcomm Platform leveraging its APIs. A Queue stores incoming calls in First In First Out (FIFO) order (let’s call those callers Customers). The Queue then connects the first call in queue to receivers (let’s call those Agents).

Call Queuing

In order to use Call Queuing, you need a valid Restcomm Cloud account.

For the Call Queuing turnkey application to function correctly at least two numbers must be reserved in Restcomm Cloud (via Call Queuing API) and at least one unique Queue defined (via Call Queuing API), let’s call this “Support” Queue have to be defined. The first number will be used by Customers to call and get in “Support” Queue. Let’s set this number to +1 571 331 6666. The second number is called by Agents and starts accepting call’s queued in “Support” in FIFO order. Let’s have this number set to +1 571 331 9999. Users can create as many queues as long as they all have unique names.

Create Queuing API

Create Queuing API has to be called twice.

Once to register the Customer Number (+1 571 331 6666 in above example) and corresponding <queue> verb as explained in Queue RCML.
A second time to register Agent Number (+1 571 331 9999 in above example) and corresponding <enqueue> verb as explained in Enqueue RCML.

Base Resource URI

https://your_custom_domain.com

Add Queuing Resource URI

/callqueue/provisioning

Supported Operations

HTTP POST: Add New Queue

Request Parameters

Parameter

Description

applicationUrl

Mandatory parameter. applicationUrl takes absolute URL as value. URL points to Restcomm Markup Language (RCML) that will be executed for an incoming call. The RCML can be setup for <queue> if its Customer Number or <enqueue> if its Agent Number.

For example, Customer Number URL can return:
<Response> <Dial timeout="300" record="true"> <Queue waitUrl="http://www.mocky.io/v2/5dadc3592d00006e00e4bcc9" joinUrl="http://www.mocky.io/v2/5d92d5d23000005b001b7085">support </Queue> </Dial> </Response>

Agent NumberURL can return:
<Response> <Enqueue waitUrl="http://www.mocky.io/v2/5dadc1ce2d00006e00e4bcba" joinUrl="http://www.mocky.io/v2/5d92ee853000005b001b70ea" rejoin="true"> support </Enqueue> </Response>

applicationUrlMethod

The HTTP Method for applicationUrl, the attribute will take GET or POST as value. The default value is POST

phoneNumber

Mandatory parameter. Phone Number that must be provisioned in Restcomm Cloud. Number is either Customer Number or Agent Number.

override

override parameter is either true or false. If Restcomm Cloud already has a number provisioned and API is called passing the same number, setting override to “true”, Call Queue Solution will override the setting of the number. By default it is set to false.

byoc

byoc parameter defines if provisioned phoneNumber is to be bought from Restcomm Cloud Platform or to be used as SIP number (Bring Your Own Career). iF byoc is set to true, phoneNumber is registered as SIP number. Its default value is set to true.

Response Body

Response Body will return HTTP response 200 OK if Call Queue was successfully provisioned else it will return an HTTP Error.

The successful response is returned as JSON body as shown in the example below. The following is a list of all available parameters.

Parameter

Description

sid

Unique Id for this Application within Call Queuing turnkey application.

phoneNumber

Phone Number that was provisioned.

accountSid

Restcomm Account Sid that called this API

friendlyName

Friendly name of Phone Number that was provisioned. By default this is always the same as phoneNumber parameter.

dateCreated

Timestamp when this Call Queuing app was created.

voiceUrl

URL that is provisioned for passed phoneNumber in Restcomm Cloud. This URL is made up of “applicationUrlMethod” that was passed as request parameter along with some additional parameters that are used by Call Queuing turnkey application.

voiceMethod

HTTP Method for calling the voiceUrl provisioned in Restcomm Cloud for PhoneNumber. This is the same value as applicationUrlMethod parameter passed in API request.

voiceFallbackUrl

Not used as of today

voiceFallbackMethod

Not used as of today

voiceCallerIdLookup

Not used as of today

voiceApplicationSid

Not used as of today

statusCallback

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

statusCallbackMethod

The HTTP method Restcomm will use to make requests to the StatusCallback URL.Always POST.

smsUrl

Not used as of today

smsMethod

Not used as of today

smsFallbackUrl

Not used as of today

smsApplicationSid

Not used as of today

apiVersion

The API version of Restcomm Cloud

isSIP

If phoneNumber is registered as SIP Number (BYOC) or if it’s provided by Telestax.

uri

Unique URI in Restcomm Cloud to reach to provisioned phoneNumber

Example:

{
"override":"true",
"applicationUrl":"http://www.mocky.io/v2/5dd4a91f2f0000f905d4fb63",
"phoneNumber":"15713316666"
}

From the bash terminal you can run the command below to register Customer Phone Number and applicationUrl:

curl -X POST \
'https://cloud.restcomm.com/callqueue/provisioning' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{ "override":"true", "applicationUrl":"http://www.mocky.io/v2/5dd4a91f2f0000f905d4fb63", "phoneNumber":"15713316666" }'

If the creation of Call Queuing is successful, below is the response returned:

{
   "sid":"PN1865b4235b7b498bbbf983d2ec486f0e",
   "phoneNumber":"15713316666",
   "accountSid":"AC23f1b11bbb99a46436c365cb7bec246e",
   "friendlyName":"15713316666",
   "dateCreated":"Wed, 20 Nov 2019 02:54:42 +0000",
   "dateUpdated":"Wed, 20 Nov 2019 02:54:42 +0000",
   "voiceUrl":"https://cloud.restcomm.com/callqueue/rcml?appUrl=http%3A%2F%2Fwww.mocky.io%2Fv2%2F5dd4a91f2f0000f905d4fb63&queueState=initiating",
   "voiceMethod":"POST",
   "voiceFallbackUrl":null,
   "voiceFallbackMethod":"POST",
   "voiceCallerIdLookup":"false",
   "voiceApplicationSid":null,
   "statusCallback":"https://cloud.restcomm.com/callqueue/callback",
   "statusCallbackMethod":"POST",
   "smsUrl":null,
   "smsMethod":"POST",
   "smsFallbackUrl":null,
   "smsFallbackMethod":"POST",
   "smsApplicationSid":null,
   "apiVersion":"2012-04-24",
   "isSIP":null,
   "uri":"/2012-04-24/Accounts/AC23f1b11bbb99a46436c365cb7bec246e/IncomingPhoneNumbers/PN1865b4235b7b498bbbf983d2ec486f0e.json"
}

You would run the same command again, but this time change applicationUrl and phoneNumber as explained in below command to register the Agent Number.

curl -X POST \
'https://cloud.restcomm.com/callqueue/provisioning' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{ "override":"true", "applicationUrl":"http://www.mocky.io/v2/5dd4b7f62f0000f905d4fb98", "phoneNumber":"15713319999" }'

Queue RCML

The <dial> verb’s <queue> noun specifies a queue to dial. When dialing a queue, the caller will be connected with the first enqueued call in the specified queue. If the queue is empty, dial will wait until the next person joins the queue or until the <dial> timeout duration is reached.

Note: As of today <dial> recording is not supported. This feature is on our roadmap.

<queue> takes below attributes

Attributes

Attribute

Description

waitUrl

Attribute takes a URL as an argument. The url points to a RCML document that will be executed on the queued caller’s end (Customer) when the caller is put to queue waiting for the next available enqueue (Agent). The waitUrl RCML just support Say, Play, Redirect verbs.

If total duration of <say>, <play> together is less than <dial> timeout value, Call Queue will put the waitUrl response in loop and play till timeout occurs or call is connected.

<redirect> verb can be used for calling RCML document again and Application can add some dynamic business logic that can change <say> in next loop.

Call Queue will pass the parameters explained in Request Parameters in its request to the value of the waitUrl attribute.

waitUrlMethod

The method attribute takes the value 'GET' or 'POST'. This tells Call Queue whether to request the waitUrl above via HTTP GET or POST. This attribute is modeled after the HTML form method attribute. 'POST' is the default value.

joinUrl

Attribute takes a URL as an argument. The url points to a RCML document that will be executed on the queued caller’s end when the caller is about to be connected to next available enqueue. The joinUrl RCML supports Say, Play, Redirect verbs.

Call Queue will pass the parameters explained in Request Parameters in its request to the value of the joinUrl attribute.

joinUrlMethod

The method attribute takes the value 'GET' or 'POST'. This tells Call Queue whether to request the joinUrl above via HTTP GET or POST. This attribute is modeled after the HTML form method attribute. 'POST' is the default value.

Request Parameters

Parameter

Description

CallSid

The unique identifier for this call.

AccountSid

Your account sid.

From

Caller’s sphone number.

Phone number receiving the call.

CallStatus

Status of call. Possible values are queued, ringing, in-progress, completed, busy, failed and no-answer.

Queue Example

Below example shows how RCML can be formed:

<Response>
      <Dial timeout="300" record="true">
          <Queue waitUrl="http://www.mocky.io/v2/5dadc3592d00006e00e4bcc9" joinUrl="http://www.mocky.io/v2/5d92d5d23000005b001b7085">support
          </Queue>
      </Dial>
</Response>

Mocky.io returns the following RCML.

<Response>
<Say>
All our Agents are busy. Your call is important to us. Please hold your line and we will connect you in sometime.
</Say>
<Play>
https://cloud.restcomm.com/restcomm/music/electronica/teru_-_110_Downtempo_Electronic_4.wav
</Play>
</Response>

Mocky.io returns RCML as follows.

<Response>
<Say language="google.en-IN-Wavenet-C" voice="woman">
Thanks for holding line. You will now be connected to Agent.
</Say>
</Response>

Enqueue RCML

The <enqueue> verb enqueues the current call in a call queue. Enqueued calls wait on hold until the call is dequeued by another caller via the <dial> verb for same Queue. <enqueue> takes below attributes

Attributes

Attribute

Description

waitUrl

Attribute takes a URL as an argument. The url points to a RCML document that will be executed while the caller (Agent) is put to queue waiting for the next caller (Customer) joining <queue>. The waitUrl RCML just support Say, Play, Redirect verbs.

Once the waitUrl RCML flow runs out of verbs to execute, Call Queue will start over, essentially looping hold music indefinitely.

<redirect> verb can be used for calling RCML document again and Application can add some dynamic business logic that can change <say> in next loop.

Call Queue will pass the parameters explained in Request Parameters in its request to the value of the waitUrl attribute.

waitUrlMethod

joinUrl

Attribute takes a URL as an argument. The url points to a RCML document that will be executed on the caller’s end when the caller (Agent) is about to be connected to the next available queued customer.. The joinUrl RCML just support Say, Play, Redirect verbs.

Call Queue will pass the parameters explained in Request Parameters in its request to the value of the joinUrl attribute.

joinUrlMethod

rejoin

When Agent finishes call with Customer and Customer hangs up, if this attribute is true and there are no more Customers queued, Agent will be enqueued again and Agent hears onhold music till next Customer joins. If this attribute is false, Agent’s call will be dropped if there are no more Customers in queue.

Request Parameters

Parameter

Description

CallSid

The unique identifier for this call.

AccountSid

Your account sid.

From

Caller’s phone number.

Phone number receiving the call.

CallStatus

Status of call. Possible values are queued, ringing, in-progress, completed, busy, failed and no-answer.

Enqueue Example

The example below shows how RCML can be formed

<Response>
      <Enqueue waitUrl="http://www.mocky.io/v2/5dadc1ce2d00006e00e4bcba" joinUrl="http://www.mocky.io/v2/5d92ee853000005b001b70ea" rejoin="true">support</Enqueue>
</Response>

Mocky.io returns the following RCML.

<Response>
<Say>
There are no customers in Queue. Please hold your line.
</Say>
<Play>
https://cloud.restcomm.com/restcomm/music/electronica/teru_-_110_Downtempo_Electronic_4.wav
</Play>
</Response>

Mocky.io returns below RCML.

<Response>
<Say>You will now be connected to Customer</Say>
</Response>