{"_id":"59b820bea2d5550038e249fa","project":"558d9c32beb7c719007f6319","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"},"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":"58cadf93d223510f005d27db","githubsync":"","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-12T18:00:30.559Z","link_external":false,"link_url":"","sync_unique":"","hidden":true,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Use the Click-to-IVR API to initiate a phone call to a pre-configured IVR\"\n}\n[/block]\nThe Click-to-IVR API is used to initiate a phone call between any one number, or list of numbers, to a pre-configured IVR within an account.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Base URL for Click-to-IVR\",\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\",\n    \"3-0\": \"survo_id\",\n    \"3-1\": \"Yes\",\n    \"1-0\": \"secret_access_key\",\n    \"1-2\": \"String\",\n    \"4-0\": \"action\",\n    \"4-1\": \"Yes\",\n    \"1-1\": \"Yes\",\n    \"0-2\": \"String\",\n    \"3-2\": \"String\",\n    \"4-2\": \"**clickto.survo**\",\n    \"h-3\": \"Max Length\",\n    \"0-3\": \"n/a\",\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    \"3-4\": \"The ID of the IVR being used. The IDs of the various IVRs in an account can be found under **Developer Tools** by selecting **Building Block IDs**\",\n    \"1-3\": \"n/a\",\n    \"3-3\": \"n/a\",\n    \"4-3\": \"n/a\",\n    \"4-4\": \"Only accepts **clickto.survo** for Click-to-IVR\",\n    \"1-5\": \"Credentials used for access to the API for a particular DialogTech account\",\n    \"3-5\": \"Defines the IVR which the caller(s) will be connected to.\",\n    \"4-5\": \"Defines the API call as a \\\"Click-to-IVR\\\" type\",\n    \"5-0\": \"user_parameters\",\n    \"5-1\": \"No\",\n    \"5-2\": \"Pipe Delimitated List of parameters. See section IVR User Parameter Substitution below.\",\n    \"5-3\": \"n/a\",\n    \"5-4\": \"A list of custom parameters to use within the IVR Prompts.\",\n    \"5-5\": \"Custom parameters that can be utilized in text-to-speech prompts within an IVR.\",\n    \"6-0\": \"p_t\",\n    \"6-1\": \"No\",\n    \"6-2\": \"String\",\n    \"6-3\": \"n/a\",\n    \"6-4\": \"Pass-through data are parameters which can be added to a clickto.survo API call, which will be included within any subsequent webhooks from that IVR for the initiated call. (See [IVR WebHooks](doc:webhook-overview#section-using-pass-through-data) for more detailed usage).\",\n    \"6-5\": \"Pass-through Data\",\n    \"8-0\": \"first_callerid\",\n    \"8-1\": \"No\",\n    \"8-2\": \"Unformatted Phone Number\",\n    \"8-3\": \"n/a\",\n    \"8-4\": \"Must be a registered number or a tracking number within the DialogTech account.\",\n    \"8-5\": \"Defines the Caller ID being shown to the `phone_to_call` recipient\",\n    \"9-0\": \"scheduleonly\",\n    \"9-1\": \"No\",\n    \"9-2\": \"n/a\",\n    \"9-3\": \"n/a\",\n    \"9-4\": \"This parameter may consist of a name without any value. No call will be placed. *(i.e `&scheduleonly` OR `&scheduleonly=1` if that is easier)*\",\n    \"9-5\": \"See the [Scheduling Arguments Table](doc:click-to-ivr#section-scheduling-arguments) for available scheduling parameters\\n\\n*Failure to provide scheduling arguments will lead to this parameter being ignored*\",\n    \"10-0\": \"page\",\n    \"10-1\": \"No\",\n    \"10-2\": \"String\",\n    \"10-3\": \"255\",\n    \"10-4\": \"Will be stored in the *Smart Click-to-Call Report*\",\n    \"10-5\": \"Defines the \\\"page\\\" the Click-to-IVR originated from.\",\n    \"7-0\": \"phone_to_call\",\n    \"7-1\": \"No\",\n    \"7-2\": \"Unformatted Phone Number\",\n    \"7-3\": \"n/a\",\n    \"7-4\": \"The phone number to call. *Not valid when* `scheduleonly` *is used*\",\n    \"7-5\": \"Defines the phone number being called to be sent to the IVR.\",\n    \"11-0\": \"ref\",\n    \"11-1\": \"No\",\n    \"11-2\": \"String\",\n    \"11-3\": \"255\",\n    \"11-4\": \"Will be stored in the *Smart Click-to-Call Report*\",\n    \"11-5\": \"An available field where a custom reference can be stored\",\n    \"2-0\": \"public_key\",\n    \"2-1\": \"Yes\",\n    \"2-2\": \"String\",\n    \"2-3\": \"n/a\",\n    \"2-4\": \"Public API Key from the Key Manager within a DialogTech account\",\n    \"2-5\": \"*This should only be used when doing a client-side Click-To-IVR and will be used in place of both the access_key and secret_access_key values*\"\n  },\n  \"cols\": 6,\n  \"rows\": 12\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Scheduling Arguments\"\n}\n[/block]\nThe following Scheduling Arguments are only available when the `scheduleonly` parameter is used from the table above.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Accepts\",\n    \"0-0\": \"phone\",\n    \"1-0\": \"sdate\",\n    \"2-0\": \"edate\",\n    \"3-0\": \"dstime\",\n    \"4-0\": \"detime\",\n    \"5-0\": \"tz\",\n    \"6-0\": \"type\",\n    \"0-1\": \"Yes\",\n    \"0-2\": \"Pipe delimitated list of phone numbers OR fully qualified URL to a csv containing at least 1 column called `number` populated with phone numbers\",\n    \"1-1\": \"Yes\",\n    \"1-2\": \"Date/time *(format YYYY-MM-DD+HH:MM)*\",\n    \"2-1\": \"Yes\",\n    \"2-2\": \"Date/time *(format YYYY-MM-DD+HH:MM)*\",\n    \"3-1\": \"Yes\",\n    \"3-2\": \"time *(format HH:MM)*\",\n    \"4-1\": \"Yes\",\n    \"4-2\": \"time *(format HH:MM)*\",\n    \"5-1\": \"No\",\n    \"5-2\": \"`Eastern` *(default)*\\n`Central`\\n`Mountain`\\n`Pacific`\\n`Alaska`\\n`Hawaii`\",\n    \"6-1\": \"No\",\n    \"6-2\": \"`1` OR `2`\",\n    \"h-3\": \"Max Length\",\n    \"7-0\": \"attempts\",\n    \"8-0\": \"retry\",\n    \"9-0\": \"simul\",\n    \"10-0\": \"cid\",\n    \"11-0\": \"desc\",\n    \"7-1\": \"No\",\n    \"8-1\": \"No\",\n    \"9-1\": \"No\",\n    \"10-1\": \"No\",\n    \"11-1\": \"No\",\n    \"h-4\": \"Notes\",\n    \"h-5\": \"Description\",\n    \"0-3\": \"n/a\",\n    \"0-4\": \"This parameter should not be used with `phone_to_call`.\",\n    \"0-5\": \"Defines the recipients of the Click-to-IVR\",\n    \"1-3\": \"n/a\",\n    \"2-3\": \"n/a\",\n    \"3-3\": \"n/a\",\n    \"4-3\": \"n/a\",\n    \"1-5\": \"Defines the Start Date/Time of the broadcast\",\n    \"2-5\": \"Defines the End Date/Time of the broadcast\",\n    \"3-5\": \"Defines the Daily Start Time of the broadcast\",\n    \"4-5\": \"Defines the Daily End Time of the broadcast\",\n    \"1-4\": \"The Start time of a broadcast is the time where the Broadcast first queues up to be processed. *Note: Click-to-IVR calls must be within you broadcast start/end date AND the daily start/end times to be properly scheduled*\",\n    \"2-4\": \"The End time of a broadcast is the time where the Broadcast can last queue up to be processed. *Note: Click-to-IVR calls must be within you broadcast start/end date AND the daily start/end times to be properly scheduled*\",\n    \"3-4\": \"The daily start time defines the beginning time of day calls should be queued and processed. *Note: Click-to-IVR calls must be within you broadcast start/end date AND the daily start/end times to be properly scheduled*\",\n    \"4-4\": \"The daily end time defines the last time of day calls should be queued and processed.  *Note: Click-to-IVR calls must be within you broadcast start/end date AND the daily start/end times to be properly scheduled*\",\n    \"5-3\": \"n/a\",\n    \"5-4\": \"Time zone selected must be from the list of accepted values.\",\n    \"5-5\": \"Defines the time zone the Daily Start and End Times, as well as the Broadcast Start and End dates correlate to.\",\n    \"6-3\": \"n/a\",\n    \"6-4\": \"`1` - Spread Calls Evenly\\n`2` - As Fast as Possible\",\n    \"6-5\": \"Determines how calls are scheduled throughout the broadcast\",\n    \"7-2\": \"`1` *(default)* OR `2`\",\n    \"7-5\": \"Defines the maximum amount of times the call will be re-attempted if the call fails to reach the recipient due to a Busy signal, congestion, or other issue in trying to connect to the recipient. *NOTE: This does not apply to voicemails as voicemails are valid recipients of broadcasts*\",\n    \"7-3\": \"n/a\",\n    \"7-4\": \"`1` - Do not retry failed calls *(default)*\\n`2` - Retry any failed calls one time\",\n    \"8-2\": \"`5` *(default)*, `10`, `15`, `30`, `60`, `90`, `120`\",\n    \"8-3\": \"n/a\",\n    \"8-4\": \"`retry` value selected must be from the list of accepted values.\",\n    \"8-5\": \"Defines the minutes between a call failure and any retry attempts. *Note: `attempts` must be enabled*\",\n    \"9-5\": \"Defines the number of simultaneous calls to be placed. This is based on the number of available smart broadcast ports within the account.\",\n    \"9-4\": \"The maximum value is based on the number of available smart broadcast ports within the account.\",\n    \"9-3\": \"n/a\",\n    \"9-2\": \"Integer\",\n    \"10-2\": \"Unformatted Phone Number\",\n    \"10-4\": \"Must be a registered number or a tracking number within the DialogTech account.\",\n    \"10-3\": \"n/a\",\n    \"10-5\": \"Defines the Caller ID being shown to the broadcast recipient(s)\",\n    \"11-2\": \"String\",\n    \"11-3\": \"32\",\n    \"11-4\": \"Default is `My SurVo Broadcast`\",\n    \"11-5\": \"Identifier for the Voice Broadcast used on account's broadcast management page.\"\n  },\n  \"cols\": 6,\n  \"rows\": 12\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Using this API\"\n}\n[/block]\nWhen 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.\n\n\n[block:api-header]\n{\n  \"title\": \"Example Responses\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"Call Connected\\\"\",\n      \"language\": \"text\",\n      \"name\": \"Client Side Response\"\n    },\n    {\n      \"code\": \"<response>\\n<result>success</result>\\n<result_description>Call Connected</result_description>\\n<sid>1503112581994d3a</sid>\\n</response>\",\n      \"language\": \"text\",\n      \"name\": \"Server Side Response\"\n    },\n    {\n      \"code\": \"<response>\\n<result>success</result>\\n<result_description>1 Voice Broadcast(s) scheduled. Broadcast ID: 4887</result_description>\\n<basic_broadcast_id>4887</basic_broadcast_id>\\n<survo_id>890</survo_id>\\n</response>\",\n      \"language\": \"text\",\n      \"name\": \"Server Side Response For Broadcast\"\n    }\n  ]\n}\n[/block]","excerpt":"Used to initiate a phone call between any one number, or list of numbers, to a pre-configured IVR within an account.","slug":"click-to-ivr","type":"basic","title":"Click-to-IVR"}

