{"_id":"558dbe567afc102f008ed8a9","category":{"_id":"558db0bc7afc102f008ed863","pages":["558dbe324cd25f0d00b7ecce","558dbe407afc102f008ed8a4","558dbe567afc102f008ed8a9","558dbe677afc102f008ed8ac","558dbe7e4cd25f0d00b7ecd0","558dbea37afc102f008ed8b2","558dbeb27afc102f008ed8b4","558dbec14cd25f0d00b7ecd2","558dbed0beb7c719007f63b4","558dbf61beb7c719007f63ba"],"version":"558d9c33beb7c719007f631c","project":"558d9c32beb7c719007f6319","__v":10,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-06-26T20:06:20.813Z","from_sync":false,"order":2,"slug":"call-initiation-api","title":"Call Initiation APIs"},"user":"558d70614cd25f0d00b7eba4","version":{"_id":"558d9c33beb7c719007f631c","project":"558d9c32beb7c719007f6319","__v":19,"createdAt":"2015-06-26T18:38:43.154Z","releaseDate":"2015-06-26T18:38:43.153Z","categories":["558d9c33beb7c719007f631d","558db0bc7afc102f008ed863","558db0d07afc102f008ed864","558db3c84cd25f0d00b7ecb2","558dbace7afc102f008ed894","558dbd104cd25f0d00b7ecca","558dbd4c4cd25f0d00b7eccb","559d3e858639bd21008e90a6","55bb8ca5a8400c2d00873e70","58fdfb438fbd2819000db9eb","590829c7ade4172d006a87b8","59082a11beedcf0f00235d87","5908bd2cba2afd23007d6d12","5908d1f64f544425002b6aae","591e5e9e2c1b1f0f000fa4e5","5a283434aba91f002834ea86","5a69fe5cde745d002c936c66","5a81e6ef761cf300127317f8","5a81e7d63b1e120012bed5a1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"githubsync":"","__v":48,"project":"558d9c32beb7c719007f6319","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-26T21:04:22.433Z","link_external":false,"link_url":"","sync_unique":"","hidden":true,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Use the Click-to-FindMe API to initiate a phone call with a click of a mouse.\"\n}\n[/block]\nThe Click-to-FindMe API is used to initiate a phone call between one phone number and any one number from a predefined list of phone numbers defined in an existing FindMe within a DialogTech account. The order in which the numbers are called -- either the predefined list first, or the 3rd party first -- can be modified.\n\nIf the list of numbers/agents is not static and can change call to call, our [Click-to-FindMe List](doc:click-to-findme-list) API would be a better option.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Base URL for Click-to-FindMe\",\n  \"body\": \"https://secure.dialogtech.com/ibp_api.php\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Parameter List\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Accepts\",\n    \"0-0\": \"access_key\",\n    \"0-1\": \"Yes* (See Notes)\",\n    \"1-0\": \"secret_access_key\",\n    \"1-2\": \"String\",\n    \"2-0\": \"action\",\n    \"2-1\": \"Yes\",\n    \"7-0\": \"type\",\n    \"7-2\": \"String: **1** or **2**\",\n    \"9-0\": \"no_answer_email\",\n    \"9-2\": \"String: Email Address\",\n    \"9-1\": \"No\",\n    \"10-0\": \"no_answer_sms\",\n    \"10-2\": \"String: Unformatted Phone Number\",\n    \"11-0\": \"no_answer_url\",\n    \"11-2\": \"String: URL\",\n    \"12-0\": \"no_answer_phone\",\n    \"12-1\": \"No\",\n    \"1-1\": \"Yes* (See Notes)\",\n    \"0-2\": \"String\",\n    \"2-2\": \"String: **clickto.findme**\",\n    \"7-1\": \"No\",\n    \"h-3\": \"Max Length\",\n    \"0-3\": \"n/a\",\n    \"10-1\": \"No\",\n    \"h-4\": \"Notes\",\n    \"h-5\": \"Usage\",\n    \"0-4\": \"Access Key from the Key Manager within a DialogTech account\",\n    \"0-5\": \"Credentials used for access to the API for a particular DialogTech account\",\n    \"1-4\": \"Secret Access Key from the Key Manager within a DialogTech account\",\n    \"1-3\": \"n/a\",\n    \"2-3\": \"n/a\",\n    \"2-4\": \"Only accepts **clickto.findme** for Click-to-FindMe\",\n    \"7-4\": \"1 - Call **phone_to_call** first (default)\\n2 - Call the FindMe first\",\n    \"7-3\": \"n/a\",\n    \"9-3\": \"n/a\",\n    \"10-3\": \"n/a\",\n    \"1-5\": \"Credentials used for access to the API for a particular DialogTech account\",\n    \"2-5\": \"Defines the API call as a \\\"Click-to-FindMe\\\" type\",\n    \"7-5\": \"Determines the order in which the various numbers are dialed\",\n    \"9-4\": \"Only available when *type=2*\",\n    \"9-5\": \"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.\",\n    \"10-5\": \"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.\",\n    \"11-1\": \"No\",\n    \"11-3\": \"n/a\",\n    \"11-4\": \"Only available when *type=2*\",\n    \"11-5\": \"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.\",\n    \"12-5\": \"Define a phone number to do a blind transfer of the call to if no one on the phone list accepts the call.\",\n    \"12-2\": \"String: Unformatted Phone Number\",\n    \"12-3\": \"n/a\",\n    \"12-4\": \"Only available when *type=2*\",\n    \"10-4\": \"Only available when *type=2*\",\n    \"3-0\": \"findme_id\",\n    \"3-1\": \"Yes\",\n    \"3-2\": \"String: Existing FindMe ID\",\n    \"3-3\": \"n/a\",\n    \"3-4\": \"An existing FindMe ID must be utilized. To find IDs for any existing FindMe within your account, enter the menu *Developer Tools* **->** *Building Block IDs*\",\n    \"3-5\": \"Determines which pre-defined list of numbers will be attempted to join any one number from that group, to the *phone_to_call* third party.\",\n    \"4-0\": \"phone_to_call\",\n    \"4-1\": \"Yes\",\n    \"4-2\": \"String: Unformatted Phone Number\",\n    \"4-3\": \"n/a\",\n    \"4-4\": \"Can be any unformatted phone number\",\n    \"4-5\": \"Defines the third party being joined to the pre-defined list of numbers in a Click-to-FindMe\",\n    \"5-0\": \"first_callerid\",\n    \"5-1\": \"No\",\n    \"5-2\": \"String: Unformatted Phone Number\",\n    \"5-3\": \"n/a\",\n    \"5-4\": \"Must be a registered number or a tracking number within the DialogTech account.\",\n    \"5-5\": \"Defines the Caller ID utilized on the first leg of the call\",\n    \"6-0\": \"second_callerid\",\n    \"6-1\": \"No\",\n    \"6-2\": \"String: Unformatted Phone Number\",\n    \"6-3\": \"n/a\",\n    \"6-4\": \"Must be a registered number or a tracking number within the DialogTech account.\",\n    \"6-5\": \"Defines the Caller ID utilized on the second leg of the call\",\n    \"8-0\": \"page\",\n    \"8-1\": \"No\",\n    \"8-2\": \"String\",\n    \"8-3\": \"255\",\n    \"8-4\": \"Will be stored in the *Smart Click-to-Call Report*\",\n    \"8-5\": \"Defines the \\\"page\\\" the Click-to-FindMe originated from.\"\n  },\n  \"cols\": 6,\n  \"rows\": 13\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Using this API\"\n}\n[/block]\nThese code examples are meant to show a basic method of accessing DialogTech's click-to-FindMe API.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n  /*\\n    Click-to-FindMe:\\n    This example will use access_key and secret_access_key\\n    for a Reverse FindMe -- This means we'll be calling\\n    the predefined list of numbers first, then the third\\n    party.\\n  */\\n\\n  // create curl resource\\n  $ch = curl_init(); \\n  $baseuri = \\\"https://secure.dialogtech.com/ibp_api.php?\\\";\\n\\n  // API Specific Static Parameters\\n  $action = \\\"clickto.findme\\\";\\n\\n  // Required User Parameters\\n  $access_key = \\\"foo\\\";\\n  $secret_access_key = \\\"bar\\\";\\n  $type = \\\"2\\\";\\n  $findme_id = \\\"98765\\\";\\n  $phone_to_call = \\\"5551112222\\\";\\n  $page = \\\"LeadResponse.html\\\";\\n  $first_callerid = \\\"9998887777\\\"; // Will display as the Caller ID for the predefined list recipient as type=2\\n  $second_callerid = \\\"8887776666\\\"; // Will display as the Caller ID for the phone_to_call as type=2\\n  $no_answer_email = \\\"no-reply:::at:::test.com\\\";\\n  $no_answer_sms = \\\"5554443333\\\";\\n  $no_answer_url = \\\"https://test.com/no_answer_listener.php\\\";\\n\\n  // Construct the full URL\\n  $full_url = $baseuri . \\\"&action=\\\" . $action .\\n    \\\"&access_key=\\\" . $access_key .\\n    \\\"&secret_access_key=\\\" . $secret_access_key .\\n    \\\"&type=\\\" . $type .\\n    \\\"&findme_id=\\\" . $findme_id .\\n    \\\"&phone_to_call=\\\" . $phone_to_call .\\n    \\\"&page=\\\" . $page .\\n    \\\"&first_callerid=\\\" . $first_callerid .\\n    \\\"&second_callerid=\\\" . $second_callerid .\\n    \\\"&no_answer_email=\\\" . $no_answer_email .\\n    \\\"&no_answer_sms=\\\" . $no_answer_sms .\\n    \\\"&no_answer_url=\\\" . $no_answer_url;\\n\\n  // Set the URL\\n  curl_setopt($ch, CURLOPT_URL, $full_url);\\n\\n  // Sets the return options of the cURL to return the actual result from the curl request, and FALSE on failure\\n  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);\\n\\n  // Sets the $output variable to the result of the curl\\n  $output = curl_exec($ch);\\n\\n  // Close curl resource to free up system resources\\n  curl_close($ch);\\n\\n  // Send the API output to the php page\\n  echo \\\"API response is: \\\" . $output;\\n?>\",\n      \"language\": \"php\",\n      \"name\": \"PHP Example 1\"\n    },\n    {\n      \"code\": \"<?php\\n\\t/*\\n\\t\\tClick-to-FindMe:\\n\\t\\tThis example will use access_key and secret_access_key\\n\\t\\tfor a normal Click-to-FindMe -- This means we'll be calling\\n\\t\\tthe a third party first, then the predefined list of\\n\\t\\tnumbers second. Using access_key and secret_access_key means \\n\\t\\t'key' is not required.\\n\\t*/\\n\\n\\t// create curl resource\\n\\t$ch = curl_init();\\n\\t$baseuri = \\\"https://secure.dialogtech.com/click_to_xyz.php?\\\";\\n\\n\\t// API Specific Static Parameters\\n\\t$action = \\\"clickto.findme\\\";\\n\\n\\t// Required User Parameters\\n\\t$access_key = \\\"foo\\\";\\n\\t$secret_access_key = \\\"bar\\\";\\n\\t$type = \\\"1\\\";\\n\\t$findme_id = \\\"98765\\\";\\n\\t$phone_to_call = \\\"5551112222\\\";\\n\\t$page = \\\"LeadResponse.html\\\";\\n\\t$first_callerid = \\\"9998887777\\\"; // Will display as the Caller ID for the 'phone_to_call` as type=1\\n\\t$second_callerid = \\\"8887776666\\\"; // Will display as the Caller ID for the predefined-list as type=1\\n\\n\\t// Construct the full URL\\n\\t$full_url = $baseuri . \\\"&action=\\\" . $action .\\n\\t\\t\\\"&access_key=\\\" . $access_key .\\n\\t\\t\\\"&secret_access_key=\\\" . $secret_access_key .\\n\\t\\t\\\"&type=\\\" . $type .\\n\\t\\t\\\"&findme_id=\\\" . $findme_id .\\n\\t\\t\\\"&phone_to_call=\\\" . $phone_to_call .\\n\\t\\t\\\"&page=\\\" . $page .\\n\\t\\t\\\"&first_callerid=\\\" . $first_callerid .\\n\\t\\t\\\"&second_callerid=\\\" . $second_callerid;\\n\\n\\t// Set the URL\\n\\tcurl_setopt($ch, CURLOPT_URL, $full_url);\\n\\n\\t// Sets the return options of the cURL to return the actual result from the curl request, and FALSE on failure\\n\\tcurl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);\\n\\n\\t// Sets the $output variable to the result of the curl\\n\\t$output = curl_exec($ch);\\n\\n\\t// Close curl resource to free up system resources\\n\\tcurl_close($ch);\\n\\n\\t// Send the API output to the php page\\n\\techo $output;\\n?>\",\n      \"language\": \"php\",\n      \"name\": \"PHP Example 2\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Example Response\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Call Connected\",\n      \"language\": \"text\",\n      \"name\": \"Success - type=1\"\n    },\n    {\n      \"code\": \"Requeset Processed\",\n      \"language\": \"text\",\n      \"name\": \"Success - type=2\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"No Answer Email/SMS/URL Examples\"\n}\n[/block]\n\nThese examples were generated by [PHP Example 1](doc:click-to-findme#section-using-this-api) above. FindMe 98765 has one agent with phone number (555) 868-8950 who did not answer their phone. (555) 758-5902 is also an SMS-enabled number within the DialogTech account used.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"To: no-reply@example.net\\nFrom: LeadResponse@ifbyphone.com\\nSubject: LeadResponse unsuccessful for (555) 111-2222\\n\\nAttempts to connect an agent to (555) 111-2222 were unsuccessful, with the following activity breakdown:\\n\\n(555) 868-8950 No Answer\",\n      \"language\": \"text\",\n      \"name\": \"Email\"\n    },\n    {\n      \"code\": \"To: (555) 444-3333\\nFrom: (555) 758-5902\\n\\nMessage: LeadResponse unsuccessful for (555) 111-2222\",\n      \"language\": \"text\",\n      \"name\": \"SMS\"\n    },\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<response>\\n\\t<phone_to_call>5551112222</phone_to_call>\\n\\t<attempts>\\n\\t\\t<attempt>\\n\\t\\t\\t<called_number>5558688950</called_number>\\n\\t\\t\\t<call_result>No Answer</call_result>\\n\\t\\t</attempt>\\n\\t</attempts>\\n</response>\",\n      \"language\": \"text\",\n      \"name\": \"URL*\"\n    }\n  ]\n}\n[/block]\n*URL was delivered as POST Payload to the no_answer_url defined in the API call.","excerpt":"Used to initiate a phone call between one phone number and any one number from a predefined list of phone numbers.","slug":"click-to-findme","type":"basic","title":"Click-to-FindMe"}

Click-to-FindMe

Used to initiate a phone call between one phone number and any one number from a predefined list of phone numbers.

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

The Click-to-FindMe API is used to initiate a phone call between one phone number and any one number from a predefined list of phone numbers defined in an existing FindMe within a DialogTech account. The order in which the numbers are called -- either the predefined list first, or the 3rd party first -- can be modified.

If the list of numbers/agents is not static and can change call to call, our Click-to-FindMe List API would be a better option.

Base URL for Click-to-FindMe

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

Parameter List

Parameter
Required
Accepts
Max Length
Notes
Usage

access_key

Yes* (See Notes)

String

n/a

Access Key from the Key Manager within a DialogTech account

Credentials used for access to the API for a particular DialogTech account

secret_access_key

Yes* (See Notes)

String

n/a

Secret Access Key from the Key Manager within a DialogTech account

Credentials used for access to the API for a particular DialogTech account

action

Yes

String: clickto.findme

n/a

Only accepts clickto.findme for Click-to-FindMe

Defines the API call as a "Click-to-FindMe" type

findme_id

Yes

String: Existing FindMe ID

n/a

An existing FindMe ID must be utilized. To find IDs for any existing FindMe within your account, enter the menu Developer Tools -> Building Block IDs

Determines which pre-defined 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

String: 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

String: 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

String: 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

String: 1 or 2

n/a

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

String: 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

String: 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

String: 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

String: 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.

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:
    This example will use access_key and secret_access_key
    for a Reverse FindMe -- This means we'll be calling
    the predefined list of numbers first, then the third
    party.
  */

  // 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";
  $findme_id = "98765";
  $phone_to_call = "5551112222";
  $page = "LeadResponse.html";
  $first_callerid = "9998887777"; // Will display as the Caller ID for the predefined list recipient as type=2
  $second_callerid = "8887776666"; // Will display as the Caller ID for the phone_to_call as type=2
  $no_answer_email = "no-reply@test.com";
  $no_answer_sms = "5554443333";
  $no_answer_url = "https://test.com/no_answer_listener.php";

  // Construct the full URL
  $full_url = $baseuri . "&action=" . $action .
    "&access_key=" . $access_key .
    "&secret_access_key=" . $secret_access_key .
    "&type=" . $type .
    "&findme_id=" . $findme_id .
    "&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 .
    "&no_answer_url=" . $no_answer_url;

  // 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 "API response is: " . $output;
?>
<?php
	/*
		Click-to-FindMe:
		This example will use access_key and secret_access_key
		for a normal Click-to-FindMe -- This means we'll be calling
		the a third party first, then the predefined list of
		numbers second. Using access_key and secret_access_key means 
		'key' is not required.
	*/

	// create curl resource
	$ch = curl_init();
	$baseuri = "https://secure.dialogtech.com/click_to_xyz.php?";

	// API Specific Static Parameters
	$action = "clickto.findme";

	// Required User Parameters
	$access_key = "foo";
	$secret_access_key = "bar";
	$type = "1";
	$findme_id = "98765";
	$phone_to_call = "5551112222";
	$page = "LeadResponse.html";
	$first_callerid = "9998887777"; // Will display as the Caller ID for the 'phone_to_call` as type=1
	$second_callerid = "8887776666"; // Will display as the Caller ID for the predefined-list as type=1

	// Construct the full URL
	$full_url = $baseuri . "&action=" . $action .
		"&access_key=" . $access_key .
		"&secret_access_key=" . $secret_access_key .
		"&type=" . $type .
		"&findme_id=" . $findme_id .
		"&phone_to_call=" . $phone_to_call .
		"&page=" . $page .
		"&first_callerid=" . $first_callerid .
		"&second_callerid=" . $second_callerid;

	// 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;
?>

Example Response

Call Connected
Requeset Processed

No Answer Email/SMS/URL Examples

These examples were generated by PHP Example 1 above. FindMe 98765 has one agent with phone number (555) 868-8950 who did not answer their phone. (555) 758-5902 is also an SMS-enabled number within the DialogTech account used.

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.