DialogTech | Control the Conversation.

The Click-to-SurVo API lets you dial 1 or more people and connect them to a pre-configured SurVo in your account. Within your SurVo you can create placeholders for text or phone numbers that can be changed dynamically on every call by passing in your own user parameters.

The calls can be placed immediately or scheduled to go out at a later date and time.

Requests can be made client side (with your Public Key) or server side (with your Access Key and Secret Access Key). Some arguments and the response format vary depending on the request type used.

Client Side Requests (GET or POST method with Public Key)

key (required): Public Key
app (required): Value = cts
survo_id (required): ID of the SurVo.
user_parameters: List of parameters. See section SurVo User Parameter Substitution below.
p_t: Pass-through data.
phone_to_call: Telephone number to call. Not valid if "scheduleonly" flag is set.
scheduleonly: Flag - this parameter may consist of a name without any value. No call placed. See section Schedule Voice Broadcast below.
first_callerid: Caller ID to show to recipients. Must be a registered number.
page (optional): This can be used as a reference for what "page" the Click-to-Call was on. Can be a string of any value and shows up on the Smart Click-to-Call Activity report.
ref (optional): This can be used as a reference for your own use. Can be a string of any value and shows up on the Smart Click-to-Call Activity report.

Notes

If scheduleonly flag is set, see "Schedule Voice Broadcast" arguments below for additional parameters.

Example URL

https://secure.ifbyphone.com/click_to_xyz.php
?app=cts
&phone_to_call=8475551212
&survo_id=890
&key=PUBLIC_KEY

This example will call 847.555.1212 and start SurVo Smart Form ID number 890.

Client Side Response (Text)

"Call Connected"

Schedule Voice Broadcast

The Click-to-SurVo web request can be used to schedule, in advance, a series of telephone calls.

To set the "scheduleonly" parameter, add the line

&scheduleonly

or, if for some reason it's easier, use

&scheduleonly=some_value

If scheduleonly is set, you may use parameters from this next table. Remember that the "phone_to_call" parameter of the previous table is not valid when you use scheduleonly.

Scheduling Arguments

phone (required): The phone number(s) scheduled to receive the SurVo Broadcast call. May be a single phone number, a "|" delimited list of phone numbers, or a fully qualified URL to a web-accessible and valid CSV file. See Notes below. If you use "phone," do not use "phone_to_call."
sdate (required): The official Voice Broadcast starting date/time in the format YYYY-MM-DD HH:MM (24 hour format).
edate (required): The official Voice Broadcast ending date/time in the format YYYY-MM-DD HH:MM (24 hour format). Must be chronologically later than "sdate". Note that this parameter is ignored if the "type" parameter is set to "2" (As fast as possible).
dstime (required): The "Daily Call Range" starting time when Voice Broadcast calls can be made (Valid values meet the HH:MM 24 hour format).
detime (required): The "Daily Call Range" ending time when Voice Broadcast calls can be made (valid values meet the HH:MM 24 hour format and come later in the day than the value for "dstime").
tz: The time zone all specified date/time values are considered to be in. (Valid values are "Eastern", "Central", "Mountain", "Pacific", "Alaska", "Hawaii"; default is "Eastern").
type: The scheduling algorithm to use when scheduling calls for this Voice Broadcast. (Valid values are 1 for "Spread calls evenly" or 2 for "As fast as possible.")
attempts: Maximum number of retry attempts for each phone number. (Valid values are 1 or 2; default is 1 - meaning no retries.)
retry: Number of minutes between retry attempts on a phone number. (Valid values are 5,10,15,30,60,90,120; default is 5.)
simul: Number of simultaneous calls to be placed every freq minutes. (Valid values are 1,2,3; default is 1.)
cid: Caller ID value that shows up to recipients of the Voice Broadcast. (Valid values are any phone number that matches one of the account’s toll free numbers, or is listed in the accounts Registered Phone number list; default is the account’s primary toll free number.)
desc: Identifier for the Voice Broadcast used on the web site's account management page. (Valid values contain alphanumeric characters and spaces; default is "My SurVo Broadcast"; maximum length is 32 characters.)

Example URL with Scheduling

