Voice Messaging (1.0.0)

Everything about sending and viewing responses to voice messages

Send Voice Message

Send voice message(s)

Send TTS (Text-to-speech) voice calls

How many messages can I send?

You can post up to 1000 messages with each API call. You can send to a mix of contacts and contact lists, as long as the total number of recipients is up to 1000. The response contains a status and details for each recipient.

How many characters can I send in a message?

If a message is longer than 4 message parts, it will be truncated (see below). If a message contains any characters that aren't in the GSM 03.38 character set, the message type will be treated as unicode. (https://en.wikipedia.org/wiki/GSM_03.38)

Standard English Characters:

Number of Characters	Message Credits
1 - 300	1
301 - 600	2
601 - 900	3
901 - 1200	4

Non-GSM (Unicode) characters:

Number of Characters	Message Credits
1 - 150	1
151 - 300	2
301 - 450	3
451 - 600	4

Allowed Languages

Language, Locale	lang	voice
`English`, US	en-us	female (default) / male
`English`, Australia	en-au	female (default) / male
`English`, UK	en-gb	female (default) / male
`English`, India	en-in	female
`English`, Wales	en-gb-wls	female (default) / male
`Celtic`, Wales	cy-gb-wls	female (default) / male
`German`, Germany	de-de	female (default) / male
`Spanish`, Spain	es-es	female (default) / male
`Spanish`, US	es-us	female (default) / male
`French`, Canada	fr-ca	female
`French`, France	fr-fr	female (default) / male
`Icelandic`, Iceland	is-is	female (default) / male
`Italian`, Italy	it-it	female (default) / male
`Danish`, Denmark	da-dk	female (default) / male
`Dutch`, Netherlands	nl-nl	female (default) / male
`Norwegian`, Norway	nb-no	female
`Polish`, Poland	pl-pl	female (default) / male
`Portuguese`, Portugal	pt-pt	male
`Portuguese`, Brazil	pt-br	female (default) / male
`Romanian`, Romania	ro-ro	female
`Russian`, Russia	ru-ru	female (default) / male
`Swedish`, Sweden	sv-se	female
`Turkish`, Turkey	tr-tr	female

Tips

To introduce a small delay between words or digits you can use a comma (,).

For example: Please enter your activation code 9, 0, 9, 0, in the next 20 minutes.

We support some SSML tags allowing custom breaks or pauses to be entered, and the readout rate to be altered.

More info...

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	Your phone number in E.164 format.
body	string	true	none	Biscuit uv3nlCOjRk croissant chocolate lollipop chocolate muffin.
voice	string	true	none	Either 'female' or 'male'.
custom_string	string	true	none	Your reference. Will be passed back with all replies and delivery reports.
country	string	true	none	The country of the recipient.
source	string	false	none	Your method of sending e.g. 'wordpress', 'php', 'c#'.
list_id	integer(int32)	false	none	Your list ID if sending to a whole list. Can be used instead of 'to'.
lang	string	false	none	au (string, required) - See section on available languages.
schedule	integer(int32)	false	none	Leave blank for immediate delivery. Your schedule time in unix format http://help.clicksend.com/what-is-a-unix-timestamp
require_input	integer(int1)	false	none	Recieve a keypress from the recipient. Flag value must be 1 for yes or 0 for no.
machine_detection	integer(int1)	false	none	Detect answering machine or voicemail and leave a message. Flag value must be 1 for yes or 0 for no.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

post/v3/voice/send

Request samples

application/json

{"messages": [{"source": "postman",
"body": "Your verification code is. 1. 2. 3. 4. 5. Again that's. 1, 2, 3, 4, 5.",
"to": "+61411111111",
"voice": "male",
"lang": "en-au",
"machine_detection": 1
}
]
}

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "string",
"data": {"total_price": 0.07,
"total_count": 1,
"queued_count": 1,
"messages": [{"date": 1436871253,
"to": "+61411111111",
"to_type": "mobile",
"body": "Jelly liquorice marshmallow candy carrot cake 4Eyffjs1vL.",
"from": null,
"lang": "en-au",
"voice": "female",
"schedule": 1436874701,
"message_id": "BF7AD270-0DE2-418B-B606-71D527D9C1AE",
"message_parts": 1,
"message_price": 0.07,
"custom_string": "this is a test",
"user_id": 1,
"subaccount_id": 1,
"country": "AU",
"require_input": 0,
"machine_detection": 0,
"status": "SUCCESS"
}
],
"_currency": {"currency_name_short": "AUD",
"currency_prefix_d": "$",
"currency_prefix_c": "c",
"currency_name_long": "Australian Dollars"
}
}
}

