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.
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]
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$]