https://secure.ifbyphone.com/click_to_xyz.php
?app=cts
&scheduleonly
&survo_id=890
&key=PUBLIC_KEY
&type=1
&sdate=2024-04-18+11%3A38
&edate=2024-04-19+12%3A03
&tz=Central
&phone=7735551212%7C8475551212
&dstime=00%3A00
&detime=23%3A59

Notes

This URL will schedule a call to two phone numbers and connect those callees to the Click-to-SurVo Smart Form with Building Block ID 890 defined in account 1234. The calls will take place on Oct 30, 2008, starting at 08:48 and ending at 08:58, and the call will be spread out evenly in that time slot. The time zone is set to Central time.

Calls are limited to be between the hours of 00:00 (midnight) and 23:59 (almost midnight), i.e., all day long.

To use a URL with a list of numbers, use (for example)

&phone=http%3A%2F%2Fwww.example.com%2Ffiles%2Fnumberstocall.csv

In this example, the Smart Form will retrieve the CSV file from "http://www.example.com/files/numberstocall.csv" and schedule calls to the numbers given in the file.

If the value of phone is a CSV file, the file must end with ".csv." In addition, the CSV file must have at least one column with the heading "number".

For example, a CSV file can contain one column of names and another of telephone numbers:

"name","number"

"John Q. Public",7735551212

"Mary Public",8475551212

Client Side Response (Text) from scheduling request

The return message for a successful web request will be in the form:

1 Voice Broadcast(s) scheduled. Broadcast ID: 34059

SurVo User Parameter Substitution Example 1

A SurVo can accept values passed in user_parameters to dynamically substitute values in your SurVo. This can be used for things like changing the question text of the SurVo to read back a different message, set the number to transfer to or setting the max duration of a monitored call. This can be done on a per-call basis.

To start with you need to configure your SurVo with the variable(s) you want to substitute. To do this you enclose your named parameter in curly brackets. In the example below we have two parameters: name and date.

Example URL 1 with Parameter Substitution

In the API call we make we will include a name and date parameter in usr_parameters with values that will replace the {name} and {date} text and be read back to the caller. Parameters are submitted as a bar-delimited list of key|value pairs.

https://secure.ifbyphone.com/click_to_xyz.php
?app=cts
&phone_to_call=8475551212
&survo_id=890
&key=PUBLIC_KEY
&user_parameters=name|John Doe||date|May 3rd, 2024

You can include as many key|value pairs as you need for each of your SurVo questions.

Survo User Parameter Substitution Example 2

Here is another example that not only changes the question text dynamically for a monitored call but also the max duration and the number to transfer to as well

Example URL 2 with User Parameter Substitution

https://secure.ifbyphone.com/click_to_xyz.php
?app=cts
&phone_to_call=8475551212
&survo_id=890
&key=PUBLIC_KEY
&user_parameters=name|John Doe||agent|Jane Smith||duration|180||number|3125552020

Server Side Requests (GET or POST method with Access Key and Secret Access Key)

access_key (required): Access Key
secret_access_key (required): Secret Access Key
action (required): Value = clickto.survo
survo_id (required): ID of the SurVo
user_parameters: List of parameters. See section SurVo User Parameter Substitution below.
p_t: Pass-through data.
phone_to_call: Telephone number to call. Not valid if "scheduleonly" flag is set.
scheduleonly: Flag - this parameter may consist of a name without any value. No call placed. See section Schedule Voice Broadcast below.
first_callerid: Caller ID to show to recipients. Must be a registered number.
page (optional): This can be used as a reference for what "page" the Click-to-Call was on. Can be a string of any value and shows up on the Smart Click-to-Call Activity report.
ref (optional): This can be used as a reference for your own use. Can be a string of any value and shows up on the Smart Click-to-Call Activity report.

Notes

If scheduleonly flag is set, see "Schedule Voice Broadcast" arguments below for additional parameters.

Example URL

https://secure.ifbyphone.com/ibp_api.php
?action=clickto.survo
&phone_to_call=8475551212
&survo_id=890
&access_key=ACCESS_KEY
&secret_access_key=SECRET_ACCESS_KEY

This example will call 847.555.1212 and start SurVo Smart Form ID number 890.

Server Side Response (XML)

<result>success</result>

<result_description>Call Connected</result_description>

</response>