Click-to-IVR

Used to initiate a phone call between any one number, or list of numbers, to a pre-configured IVR within an account.

Use the Click-to-IVR API to initiate a phone call to a pre-configured IVR

The Click-to-IVR API is used to initiate a phone call between any one number, or list of numbers, to a pre-configured IVR within an account.

Base URL for Click-to-IVR

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

Parameter List

Parameter
Required
Accepts
Max Length
Notes
Usage

access_key

Yes

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

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

public_key

Yes

String

n/a

Public API Key from the Key Manager within a DialogTech account

This should only be used when doing a client-side Click-To-IVR and will be used in place of both the access_key and secret_access_key values

survo_id

Yes

String

n/a

The ID of the IVR being used. The IDs of the various IVRs in an account can be found under Developer Tools by selecting Building Block IDs

Defines the IVR which the caller(s) will be connected to.

action

Yes

clickto.survo

n/a

Only accepts clickto.survo for Click-to-IVR

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

user_parameters

No

Pipe Delimitated List of parameters. See section IVR User Parameter Substitution below.

n/a

A list of custom parameters to use within the IVR Prompts.

Custom parameters that can be utilized in text-to-speech prompts within an IVR.

p_t

No

String

n/a

Pass-through data are parameters which can be added to a clickto.survo API call, which will be included within any subsequent webhooks from that IVR for the initiated call. (See IVR WebHooks for more detailed usage).

