Voice Messaging

Messaging

Voice Messaging

Everything about sending and viewing responses to voice messages

Download OpenAPI description

voice-messaging.json

voice-messaging.yaml

Servers

https://rest.clicksend.com/

Send Voice Message

Request

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

Security

basicAuth

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

messagesArray of objects

Example: [{"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}]

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \
     --header "Content-Type: application/json" \

     --data-binary "    {
        \"messages\":[
            {
                \"source\":\"php\",
                \"body\":\"Jelly liquorice marshmallow candy carrot cake 4Eyffjs1vL.\",
                \"to\":\"+61411111111\",
                \"lang\":\"en-au\",
                \"voice\":\"female\",
                \"schedule\":1436874701,
                \"custom_string\":\"this is a test\",
                \"require_input\": 1,
                \"machine_detection\": 1
            },
            {
                \"source\":\"php\",
                \"body\":\"Chocolate bar icing icing oat cake carrot cake jelly cotton MWEvciEPIr.\",
                \"to\":\"+61422222222\",
                \"lang\":\"en-au\",
                \"voice\":\"female\",
                \"schedule\":1436876011,
                \"custom_string\":\"this is a test\"
            }
        ]
    }" \
'https://rest.clicksend.com/v3/voice/send'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

Here are your data.

dataobject

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "string",
  "data": {
    "total_price": 0.07,
    "total_count": 1,
    "queued_count": 1,
    "messages": [ … ],
    "_currency": { … }
  }
}

Calculate Voice Price

Request

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

Security

basicAuth

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

messagesArray of objects

Example: [{"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}]

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \
     --header "Content-Type: application/json" \

     --data-binary "    {
        \"messages\":[
            {
                \"source\":\"php\",
                \"body\":\"Jelly liquorice marshmallow candy carrot cake 4Eyffjs1vL.\",
                \"to\":\"+61411111111\",
                \"lang\":\"en-au\",
                \"voice\":\"female\",
                \"schedule\":1436874701,
                \"custom_string\":\"this is a test\"
            },
            {
                \"source\":\"php\",
                \"body\":\"Chocolate bar icing icing oat cake carrot cake jelly cotton MWEvciEPIr.\",
                \"to\":\"+61422222222\",
                \"lang\":\"en-au\",
                \"voice\":\"female\",
                \"schedule\":1436876011,
                \"custom_string\":\"this is a test\",
                \"require_input\":1
            }
        ]
    }" \
'https://rest.clicksend.com/v3/voice/price'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

Here are your data.

dataobject

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "string",
  "data": {
    "total_price": 0.07,
    "total_count": 1,
    "queued_count": 1,
    "messages": [ … ],
    "_currency": { … }
  }
}

View Voice Languages

Request

Get all voice languages

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

This endpoint requires authentication,more info...

Security

basicAuth

Headers

Content-Typestring

Example: application/json

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

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

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here are the possible languages."

dataArray of objects

Example: [{"code":"en-us","country":"English, US","gender":["male","female"]},{"code":"en-au","country":"English, Australia","gender":["male","female"]}]

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are the possible languages.",
  "data": [
    { … },
    { … }
  ]
}

View Voice Receipts

Request

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

Security

basicAuth

Headers

Content-Typestring

Example: application/json

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

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

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here are your delivery receipts."

dataobject

Response

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": [ … ]
  }
}

Cancel Voice Message

Request

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

Security

basicAuth

Path

message_idstringrequired

Headers

Content-Typestring

Example: application/x-www-form-urlencoded

Bodyapplication/json

object

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

'https://rest.clicksend.com/v3/voice/{message_id}/cancel'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Voice have been cancelled."

dataArray of items

Example: []

Response

application/json

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

Cancel All Voice Messages

Request

Update all voice messages as cancelled

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

This endpoint requires authentication,more info...

Security

basicAuth

Headers

Content-Typestring

Example: application/x-www-form-urlencoded

Bodyapplication/json

object

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

'https://rest.clicksend.com/v3/voice/cancel-all'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "5 messages have been cancelled."

dataobject

Response

application/json

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

Get Voice History

Request

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

Security

basicAuth

Query

date_tostring

limitinteger

Example: limit=20

operatorstring

Example: operator=AND

order_bystring

Example: order_by=date_added:desc

pageinteger

Example: page=1

Headers

Content-Typestring

Example: application/json

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

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

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here is your history."

dataobject

Response

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": [ … ]
  }
}

Export Voice History

Request

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

Security

basicAuth

Query

filenamestring

Example: filename=Voice_history.csv

qstring

order_bystring

Example: order_by=date_added:desc

date_fromstring

date_tostring

limitinteger

Example: limit=50000

Headers

Content-Typestring

Example: application/json

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

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

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Download your file here."

dataobject

Response

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

Voice Messaging

Send Voice Message

RequestExpand all

How many messages can I send?

How many characters can I send in a message?

Standard English Characters:

Non-GSM (Unicode) characters:

Allowed Languages

Properties

Responses

Was this helpful?

Calculate Voice Price

RequestExpand all

Properties

Responses

Was this helpful?

View Voice Languages

Request

Responses

Was this helpful?

View Voice Receipts

Request

Parameters

Responses

Was this helpful?

Cancel Voice Message

Request

Parameters

Responses

Was this helpful?

Cancel All Voice Messages

Request

Responses

Was this helpful?

Get Voice History

Request

Parameters

Responses

Was this helpful?

Export Voice History

Request

Parameters

Responses

Was this helpful?

Request

Request