8x8 Contact Center Web Callback API

Updated: 07/03/2024

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. One advantage of this feature is that the customer does not need to wait in a queue. This leads to better customer satisfaction and lower telephony costs (to the contact center). The 8x8 Contact Center web callback API is a HTTP API.

The web call back feature supports the following callback options:

Call me now. The application will call the customer and launch the appropriate IVR script.
Call me after a certain delay (the delay is configurable). After the delay the behavior is same as call me now.
Call me when an agent is available.

This article 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 Contact Center tenant.

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

Important: All callback requests submitted will be lost when the platform is re-started. Prior to a platform upgrade, make sure the pending callback requests are handled on your application side.

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://vcc-na4.8x8.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.

Revise your query URL based on the login URL of your Tenant. (Refer to the 8x8 Contact Center Platform URL Guide to retrieve your login URL)

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 in to Configuration Manager for Contact Center, select Integration, and click API Token. The Action Request Token needs to be used in all API requests. Next, click New Token. 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

The whole query parameter must be URL Encoded.

GET/POST Parameters

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

Parameter Name	Description	Accepted value	Mandatory
tenant	Tenant name		Yes
token	Authentication token		Yes
phone	The phone number of the customer requesting a callback.	Digit only. In order to correctly route calls, it is recommended that the phone number is formatted in E.164 format.	Yes
callback_type	A value of 1 indicates a request to be called back right now (with an optional delay). A value of 2 indicates that the customer wants to be called back when agent is available.	1 or 2	Yes
channel_number	This is the channel whose IVR script would be loaded and executed once the customer answers the call. This is a required attribute if callback_type is set to 1.	A valid channel number for the tenant.	Yes if callback_type is set to 1.
queue_id	This attribute is used to identify the ID of the queue that this interaction should be placed in. This is a required field for the "call me when an agent is available option" (callback_type of 2).	A valid queue ID for the tenant.	Yes if callback_type is set to 2.
callback_delay	If callback_type is set to 1 an optional delay could be provided. If a value greater than 0 is provided, the application would wait for the specified number of seconds before attempting to call the customer.	Any value greater than 0.	No
expiration	If callback_type is set to 2 an optional expiration could be provided. If a value greater than 0 is provided, the application would delete the request if an agent does not become available within the specified time.	Any value greater than 0.	No
extTransactionData	This attribute can be used to pass name value pairs that will be used for populating the transaction panel when an agent is offered the interaction. Each name value pair is enclosed by [ ] and the name/value are separated by "\|".	There is a limit of 500 characters.	No
caller_id	This attribute is used to specify the Caller ID to be used on the outbound call. This is an optional field. The value provided must be one of the channels configured for the tenant. If no value is provided or if the value provided does not match one of the channels configured for the agent, the default Caller ID provisioned for the tenant would be used.	Anonymous (Anonymous Caller ID)-1 (use agent default Caller ID) Any valid channel number. Tenant default Caller ID.	No
back	This attribute would be used to launch a page after the request has been processed.	Only validated domains can be used. Create a Case with 8x8 Support to provide the domains that you would like to use with the back parameter. If your domain is not validated then you will get an internal error and you won’t be able to redirect to the desired URL.	No
ctl_userdata	This attribute can be used to pass name value pairs that will be used for triggering build-in callback function.	Refer to section ctl_userdata below.	No
dialplan_id	Dial Plan Id that should be applied to the Phone Number.	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
previewTimeout	Preview Timeout	This overrides the offer timeout configured for the agent. Accepted value is between 15 to 10800 seconds. This parameter only used along with callback_type equals to 2 (call me when agent is available).	No
extTransactionId	External Transaction Id	This attribute allows tenant to mark a web callback with any identifier. This attribute can be used to delete the webcallback interaction after its creation using the web callback interaction delete API.	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 user data 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.

Token name	Description
$caller_id$	The caller ID used to do the outbound call.
$transaction_id$	Transaction ID associated with the outbound call.
$call_answered_time$	UTC Call answered time in seconds. If call is not established, a number of 0 is used.
$call_hangup_time$	UTC Call hang up time in seconds. If call is not established, a number of 0 is used.
$callAnsweredTenantTT$	Call Answered Timestamp in tenant timezone in the format of YYYY/MM/DD HH:mm:ss Z.
$callHangupTenantTT$	Call Hangup Timestamp in tenant timezone in the format of YYYY/MM/DD HH:mm:ss Z.
$callDuration$	Call Duration in the format of HH:MM:SS
$equal$	The token will be replaced actual '='.
$interaction_guid$	Interaction GUID of the interaction associated with the outbound call.
$year$	The current year in the format of YYYY.
$month$	The current month in the format of MM.
$date$	The current date in the format of DD.
$hours$	The current hour in the format of HH.
$minutes$	The current minute in the format of MM.
$seconds$	The current second in the format of SS.
$transaction_codes$	Selected transaction codes. The format is <transaction list name >:<transaction shortcode> separated by commas if more than one is selected. The corresponding text can be found by using the mapping downloaded from Virtual Contact Center stat API.
$notes$	The small notes along with Transaction Code selected entered by agent.
$lastTclListName$	The transaction code list name of the last selected transaction code.
$lastTclCodeDesc$	The transaction code description of the last selected transaction code.
$lastTclCodeShort$	The short code of the last selected transaction code.

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:

