API & DOCS

My Account            

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

https://secure.dialogtech.com/ibp_api.php

Parameter List

ParameterRequiredAcceptsMax LengthNotesUsage
access_keyYes* (See Notes)Stringn/aIf 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_keyYes* (See Notes)Stringn/aIf 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
keyYes* (See Notes)Stringn/aIf 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
actionYesclickto.findmen/aOnly accepts clickto.findme for Click-to-FindMeDefines the API call as a "Click-to-FindMe" type
listYesPipe delimitated list of unformatted phone numbersn/aAn 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_callYesUnformatted Phone Numbern/aCan be any unformatted phone numberDefines the third party being joined to the pre-defined list of numbers in a Click-to-FindMe
first_calleridNoUnformatted Phone Numbern/aMust 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_calleridNoUnformatted Phone Numbern/aMust be a registered number or a tracking number within the DialogTech account.Defines the Caller ID utilized on the second leg of the call
typeNo1 or 211 - Call phone_to_call first (default)
2 - Call the FindMe first
Determines the order in which the various numbers are dialed
pageNoString255Will be stored in the Smart Click-to-Call ReportDefines the "page" the Click-to-FindMe originated from.
no_answer_emailNoEmail Addressn/aOnly available when type=2Define 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_smsNoUnformatted Phone Numbern/aOnly available when type=2Define 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_urlNoURLn/aOnly available when type=2Define 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_phoneNoUnformatted Phone Numbern/aOnly available when type=2Define 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

ParameterRequiredAcceptsMax LengthNotesUsage
dtmf_onlyNo1 or 210 - 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_promptNoStringTBDOnly available when type=1

Lets 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_typeNo1 or 211 - 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_countNo1 to 51Loop count 1 is the defaultNumber of times to go through the call list before triggering last action
randomizeNo0 or 110 - 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.
recordNo0 or 110 - Do not record the call (default)
1 - Record the call
Determine if the call should be recorded once connected
no_introNo0 or 110 - 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_screenNo0 or 11Only available when type=1

0 - Do not screen the phone_to_call third party for their name
1 - 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_methodNo0 or 1 or 210 - 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.
holdmusicNoString: Filename (ex filename.wav)n/aName of music file located in the holdme directory in Audio File MaintenanceHold music to play for the caller while waiting for the operator to accept the call.
usr_audio_prompt_set_idNoID of an existing Custom Audio Prompt Set from a FindMen/aPlease contact our support team for assistance in utilizing this parameterDefines the custom audio prompts used for for the caller and agent(s) in a FindMe List
holdrepeatNo0 or 1 or 210 - 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.
timeoutNo10 through 602Values 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_phraseNoStringTBDOnly available when use_screen=0

Message is whispered via text-to-speech
Message whispered to the operator
nextactionNo1 through 71Only available when type=1

See "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
nextactionitemNoBuilding Block IDn/aOnly available when type=1

See "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
refNoString255Will be stored in the Smart Click-to-Call ReportAn 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 Valuenextactionitem ValueDescription
1Not requiredTell user no one is available and disconnect.
2Voice Mailbox IDTransfer to Voice Mail
3Not requiredAutomatically transfer the call to the last number tried in the list
4Virtual Receptionist IDTransfer to Virtual Receptionist
5FindMe IDTransfer to FindMe
6SurVo/IVR IDTransfer to SurVo/IVR
7Not requiredAutomatically 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.