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

ParameterDescriptionDefault ValueData TypeMandatory
vAPI version to use
INTEGERYES

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 NameDescriptionDefault ValueData TypeMandatory
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.


STRINGYES
destinationDestination phone number
STRINGYES
 messageMessage with the SMS text
STRINGYES
callback_urlURL we will send the delivery receipts to.
STRINGNO
callback_url_headersAdditional headers we will be sending with the delivery receipt call back. If multiple headers need to be included, please separate them by ",".
STRINGNO
expiryThe 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.
INTNO
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>

STRINGNO

Result

Error Result

HTTP CodeError StringResolution
400API Version EmptyAdd a value for the v parameter in the query string
400API Version InvalidCorrect v parameter
400Request Method must be POST. x attemptedSwitch request method x to POST
400XML EmptyAdd xml to the request body
400XML parse error. x at line y, column zCorrect XML at point x on line y, column z
400Request EmptyAdd at least one node to the request
400Origin EmptyAdd a valid origin
400Origin Invalid: xCorrect origin
400Destination EmptyAdd a valid destination
400Destination Invalid: xCorrect destination
400Message EmptyCorrect message
400Message must be less than 160 characters longCorrect message
500Internal Server ErrorRetry 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

NameDescriptionData Type
sms_activity_idThe Identifier of the SMS that was sent.STRING
delivery_status

Textual representation of the raw delivery receipt.

STRING
status_reasonNumeric representation of the raw delivery receipt.STRING
receipt_timestampThe 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