Used to initiate a phone call between one phone number and any one number from a dynamic list of phone numbers.
Use the Click-to-FindMe List API to initiate a phone call with a click of a mouse.
The Click-to-FindMe List API is used to initiate a phone call between one phone number and any one number from a dynamic list of phone numbers defined in at the time the Click-to-FindMe List API is called. The order in which the numbers are called -- either the list first, or the 3rd party first -- can be modified.
If the list of numbers/agents is static and the caller experience requires no change call-to-call, our Click-to-FindMe API would be a better option.
Base URL for Click-to-FindMe List
Parameter List
| Parameter | Required | Accepts | Max Length | Notes | Usage |
|---|---|---|---|---|---|
| access_key | Yes* (See Notes) | String | n/a | If using access_key, secret_access_key is required. The parameter key is not required in this case. | Credentials used for access to the API for a particular DialogTech account |
| secret_access_key | Yes* (See Notes) | String | n/a | If using secret_access_key, access_key is required. The parameter key is not required in this case. | Credentials used for access to the API for a particular DialogTech account |
| key | Yes* (See Notes) | String | n/a | If using key, both access_key and secret_access_key are not required. The parameter key is required in this case. | Public API key used for limited access to the API for a particular DialogTech account |
| action | Yes | clickto.findme | n/a | Only accepts clickto.findme for Click-to-FindMe | Defines the API call as a "Click-to-FindMe" type |
| list | Yes | Pipe delimitated list of unformatted phone numbers | n/a | An list of phone numbers, pipe delimitated, in which any one is a valid recipient to be connected to the phone_to_call number. | Determines which list of numbers will be attempted to join any one number from that group, to the phone_to_call third party. |
| phone_to_call | Yes | Unformatted Phone Number | n/a | Can be any unformatted phone number | Defines the third party being joined to the pre-defined list of numbers in a Click-to-FindMe |
| first_callerid | No | Unformatted Phone Number | n/a | Must be a registered number or a tracking number within the DialogTech account. | Defines the Caller ID utilized on the first leg of the call |
| second_callerid | No | Unformatted Phone Number | n/a | Must be a registered number or a tracking number within the DialogTech account. | Defines the Caller ID utilized on the second leg of the call |
| type | No | 1 or 2 | 1 | 1 - Call phone_to_call first (default)2 - Call the FindMe first | Determines the order in which the various numbers are dialed |
| page | No | String | 255 | Will be stored in the Smart Click-to-Call Report | Defines the "page" the Click-to-FindMe originated from. |
| no_answer_email | No | Email Address | n/a | Only available when type=2 | Define an email address to send an email to if no one on the phone list accepts the call. This email will include the phone_to_call along with the outcome of each attempt to the phone numbers on the list. |
| no_answer_sms | No | Unformatted Phone Number | n/a | Only available when type=2 | Define a phone number to receive an SMS message if no one on the phone list accepts the call. The text will say that the call was unsuccessful along with the phone_to_call. You must have at least one phone number registered for SMS to utilize this feature. |
| no_answer_url | No | URL | n/a | Only available when type=2 | Define a URL to post XML data to if no one on the phone list accepts the call. This data will include the phone_to_call along with the outcome of each attempt of the phone numbers on the list. |
| no_answer_phone | No | Unformatted Phone Number | n/a | Only available when type=2 | Define a phone number to do a blind transfer of the call to if no one on the phone list accepts the call. |
FindMe Experience Config Parameters
| Parameter | Required | Accepts | Max Length | Notes | Usage |
|---|---|---|---|---|---|
| dtmf_only | No | 1 or 2 | 1 | 0 - Allow the operator to accept the call using "Yes" or keypad press 1 - Force the operator to use their Keypad to accept the call | Force the operator to use their Keypad to accept the call |
| screen_prompt | No | String | TBD | Only available when type=1Lets you provide an announcement that will be read to the caller using text-to-speech. If you use screen_prompt to provide your own announcement, you should bear in mind that the call will play a beep and start recording, and that if the caller does not leave a name, the callee will get a "Name not provided" message. You can change this default behavior by using the use_screen parameter. | Provide a custom text-to-speech screening prompt for use with use_screen |
| usr_findme_type | No | 1 or 2 | 1 | 1 - Individual FindMe (default) 2 - Customer service hunt group | Determines the default audio prompts within the FindMe to sound like it's trying to reach an individual, or a member of a team |
| loop_count | No | 1 to 5 | 1 | Loop count 1 is the default | Number of times to go through the call list before triggering last action |
| randomize | No | 0 or 1 | 1 | 0 - Do not randomize the list order (default) 1 - Randomize the list order | Specify if the order in which numbers are attempted from the list parameter is randomized. |
| record | No | 0 or 1 | 1 | 0 - Do not record the call (default) 1 - Record the call | Determine if the call should be recorded once connected |
| no_intro | No | 0 or 1 | 1 | 0 - Disable screening audio prompts 1 - Enable screening audio prompts (default) | Determines if the audio prompts for screening the phone_to_call are enabled or not |
| use_screen | No | 0 or 1 | 1 | Only available when type=10 - Do not screen the phone_to_call third party for their name1 - Screen the phone_to_call third party for their name (default) | Determine if the phone_to_call third party should be prompted for their name |
| screen_method | No | 0 or 1 or 2 | 1 | 0 - Whisper the third party's name to the list number 1 - Whisper text to the list number 2 - Whisper audio to the list number | Determines the type of screening presented to the recipient of the call. |
| holdmusic | No | String: Filename (ex filename.wav) | n/a | Name of music file located in the holdme directory in Audio File Maintenance | Hold music to play for the caller while waiting for the operator to accept the call. |
| usr_audio_prompt_set_id | No | ID of an existing Custom Audio Prompt Set from a FindMe | n/a | Please contact our support team for assistance in utilizing this parameter | Defines the custom audio prompts used for for the caller and agent(s) in a FindMe List |
| holdrepeat | No | 0 or 1 or 2 | 1 | 0 - Repeat hold music only once per FindMe session 1 - Repeat hold music only once between each FindMe attempt 2 - Repeat hold music continuously between FindMe attempts | Define how the hold music experience is for the caller. |
| timeout | No | 10 through 60 | 2 | Values can be anywhere from 10-60, Default is 30. | Define the number of seconds each number within the list is attempted before that number is determined to be "No answer" and the next number, or nextaction is attempted |
| whisper_phrase | No | String | TBD | Only available when use_screen=0Message is whispered via text-to-speech | Message whispered to the operator |
| nextaction | No | 1 through 7 | 1 | Only available when type=1See "Next Action" options below | Defines the application type that the call will transfer to if none of the numbers in the list accept the call |
| nextactionitem | No | Building Block ID | n/a | Only available when type=1See "Next Action" options below | Defines the specific building block that the call will transfer to if none of the numbers in the list accept the call |
| ref | No | String | 255 | Will be stored in the Smart Click-to-Call Report | An available field where a custom reference can be stored |
Next Action Options
These values are accepted for the nextaction and nextactionitem parameters above when all the numbers in the FindMe list fail to get connected to the third party phone_to_call
| nextaction Value | nextactionitem Value | Description |
|---|---|---|
| 1 | Not required | Tell user no one is available and disconnect. |
| 2 | Voice Mailbox ID | Transfer to Voice Mail |
| 3 | Not required | Automatically transfer the call to the last number tried in the list |
| 4 | Virtual Receptionist ID | Transfer to Virtual Receptionist |
| 5 | FindMe ID | Transfer to FindMe |
| 6 | SurVo/IVR ID | Transfer to SurVo/IVR |
| 7 | Not required | Automatically transfer the call to the last number tried in the list without introduction |
Using this API
These code examples are meant to show a basic method of accessing DialogTech's click-to-FindMe API.
<?php
/*
Click-to-FindMe List EX1:
This example will use access_key and secret_access_key
for a Reverse FindMe List -- This means we'll be calling
the dynamic list of numbers first, then the third
party. Using access_key and secret_access_key means
'key' is not required.
*/
// create curl resource
$ch = curl_init();
$baseuri = "https://secure.dialogtech.com/ibp_api.php?";
// API Specific Static Parameters
$action = "clickto.findme";
// Required User Parameters
$access_key = "foo";
$secret_access_key = "bar";
$type = "2";
$list = "5559998888|5559997777";
$phone_to_call = "5551112222";
$page = "LeadResponse.html";
$first_callerid = "9998887777"; // Will display as the Caller ID for the 'phone_to_call' recipient as type=1
$second_callerid = "8887776666"; // Will display as the Caller ID for the 'id' recipient as type=1
$no_answer_email = "[email protected]";
$no_answer_sms = "5554443333";
// Construct the full URL
$full_url = $baseuri . "&action=" . $action .
"&access_key=" . $access_key .
"&secret_access_key=" . $secret_access_key .
"&type=" . $type .
"&list=" . $list .
"&phone_to_call=" . $phone_to_call .
"&page=" . $page .
"&first_callerid=" . $first_callerid .
"&second_callerid=" . $second_callerid .
"&no_answer_email=" . $no_answer_email .
"&no_answer_sms=" . $no_answer_sms;
// Set the URL
curl_setopt($ch, CURLOPT_URL, $full_url);
// Sets the return options of the cURL to return the actual result from the curl request, and FALSE on failure
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Sets the $output variable to the result of the curl
$output = curl_exec($ch);
// Close curl resource to free up system resources
curl_close($ch);
// Send the API output to the php page
echo $output;
?>
When requesting the click-to-call API, the client side response will only populate after the first leg of the call is answered or not. The response will be a plain-text string indicating the success/failure of the first leg of the call.
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE response [
<!ELEMENT response (result,result_description,sid)>
<!ELEMENT result (#PCDATA)>
<!ELEMENT result_description (#PCDATA)>
<!ELEMENT sid (#PCDATA)>
]>
<response>
<result>success</result>
<result_description>Call Connected</result_description>
<sid>181127fc48636186</sid>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE response [
<!ELEMENT response (result,result_description,sid)>
<!ELEMENT result (#PCDATA)>
<!ELEMENT result_description (#PCDATA)>
<!ELEMENT sid (#PCDATA)>
]>
<response>
<result>failed</result>
<result_description>unknown</result_description>
<sid>181127fa636be04c</sid>
</response>
No Answer Email/SMS/URL Examples
These examples were generated by an example very similar to PHP Example 1 above.
To: [email protected]
From: [email protected]
Subject: LeadResponse unsuccessful for (555) 111-2222
Attempts to connect an agent to (555) 111-2222 were unsuccessful, with the following activity breakdown:
(555) 868-8950 No Answer
To: (555) 444-3333
From: (555) 758-5902
Message: LeadResponse unsuccessful for (555) 111-2222
<?xml version="1.0" encoding="UTF-8"?>
<response>
<phone_to_call>5551112222</phone_to_call>
<attempts>
<attempt>
<called_number>5558688950</called_number>
<call_result>No Answer</call_result>
</attempt>
</attempts>
</response>
*URL was delivered as POST Payload to the no_answer_url defined in the API call.