Error Code	Description
1	Tenant not enabled.
2	Web callback not enabled.
3	Invalid authentication token.
7	Queue id provided is invalid.
8	Queue is disabled.
9	Queue direction is not 'Outbound'
10	Missing Callback type.
11	Callback delay is not numeric
12	Missing channel information for callback type 1.
13	Invalid channel number provided.
14	Unknown callback type specified.
15	Service unavailable.
16	External data maximum length exceeded(500 character limit)
17	Phone number not provided.
19	Internal Error.
20	ctl_userdata exceeded max length (1800 character limit)
21	Invalid preview timeout value.
22	External transaction ID maximum length exceeded (64 character limit)

Examples

Example 1

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

https://vcc-na4.8x8.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://vcc-na4.8x8.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://vcc-na4.8x8.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

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://vcc-na4.8x8.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).

Delete Web Callback

If agents place phone calls and interact with customers whose web callback requests are still pending in the queue, agents may prefer to cancel the pending requests from the Web Callback API. Interactions created by the web callback API can be easily removed by requesting the delete web callback API. This request removes all web callback interactions which were created using extTransactionId parameter. If customers request a call back via web to interact with the agents before the call is processed by the agents, the agents can now mark this call complete and delete the pending request.

The delete web callback API allows web callbacks to be deleted only if the interactions are not assigned to any agent yet.

The delete API uses basic authentication methods to authenticate API access. The authentication user name will be your tenant name, and the password will be the API action request token you obtain from Configuration Manager.

DELETE https://vcc-naX.8x8.com/api/interactions/webcallback/externaltransaction/{ext-transaction-id}

The HTTP request method is DELETE and {ext-transaction-id} should be the external transaction id assigned to the web callbacks aimed to be deleted. The request returns an xml as default response type and it also supports JSON by using .json at the end of the path

Deleting a web callback

To delete a web callback, first, the web callback must have been created using the extTransactionId parameter. In the following example the web callback was created with extTransactionId=transac_0 and the delete request sends the same value in the path, {ext-transaction-id}:

DELETE https://vcc-naX.8x8.com/api/interactions/webcallback/externaltransaction/transac_0.json

Response:

HTTP 200 OK

  { 
  "data":{ 
  "extTransactionId":"transac_0",
  "interactions":{ 
  "deleteStatus":"ok",
  "interactionGuid":"int-154820172-byfXC2WPsSnYzX-...",
  "phone":12345678918,
  "transactionID":42
  }
  }
}

If the interaction is already created and assigned to an agent, the response data attribute "deleteStatus" inside the interactions is shown as "nok" and the HTTP response code is 207 Multi-Status. The "reason" attributes indicates the cause of the failure and the only value currently available is "statuserror", which means that the interaction was not allowed to be deleted due its status.

Response:

HTTP 207 Multi-Status

  { 
  "data":{ 
  "extTransactionId":"transac_0",
  "interactions":{ 
  "deleteStatus":"nok",
  "interactionGuid":"int-154820172-byfXC2WPsSnYzX-...",
  "phone":12345678918,
  "transactionID":42,
  "reason":"statuserror"
  }
  }
  }

In case there is more than one web callback created with same external transaction id, the request is going to delete all the interactions. In the response, the "interactions" attribute is set as an array containing all the results of each individual interaction. See the following response example:

Response:

HTTP 207 Multi-Status

  { 
  "data":{ 
  "extTransactionId":"transac_0",
  "interactions":[ 
  { 
  "deleteStatus":"ok",
  "interactionGuid":"int-154820172-byfXC2WPsSnYzX-...",
  "phone":12345678918,
  "transactionID":42
  },
  { 
  "deleteStatus":"nok",
  "interactionGuid":"int-154820152-dsfXC2BQeSnZcA-...",
  "phone":12345678919,
  "transactionID":43,
  "reason":"statuserror"
  }
  ]
  }
}

Note: If in this request, all interactions were successfully deleted ("deleteStatus":"ok"), the response code will be 200 OK instead of 207 Multi-Status.

Error responses

The external transaction id passed {ext-transaction-id} may not exist by the time the delete request is executed, in cases like this, the API returns the following response and the HTTP response code is 404 Not Found::

Response:

HTTP 404 Not Found
 { 
  "error":{ 
  "message":"transaction not found"
  }
  }

If any other application error occurs during the request, the result API returns 500 Internal Server Error like the example below:

Response:

HTTP 500 Internal Server Error
 { 
  "error":{ 
  "message":"internal error"
  }
  }

Response Codes

Response Code	Description
200 OK :	All web callback interactions associated to the {ext-transaction-id} were successfully deleted.
207 Multi-Status :	Some of the requested web callback interactions associated to the {ext-transaction-id} were not deleted.
404 Not Found :	No web callback interactions associated to the {ext-transaction-id} were found.
401 Unauthorized :	Invalid or missing username and authentication token.
500 Internal Server Error :	Some internal error has occurred.