Calculate Voice Price

Calculate voice price

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	Your phone number in E.164 format.
body	string	true	none	Biscuit uv3nlCOjRk croissant chocolate lollipop chocolate muffin.
voice	string	true	none	Either 'female' or 'male'.
custom_string	string	true	none	Your reference. Will be passed back with all replies and delivery reports.
country	string	true	none	The country of the recipient.
source	string	false	none	Your method of sending e.g. 'wordpress', 'php', 'c#'.
list_id	integer(int32)	false	none	Your list ID if sending to a whole list. Can be used instead of 'to'.
lang	string	false	none	au (string, required) - See section on available languages.
schedule	integer(int32)	false	none	Leave blank for immediate delivery. Your schedule time in unix format http://help.clicksend.com/what-is-a-unix-timestamp
require_input	integer(int1)	false	none	Recieve a keypress from the recipient. Flag value must be 1 for yes or 0 for no.
machine_detection	integer(int1)	false	none	Detect answering machine or voicemail and leave a message. Flag value must be 1 for yes or 0 for no.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

post/v3/voice/price

Request samples

application/json

{"messages": [{"source": "php",
"from": "1234",
"body": "Hi, this is a test.",
"to": "+61411111111",
"voice": "female",
"lang": "en-au",
"schedule": "1529086126",
"custom_string": "this is a test",
"asdasd": "asdadasd",
"machine_detection": 1
}
]
}

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "string",
"data": {"total_price": 0.07,
"total_count": 1,
"queued_count": 1,
"messages": [{"date": 1436871253,
"to": "+61411111111",
"to_type": "mobile",
"body": "Jelly liquorice marshmallow candy carrot cake 4Eyffjs1vL.",
"from": null,
"lang": "en-au",
"voice": "female",
"schedule": 1436874701,
"message_id": "BF7AD270-0DE2-418B-B606-71D527D9C1AE",
"message_parts": 1,
"message_price": 0.07,
"custom_string": "this is a test",
"user_id": 1,
"subaccount_id": 1,
"country": "AU",
"require_input": 0,
"machine_detection": 0,
"status": "SUCCESS"
}
],
"_currency": {"currency_name_short": "AUD",
"currency_prefix_d": "$",
"currency_prefix_c": "c",
"currency_name_long": "Australian Dollars"
}
}
}

View Voice Languages

Get all voice languages

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/voice/lang

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/voice/lang'

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Here are the possible languages.",
"data": [{"code": "en-us",
"country": "English, US",
"gender": ["male",
"female"
]
},
{"code": "en-au",
"country": "English, Australia",
"gender": ["male",
"female"
]
}
]
}

View Voice Receipts

Get all voice receipts

Push Delivery Receipts

If you prefer, we can push message replies to your server as they arrive with us.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on Voice then Delivery Report Rules.
Click the 'Add New Rule' button.
Select the 'URL' action.
Enter the URL and click 'Save'.

The following variables will be posted to the URL specified:

Variable	Description
`timestamp_send`	Timestamp of the original send request in UNIX format. e.g 1439173980
`timestamp`	Timestamp of delivery report in UNIX format. e.g 1439173981
`message_id`	Message ID, returned when originally sending the message.
`status`	Delivered or Undelivered
`status_code`	Status code. Refer to 'Voice Delivery Status Codes' in docs.
`status_text`	Status text.
`error_code`	Error code.
`error_text`	Error text.
`custom_string`	A custom string used when sending the original message.
`user_id`	The user ID of the user who sent the message.
`subaccount_id`	The subaccount ID of the user who sent the message.
`message_type`	'voice' (constant).
`digits`	Numbers the recipient pressed on their keypad during the call. A blank string will be used if they didn't provide any input.

