Click-to-FindMe List

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

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

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

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

1 or 2

1 - Call phone_to_call first (default)
2 - Call the FindMe first

Determines the order in which the various numbers are dialed

page

String

255

Will be stored in the Smart Click-to-Call Report

Defines the "page" the Click-to-FindMe originated from.

no_answer_email

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

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

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

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

1 or 2

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

String

TBD

Only 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_type

1 or 2

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

1 to 5

Loop count 1 is the default

Number of times to go through the call list before triggering last action

randomize

0 or 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

0 or 1

0 - Do not record the call (default)
1 - Record the call

Determine if the call should be recorded once connected

no_intro

0 or 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

0 or 1

Only 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_method

0 or 1 or 2

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

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

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

0 or 1 or 2

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

10 through 60

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

String

TBD

Only available when use_screen=0

Message is whispered via text-to-speech

Message whispered to the operator

nextaction

1 through 7

Only 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

nextactionitem

Building Block ID

n/a

Only 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

ref

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

Not required

Tell user no one is available and disconnect.

Voice Mailbox ID

Transfer to Voice Mail

Not required

Automatically transfer the call to the last number tried in the list

Virtual Receptionist ID

Transfer to Virtual Receptionist

FindMe ID

Transfer to FindMe

SurVo/IVR ID

Transfer to SurVo/IVR

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 Example 1

<?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 = "no-reply@example.net";
	$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

Success

Failed

<?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.

SMS

URL*

To: no-reply@example.net
From: LeadResponse@ifbyphone.com
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.

DialogTech's API Documentation

DialogTech API Overview

Administration APIs

Call Initiation APIs

SMS APIs

Reporting APIs

New APIs

Webhooks

Legacy Documentation

Use the Click-to-FindMe List API to initiate a phone call with a click of a mouse.

Base URL for Click-to-FindMe List

Parameter List

FindMe Experience Config Parameters

Next Action Options

Using this API

Example Response

No Answer Email/SMS/URL Examples