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.
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. Agent NumberURL can return: |
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. |
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. |
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. |
To |
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. |
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 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. |
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. |
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. |
To |
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>