Pull Delivery Receipts

Receive delivery reports by polling. You can poll our server and retrieve delivery reports at a time that suits you.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on Voice then Delivery Report Rules.
Click the 'Add New Rule' button.
Select the 'Poll' action.
Then click 'Save'.

Parameters

Parameter	In	Type	Required	Description
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/voice/receipts

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/voice/receipts'

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Here are your delivery receipts.",
"data": {"total": 2,
"per_page": 15,
"current_page": 1,
"last_page": 1,
"next_page_url": null,
"prev_page_url": null,
"from": 1,
"to": 2,
"data": [{"timestamp_send": "1442381791",
"timestamp": "1442381791",
"message_id": "31BC271B-1E0C-45F6-9E7E-97186C46BB82",
"status_code": "201",
"status_text": "Success: Message received on handset.",
"error_code": null,
"error_text": null,
"custom_string": null,
"message_type": "voice",
"digits": 2
},
{"timestamp_send": "1442381829",
"timestamp": "1442381829",
"message_id": "23C8ADA3-FD8B-420B-801A-F829BB87AC6F",
"status_code": "201",
"status_text": "Success: Message received on handset.",
"error_code": null,
"error_text": null,
"custom_string": null,
"message_type": "voice",
"digits": 5
}
]
}
}

Cancel Voice Message

Update voice message status as cancelled

Parameters

Parameter	In	Type	Required	Description
message_id	path	string	true	Your voice message id

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

message_id

required

string

header Parameters

Content-Type

string

Example: application/x-www-form-urlencoded

Request Body schema: application/json

object

Responses

200

Successful response

put/v3/voice/{message_id}/cancel

Request samples

application/json

""

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Voice have been cancelled.",
"data": [ ]
}

Cancel All Voice Messages

Update all voice messages as cancelled

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

header Parameters

Content-Type

string

Example: application/x-www-form-urlencoded

Request Body schema: application/json

object

Responses

200

Successful response

put/v3/voice/cancel-all

Request samples

application/json

""

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "5 messages have been cancelled.",
"data": {"count": 5
}
}

Get Voice History

Get all voice history

Parameters

Parameter	In	Type	Required	Description
date_from	query	integer(int32)	false	Start date (Unix Timestamp e.g. 1436849372)
date_to	query	integer(int32)	false	End date (Unix Timestamp e.g. 1436879372)
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

query Parameters

date_to	string
limit	integer Example: limit=20
operator	string Example: operator=AND
order_by	string Example: order_by=date_added:desc
page	integer Example: page=1

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/voice/history

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/voice/history?date_from=&date_to='

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Here is your history.",
"data": {"total": 2,
"per_page": 15,
"current_page": 1,
"last_page": 1,
"next_page_url": null,
"prev_page_url": null,
"from": 1,
"to": 2,
"data": [{"date": 1436871253,
"to": "+61411111111",
"to_type": "mobile",
"body": "Jelly liquorice marshmallow candy carrot cake 4Eyffjs1vL.",
"from": null,
"lang": "en-au",
"voice": "female",
"schedule": 1436874701,
"message_id": "BF7AD270-0DE2-418B-B606-71D527D9C1AE",
"message_parts": 1,
"message_price": 0.07,
"custom_string": "this is a test",
"user_id": 1,
"subaccount_id": 1,
"country": "AU",
"require_input": 0,
"machine_detection": 0,
"status": "SUCCESS"
}
]
}
}

Export Voice History

Export voice history

Parameters

Parameter	In	Type	Required	Description
filename	query	string	true	Filename to export to

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

query Parameters

filename	string Example: filename=Voice_history.csv
q	string
order_by	string Example: order_by=date_added:desc
date_from	string
date_to	string
limit	integer Example: limit=50000

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/voice/history/export

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/voice/history/export?filename={filename}'

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Download your file here.",
"data": {"url": "https://rest.clicksend.com/files/22D55AF9-6CF0-476D-A8B3-82A998FD2738?filename=export.csv"
}
}