Pass-through Data

phone_to_call

No

Unformatted Phone Number

n/a

The phone number to call. Not valid when scheduleonly is used

Defines the phone number being called to be sent to the IVR.

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 being shown to the phone_to_call recipient

scheduleonly

No

n/a

n/a

This parameter may consist of a name without any value. No call will be placed. (i.e &scheduleonly OR &scheduleonly=1 if that is easier)

See the Scheduling Arguments Table for available scheduling parameters

Failure to provide scheduling arguments will lead to this parameter being ignored

page

No

String

255

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

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

ref

No

String

255

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

An available field where a custom reference can be stored

Scheduling Arguments

The following Scheduling Arguments are only available when the scheduleonly parameter is used from the table above.

Parameter
Required
Accepts
Max Length
Notes
Description

phone

Yes

Pipe delimitated list of phone numbers OR fully qualified URL to a csv containing at least 1 column called number populated with phone numbers

n/a

This parameter should not be used with phone_to_call.

Defines the recipients of the Click-to-IVR

sdate

Yes

Date/time (format YYYY-MM-DD+HH:MM)

n/a

The Start time of a broadcast is the time where the Broadcast first queues up to be processed. Note: Click-to-IVR calls must be within you broadcast start/end date AND the daily start/end times to be properly scheduled