Schedule Voice Broadcast with Survo

The Click-to-SurVo web request can be used to schedule, in advance, a series of telephone calls.

To set the "scheduleonly" parameter, add the line

&scheduleonly

or, if for some reason it's easier, use

&scheduleonly=some_value

If scheduleonly is set, you may use parameters from this next table. Remember that the "phone_to_call" parameter of the previous table is not valid when you use scheduleonly.

Scheduling Arguments

phone (required): The phone number(s) scheduled to receive the SurVo Broadcast call. May be a single phone number, a "|" delimited list of phone numbers, or a fully qualified URL to a web-accessible and valid CSV file. See Notes below. If you use "phone," do not use "phone_to_call."
sdate (required): The official Voice Broadcast starting date/time in the format YYYY-MM-DD HH:MM (24 hour format).
edate (required): The official Voice Broadcast ending date/time in the format YYYY-MM-DD HH:MM (24 hour format). Must be chronologically later than "sdate". Note that this parameter is ignored if the "type" parameter is set to "2" (As fast as possible).
dstime (required): The "Daily Call Range" starting time when Voice Broadcast calls can be made (Valid values meet the HH:MM 24 hour format).
detime (required): The "Daily Call Range" ending time when Voice Broadcast calls can be made (valid values meet the HH:MM 24 hour format and come later in the day than the value for "dstime").
tz: The time zone all specified date/time values are considered to be in. (Valid values are "Eastern", "Central", "Mountain", "Pacific", "Alaska", "Hawaii"; default is "Eastern").
type: The scheduling algorithm to use when scheduling calls for this Voice Broadcast. (Valid values are 1 for "Spread calls evenly" or 2 for "As fast as possible.")
attempts: Maximum number of retry attempts for each phone number. (Valid values are 1 or 2; default is 1 - meaning no retries.)
retry: Number of minutes between retry attempts on a phone number. (Valid values are 5,10,15,30,60,90,120; default is 5.)
simul: Number of simultaneous calls to be placed every freq minutes. (Valid values are 1,2,3; default is 1.)
cid: Caller ID value that shows up to recipients of the Voice Broadcast. (Valid values are any phone number that matches one of the account’s toll free numbers, or is listed in the accounts Registered Phone number list; default is the account’s primary toll free number.)
desc: Identifier for the Voice Broadcast used on the web site's account management page. (Valid values contain alphanumeric characters and spaces; default is "My SurVo Broadcast"; maximum length is 32 characters.)

Example URL

https://secure.ifbyphone.com/ibp_api.php
?action=clickto.survo
&scheduleonly
&survo_id=890
&access_key=ACCESS_KEY
&secret_access_key=SECRET_ACCESS_KEY
&type=1
&sdate=2024-04-18+11%3A38
&edate=2024-04-19+12%3A03
&tz=Central
&phone=7735551212%7C8475551212
&dstime=00%3A00
&detime=23%3A59

Notes

Calls are limited to be between the hours of 00:00 (midnight) and 23:59 (almost midnight), i.e., all day long.

To use a URL with a list of numbers, use (for example)

&phone=http%3A%2F%2Fwww.example.com%2Ffiles%2Fnumberstocall.csv

In this example, the Smart Form will retrieve the CSV file from "http://www.example.com/files/numberstocall.csv" and schedule calls to the numbers given in the file.

If the value of phone is a CSV file, the file must end with ".csv." In addition, the CSV file must have at least one column with the heading "number".

For example, a CSV file can contain one column of names and another of telephone numbers:

"name","number"

"John Q. Public",7735551212

"Mary Public",8475551212

Server Side Response (XML) from Scheduling Request

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

SurVo User Parameter Substitution Example 1

Example URL 1 with User Parameter Substitution

https://secure.ifbyphone.com/ibp_api.php
?action=clickto.survo
&phone_to_call=8475551212
&survo_id=890
&access_key=ACCESS_KEY
&secret_access_key=SECRET_ACCESS_KEY
&user_parameters=name|John Doe||date|May 3rd, 2024

You can include as many key|value pairs as you need for each of your SurVo questions.

Survo User Parameter Substitution Example 2

Here is another example that not only changes the question text dynamically for a monitored call but also the max duration and the number to transfer to as well