Virtual Contact Center Web Callback API

Overview

Web callback is a function that allows tenants to embed a button on their websites that would allow visitors to request a call back from the application. There are numerous advantages of this feature: customer does not need to wait in the queue – this would lead to better customer satisfaction and lower telephony costs (to the contact center). The Virtual Contact Center web callback API is a HTTP API.

The web call back feature supports the following callback options:

1. Call me now – application would call the customer and launch the appropriate IVR script.
2. Call me after a certain delay (the delay is configurable). After the delay the behavior is same as call me now.
3. Call me when agent is available.

This document describes the supported parameters for using the web callback API. Example use cases are provided for references.

All API requests are authenticated using a token that is issued to a valid Virtual Contact Center tenant.

For security reasons, the web callback API only accepts request using HTTPS, so that request headers and response data are encrypted.

Testing Using a Browser

The web callback API makes it easy to submit a query, for experimentation, testing or debugging purposes. From a web browser, simply enter the URL.  For example,

https://mycontactual.com/SC/webcallback.php?tenant=Acme&token=fb65d0515b9631c6db72e7e66fe6df49&phone=
16505551212&callback_type=1&channel_number=18006661212 

will initiate a call to the number 16505551212 and load the IVR script associated with the channel 18006661212.

https://na1.mycontactual.com/SC/webcallback.php
https://na2.mycontactual.com/SC/webcallback.php
https://na3.mycontactual.com/SC/webcallback.php
https://na4.mycontactual.com/SC/webcallback.php
https://vcc-na7.8x8.com/SC/webcallback.php
For tenants in Cananda: https://www.mycontactual.ca/SC/webcallback.php
For tenants in UK: https://www.mycontactual.co.uk/SC/webcallback.php

Authentication

In order to make an API request, you must first obtain an authentication token that has been issued for your tenant. This token combines username and password into a single long string. To get your token, log into the Configuration Manager, select "Integration", and click the "API Token" tab. The "Action Request Token" needs to be used in all API requests. Next, click the "New Token" button. This generates a new private token for your tenant. You will use this token in all requests to the web callback API. You may generate a new token at any time.

Queue Id

For web callback type – "call me when agent is available" a queue id needs to be provided. The interaction would be placed in this queue – until an appropriate agent becomes available. The queue id can be retrieved by going to the queues tab in the configuration manager. Only outbound phone queues can be used in the web callback request.

Query Parameters

GET/POST Parameters

The following parameters are allowed parameters that can be passing along with the web callback URL using GET or POST method.

Parameter Name

Description

Accepted value

Mendatory

tenant

Tenant name

token

Authentication token

phone

callback_type

channel_number

queue_id

callback_delay

expiration

extTransactionData

caller_id

back

No

ctl_userdata

Please refer to section 'ctl_userdata' below.

No

dialplan_id

Digit only. 
A valid dial plan id. 
Id can be found from 
the Dial Plan listing 
table on Configuration 
Manager. If not specified, 
tenant default dial plan 
is used.

No

ctl_userdata

The ctl_userdata allows tenant to pass in any user data or system data to trigger callback function. The value of ctl_userdata is any combination of name/value data in the format shown below.

ctl_userdata=[name1|value1][name2|value2][name3|value3]…

The category of name/value data is mainly divided into two groups: system data and user data.

System Data

System data are data that recognized by Virtual Contact Center system. All the name of the data that starts with 'ctl_' are treated as system data. The following table shows the list of supported system data with description.

Data Name

Description

Supported value

Default Value

Remarks

ctl_callbackUrl

The URL to do the

callback. All the 

userdata with 

system generated 

result and data 

will be passing to 

the URL using POST 

method.

Any valid URL.

No system default value.

If not specified, no callback 

will be done.

User Data

The user data are the data that will be sent along with the callback. The name of the user data should never start with 'ctl_' or it will be treated as system data. Refer to Examples below to find out what user data would look like. User data is mostly for recording information of the related activity (in this case, web callback). Therefore, Virtual Contact Center provides a list tokens that can be used in user data. Tokens will be replaced by the actual data before it's used in the action or posting to the launch URL.  The following is the list of supported tokens with description.

Error Codes

In case of error a parameter named "ctl_error" will be returned as part of the query string sent along with the back url. The various error codes are:

Examples

Example 1:

If the customer would like to be called back right away, the web callback request would look like the following:

https://mycontactual.com/SC/webcallback.php?tenant=Acme&token=fb65d0515b9631c6db72e7e66fe6df49&phone=
16505551212&callback_type=1&channel_number=18006661212&back=http://www.acmejet.com/ctdresult.php&
caller_id=18006664444 

The application would initiate a call to 16505551212, the customer would see the caller id as 18006664444 and after the request is processed, the following url http://www.acmejet.com/ctdresult.php would be launched. Once the customer answers the phone, the IVR script associated with the channel 18006661212 would be executed.

Example 2:

If the customer would like to be called back after a fixed amount of delay (5 minutes in this example), the web callback request would look like the following:

https://mycontactual.com/SC/webcallback.php?tenant=Acme&token=fb65d0515b9631c6db72e7e66fe6df49&phone=
16505551212&callback_type=1&channel_number=18006661212&back=http://www.acmejet.com/ctdresult.php&
caller_id=18006664444&callback_delay=300&ctl_userdata=[ctl_callbackUrl|https://mywebporter.com/
callback.php][Transactionid__c|$interaction_guid$][CallAnswerTime|$call_answered_time$]
[foreign_key|1234456677]

The application would initiate a call to 16505551212 after a delay of 5 minutes, the customer would see the caller id as 18006664444 and after the request is processed, the following URL http://www.acmejet.com/ctdresult.php would be launched. This example also shows how to trigger callback by using ctl_userdata. The callback function passes all the data in the value of ctl_userdata back to the callback URL.

Example 3:

If the customer would like to be called back when an agent is available, the request would look like the following:

https://mycontactual.com/SC/webcallback.php?tenant=Acme&token=fb65d0515b9631c6db72e7e66fe6df49&phone=
16505551212&callback_type=2&back=http://www.acmejet.com/ctdresult.php&caller_id=18006664444&queue_id=103

An interaction would be created and placed in the queue (id 103 in this example). When an agent becomes available, the application would offer the interaction to the agent. If the agent accepts the interaction, the application would initiate a call to the agent and then bridge the call to the customer.

Example 4:

If the customer would like to be called back when an agent is available with the following exception – if agent is not available within the next hour, he would like the request to be terminated. The request would look like the following:

https://mycontactual.com/SC/webcallback.php?tenant=Acme&token=fb65d0515b9631c6db72e7e66fe6df49&phone=
16505551212&callback_type=2&back=http://www.acmejet.com/ctdresult.php&caller_id=18006664444&
queue_id=103&expiration=3600

An interaction would be created and placed in the queue (id 103 in this example). When an agent becomes available, the application would offer the interaction to the agent. If the agent accepts the interaction, the application would initiate a call to the agent and then bridge the call to the customer. If an agent is not available within an hour, the interaction would be deleted (treated as an abandoned transaction in the reports).