Request a Quote

8x8 U.S. 8x8 Solutions U.K. Request a Quote  1-866-879-8647
Sign In  Account Manager >    Virtual Office Online >

Back >

Virtual Contact Center Click-To-Dial API

Overview

The Virtual Contact Center Click-To-Dial API is a HTTP API that allows logged-in agent to perform outbound call by launching an external URL. The typical usage of Click-To-Dial is to create clickable hyperlink on CRM record to dial out on corresponding customer phone number.

This document describes the supported parameters for running Click-To-Dial. Example use cases are provided for references.

The API request is authenticated using client cookie. Only agent with valid AGUI session will be able to run Click-To-Dial API. Click-To-Dial API can only successfully run on the browse window that sharing the AGUI session.

For security reasons, the Click-To-Dial API only accepts request using HTTPS, so that request headers and response data are encrypted.

Testing Using A Browser

The Cick-To-Dial API makes it easy to submit a query, for experimentation, testing or debugging purposes. From a web browser, simply enter the URL. You will be promted to close the window. In the meantime, the correspoding agent phone will be ringed. Once agent answer the phone, destination phone will ring. For example,

  https://mycontactual.com/AGUI/make_call.php?prefix=1&phone=6502928880

will call the destination number 16502928880.

Revise your query URL based on the login URL of your tenant:

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

Query Parameters

GET Parameters

The following parameters are allowed GET parameters passing along with the click-to-dial URL.
All the GET parameter data should be URL encoded.
Parameter Name
Description
Accepted value
prefix
Calling Phone Number Prefix
Digit only.
phone
Calling Phone Number
Any phone number (formatted or non-formatted).
callerId
Caller id to make the outbound call.
Any existing phone channel number. Digit only.
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. 
It is an optional field.
queue_id
Outbound queue id to make the call 
along with. Agent will become busy 
when the call established with the 
queue. Corresponding TCL will be 
applied along with the queue.
Digit only. A valid queue 
id. Id can be found from 
the Queues listing table 
on Configuration Manager. 
It is optional field.

GET/POST Parameters

The following parameters are allowed parameters that can be passing along with the click-to-dial URL using GET or POST method.

Parameter Name
Description
Accepted value
ctl_userdata
A set of name/value pair data to
trigger desired action.
Refer to Section 'ctl_userdata' below.
extTransactionData
A set of name/value pair data to 
associate CRM record with auto log.
Refer to Section 'extTransactionData' below.

extTransactionData

The exTransactionData allows tenant to pass in associated record ID and record and record type the click-to-dial call is triggered from. The extRecordId and extRecordType are usual to link the call log generated by the ctl_action automatically. Please refer to section 'Create Action' below for an example. However, the association can only applied for tenant using Enhanced SFDC integration. The format of the value of extTransactionData looks like the following:
extTransactionData=[extRecordId|value1][extRecordType|value2]

ctl_userdata

The ctl_userdata allow tenant to pass in any user data or system data to trigger supported click-to-dial related action. The design of ctl_userdata is to allow any combination of name/value data. Each name/value data shall be in the format of [name|value]. There is no limit on how many number of name/value data can be used to compose the ctl_userdata. The value of ctl_userdata typically looks like the following:
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_action
Action command
create
No system default value.
If not specified, no action 
is taken in Virtual Contact Center 
system.
ctl_intType
Integration Type
sfdc
No system default value.
If not specified, action will 
be ignored.
ctl_launchopt
Launch Screenpop
URL after action
true|false
false
Launch Screenpop URL 
configured
ctl_launchext
Launch Screenpop
Option
edit
No system default value.
If not specified, the record 
launched with the URL will be 
readonly. Value will be 
ignored if ctl_launchopt is 
not true.
ctl_parentid
Launch Screenpop
option with the 
parented as return
URL
valid ID
No system default value.
If not specified, no return 
URL for launching screenpop 
URL.
ctl_newRecordId
Record ID used by
do the launch URL.
valid ID
--
This is appended to the 
ctl_userdata after create 
action is finished by the 
Virtual Contact Center system. Tenant 
should not specify this.
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.
ctl_recordname
The name of the 
record to launch 
the window/tab on 
screenpop window.
No restriction.
 
This is used together with 
launchopt = true. If not 
specified, system will 
generate name for the new 
window/tab for launching 
screenpop.

