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 Queuing Solution from ACME build on top of the CPaaS 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 CPaaS Cloud account.

For the Call Queuing solution to function correctly at least two numbers must be reserved in CPaaS 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 Queue API

Create Queue 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://$DOMAIN

Add Queue 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 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 CPaaS Cloud. Number is either Customer Number or Agent Number.

override

override parameter is either true or false. If CPaaS Cloud already has a number provisioned and API is called passing the same number, setting override to “true”, Call Queuing 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 CPaaS 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 Queuing 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 Solution.

phoneNumber

Phone Number that was provisioned.

accountSid

CPaaS 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 CPaaS 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 Solution.

voiceMethod

HTTP Method for calling the voiceUrl provisioned in CPaaS 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 CPaaS will request to pass status parameters (such as call ended) to Call Queuing application.

statusCallbackMethod

The HTTP method CPaaS 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 CPaaS Cloud

isSIP

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

uri

Unique URI in CPaaS 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://yourcompany.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":"PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "phoneNumber":"15713316666",
   "accountSid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "friendlyName":"15713316666",
   "dateCreated":"Wed, 20 Nov 2019 02:54:42 +0000",
   "dateUpdated":"Wed, 20 Nov 2019 02:54:42 +0000",
   "voiceUrl":"https://yourcompany.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://yourcompany.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://yourcompany.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 (Agent) when the caller is put to queue waiting for the next available enqueue (Customer). The waitUrl RCML supports Say, Play, and Redirect verbs.

If total duration of <say>, <play> together is less than <dial> timeout value, Call Queuing 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 Queuing 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 Queuing 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 Queuing 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 Queuing 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.

rejoin

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

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://yourcompany.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 (Customer) is put to queue waiting for the next caller (Agent) joining <queue>. The waitUrl RCML supports Say, Play, and Redirect verbs.

Once the waitUrl RCML flow runs out of verbs to execute, Call Queuing 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 Queuing 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 Queuing 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://yourcompany.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>