Defines the Start Date/Time of the broadcast

edate

Yes

Date/time (format YYYY-MM-DD+HH:MM)

n/a

The End time of a broadcast is the time where the Broadcast can last queue up to be processed. Note: Click-to-IVR calls must be within you broadcast start/end date AND the daily start/end times to be properly scheduled

Defines the End Date/Time of the broadcast

dstime

Yes

time (format HH:MM)

n/a

The daily start time defines the beginning time of day calls should be queued and processed. Note: Click-to-IVR calls must be within you broadcast start/end date AND the daily start/end times to be properly scheduled

Defines the Daily Start Time of the broadcast

detime

Yes

time (format HH:MM)

n/a

The daily end time defines the last time of day calls should be queued and processed. Note: Click-to-IVR calls must be within you broadcast start/end date AND the daily start/end times to be properly scheduled

Defines the Daily End Time of the broadcast

tz

No

Eastern (default)
Central
Mountain
Pacific
Alaska
Hawaii

n/a

Time zone selected must be from the list of accepted values.

Defines the time zone the Daily Start and End Times, as well as the Broadcast Start and End dates correlate to.

type

No

1 OR 2

n/a

1 - Spread Calls Evenly
2 - As Fast as Possible

Determines how calls are scheduled throughout the broadcast

attempts

No

1 (default) OR 2

n/a

1 - Do not retry failed calls (default)
2 - Retry any failed calls one time

Defines the maximum amount of times the call will be re-attempted if the call fails to reach the recipient due to a Busy signal, congestion, or other issue in trying to connect to the recipient. NOTE: This does not apply to voicemails as voicemails are valid recipients of broadcasts

retry

No

5 (default), 10, 15, 30, 60, 90, 120

n/a

retry value selected must be from the list of accepted values.

Defines the minutes between a call failure and any retry attempts. Note: attempts must be enabled

simul

No

Integer

n/a

The maximum value is based on the number of available smart broadcast ports within the account.

Defines the number of simultaneous calls to be placed. This is based on the number of available smart broadcast ports within the account.

cid

No

Unformatted Phone Number

n/a

Must be a registered number or a tracking number within the DialogTech account.

Defines the Caller ID being shown to the broadcast recipient(s)

desc

No

String

32

Default is My SurVo Broadcast

Identifier for the Voice Broadcast used on account's broadcast management page.

Using this API

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 Responses

"Call Connected"
<response>
<result>success</result>
<result_description>Call Connected</result_description>
<sid>1503112581994d3a</sid>
</response>
<response>
<result>success</result>
<result_description>1 Voice Broadcast(s) scheduled. Broadcast ID: 4887</result_description>
<basic_broadcast_id>4887</basic_broadcast_id>
<survo_id>890</survo_id>
</response>