sendSms¶
Request Method: POST
Description: Send an SMS
URL: https://api.iovox.com:444/SMS?v=3&method=sendSms
The following parameters can be sent in the querystring
| Parameter | Description | Default Value | Data Type | Mandatory |
| v | API version to use | INTEGER | YES |
Payload¶
The following XML payload must be sent with a sendSms request:
<?xml version="1.0" encoding="utf-8"?>
<request>
<origin>447923221231</origin>
<destination>447723443321</destination>
<message>Hello there, my name is John</message>
</request>
An example with delivery receipt call back URL and headers:
<?xml version="1.0" encoding="utf-8"?>
<request>
<origin>447923221231</origin>
<destination>447723443321</destination>
<message>Hello there, my name is John</message>
<callback_url>https://my.dlr.callback.iovox.com/dlr</callback_url>
<callback_url_headers>Content-Type: application/json,X-Custom-Header: iovox</callback_url_headers>
</request>
An example using expiry after 3 minutes in combination with a text to speech failover:
<?xml version="1.0" encoding="utf-8"?>
<request>
<origin>447923221231</origin>
<destination>447723443321</destination>
<message>Hello there, my name is John</message>
<expiry>3</expiry>
<c2c_failover_link_id>123456</c2c_failover_link_id>
</request>
Payload Description¶
The following parameters can be sent in the querystring
| Node Name | Description | Default Value | Data Type | Mandatory |
| origin | The sender name can be a maximum of 11 characters long. Composed of an E.164 formatted phone number, excluding the leading + or 00, or a combination of alphanumeric characters that includes spaces and full stops but no special characters. | STRING | YES | |
| destination | Destination phone number | STRING | YES | |
| message | Message with the SMS text | STRING | YES | |
| callback_url | URL we will send the delivery receipts to. | STRING | NO | |
| callback_url_headers | Additional headers we will be sending with the delivery receipt call back. If multiple headers need to be included, please separate them by ",". | STRING | NO | |
| expiry | The expiry time of the message in minutes. If the SMS is not delivered by this time, then the message will be marked as EXPIRED. Please note that the SMS may still be delivered by the operator after expiry. | INT | NO | |
| c2c_failover_link_id | A link ID to use to convert the SMS into a call where the content will be read out using text to speech. This parameter will be used when the SMS fails to be delivered (FAILED/EXPIRED). Example call flow to be used with text to speech failover: <callFlow name="SMS READ OUT">
<play id="sms_read_out" label="SMS READ OUT">
<textToSpeech textToSpeak="You have received an SMS from" voice="tts_uk_eng_male" />
<textToSpeech textToSpeak="$sms_origin" voice="tts_uk_eng_male" />
<textToSpeech textToSpeak="$content" voice="tts_uk_eng_male" />
</play>
</callFlow> | STRING | NO |
Result¶
Error Result¶
| HTTP Code | Error String | Resolution |
| 400 | API Version Empty | Add a value for the v parameter in the query string |
| 400 | API Version Invalid | Correct v parameter |
| 400 | Request Method must be POST. x attempted | Switch request method x to POST |
| 400 | XML Empty | Add xml to the request body |
| 400 | XML parse error. x at line y, column z | Correct XML at point x on line y, column z |
| 400 | Request Empty | Add at least one node to the request |
| 400 | Origin Empty | Add a valid origin |
| 400 | Origin Invalid: x | Correct origin |
| 400 | Destination Empty | Add a valid destination |
| 400 | Destination Invalid: x | Correct destination |
| 400 | Message Empty | Correct message |
| 400 | Message must be less than 160 characters long | Correct message |
| 500 | Internal Server Error | Retry later |
Success Result¶
HTTP/1.1 201 Created
<?xml version="1.0" encoding="UTF-8"?>
<response>
<sms_activity_id>d454cfe0-a835-11e6-9852-d43d7ed6ce4c</sms_activity_id>
</response>
Delivery Receipts¶
We can send a JSON string to a URL via HTTP POST. The JSON string contains the delivery receipt with an identifier for the message that was sent.
Example payloads:
{
"sms_activity_id": "d454cfe0-a835-11e6-9852-d43d7ed6ce4c",
"delivery_status": "smsc submit",
"status_reason": "8",
"receipt_timestamp": "2020-05-06 18:37:37",
"status": "ACKNOWLEDGED"
}
{
"sms_activity_id": "d454cfe0-a835-11e6-9852-d43d7ed6ce4c",
"delivery_status": "delivery success",
"status_reason": "1",
"receipt_timestamp": "2020-05-06 18:37:46",
"status": "DELIVERED"
}
Delivery Receipts JSON Description¶
| Name | Description | Data Type |
|---|---|---|
| sms_activity_id | The Identifier of the SMS that was sent. | STRING |
| delivery_status | Textual representation of the raw delivery receipt. | STRING |
| status_reason | Numeric representation of the raw delivery receipt. | STRING |
| receipt_timestamp | The timestamp in Europe/London time of the delivery receipt. | STRING |
| status | The status of the SMS. Possible values are ACKNOWLEDGED, DELIVERED, FAILED, BUFFERED. ACKNOWLEDGED: The SMS center has accepted the message and will try delivery as soon as possible. DELIVERED: The SMS center has delivered the message to the destination. FAILED: The SMS center failed to deliver the message. BUFFERED: The SMS center has buffered the message and will re-try delivery at a later time. | STRING |