User Data

The user data are the data that for performing 'ctl_action' specified. The name of the user data should never start with 'ctl_' or it will be treated as system data. Virtual Contact Center only process the user data only with known 'ctl_action' and 'ctl_intType'. 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, click-to-dial). 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.

Create Action

Create action triggers creation of new record in CRM with integration type specified. The current version of Virtual Contact Center application only support create record on SFDC.  

Launch Option

Launch option 'ctl_launchopt' is for launching Screen pop URL with the following name/values screenpop data post. Launch Option is allowing value either 'true' or 'false'. It is only taking effect if Screenpop is enabled on the Configuration Manager. This option is independent of the ctl_action specified.

Data Name

Description

CtlUserData

The original ctl_userdata with all tokens filled with actual data.

AgentID

Agent login ID

Username

Agent External Username entered to AGUI

extLogin

Agent External Username entered to AGUI

Password

Agent External password entered to AGUI

extPwd

Agent External password entered to AGUI

Account

Account ID configured in Screenpop section of the Configuration Manager

Role

Screen pop target type configured in Configuration Manager.

Command

Screen pop command. For this case, 'launch' is the value.

cmd

Screen pop command. For this case, 'launch' is the value.

Callback URL

Callback URL 'ctl_callbackUrl' triggers callback action when click-to-dial transaction completes. The callback action is independent with other action specified in the user data. The following table shows the data that will be post to the callback URL specified.

Data Name

Description

ctl_userdata

The original ctl_userdata passing in to the Virtual Contact Center Application with the click-to-dial URL with all the tokens replaced by actual data. Ctl_newRecordId will be appended to the ctl_userdata if the ctl_action is used and new record is created successfully.

resultCode

The result of the ctl_action. The possible values are: 'SUCCESS', 'FAIL' or 'IGNORE'.

errorString

The error message for the failure action.

Examples

Example 1:

The following URL shows the custom link that can be used to trigger creation of 'Task' record on SFDC for the 'account' record that the click-to-dial running on.
https://mycontactual.com/AGUI/make_call.php? prefix=&phone={!Account.Phone}&callerId=5251990&ctl_userdata=
[ctl_action|create][subject|outbound%20call%20log%20($transaction_id$)][Transactionid__c|$interaction_guid$]
[ObjectType|Task][WhatId|{!Account.Id}][status|completed][Description|My%20Own%20Description%0Acall%20
answered%20at$equal$%20$call_answered_time$%0Acall%20hangup%20at:%20$call_hangup_time$%0ATransaction%20
Codes%20$equal$%20$transaction_codes$][ctl_parentid|{!Account.Id}][ctl_launchopt|true][ctl_launchext|edit]
[ctl_intType|sfdc][ActivityDate|$year$-$month$-$date$]

The result of the URL will make an outbound call to the phone number specified in the phone field of the corresponding 'Account' record. After the outbound call is completed, all the tokens will be replaced by actual data. Then, a task record with subject, description, status, transactionid__c, whatid and activitydate is created. After creation operation is done, screenpop window will be launched with the newly created task record in edit mode. Agent can modify and save the record or simply cancel the change to go back to the parent record.

account-link

 

account-link

 

dialing

 

talking

 

end-pop

 

save-ah

Example 2:

The following URL shows the click-to-dial link that can be used to trigger screenpop to post click-to-dial configured data to screenpop URL.
https://mycontactual.com/AGUI/make_call.php? prefix=1&phone=6502022222&ctl_userdata=[foreign_key|12345678]
[Transactionid|$interaction_guid$]
[start_time|$call_answered_time][end_time|$call_hangup_time$]
[transaction_codes|$transaction_codes$][ctl_launchopt|true][customer_id|123456567]

custom-customer

calling

custom-screenpop

Example 3:

The following URL shows the click-to-dial link that can be used to perform outbound call and trigger callback to the URL specified.
https://mycontactual.com/AGUI/make_call.php? prefix=&phone=5355566234&ctl_userdata=[foreign_key|12345678]
[Transactionid|$interaction_guid$][start_time|$call_answered_time][end_time|$call_hangup_time$]
[transaction_codes|$transaction_codes$][ctl_callbackUrl|http://www.mycompany.com/clicktodial/callback?
transaction=$transaction_id$]
Share