Send SMS

The transactional SMS operation consists of sending an SMS to one or more recipients who do not belong to the organization’s audience. As such, it does not depend on a schema previously defined for the audience of contacts.

This operation allows for the configuration of webhooks – webhooks are endpoints configured by the client in each transactional SMS send, which will be invoked by Arpoone to forward event information related to the delivery status of the message.

There is a limit of 10 SMS per HTTP request to the Arpoone API, configurable in the messages field.

Special attention must be given to the fact that the To field (destination phone number) in the transactional SMS payload has to be a valid MSISDN with the country prefix included - for instance, if the MSISDN is portuguese, it must start with 351 (E.g.: 351913462111).

Senders

The SMS sender can be numeric or alphanumeric and is configured on the From field of the transactional SMS payload.

The execution of transactional SMS sending requires prior configuration of the sender used in the request. This configuration is done on the Arpoone platform.

This configuration involves the following steps:

• Create the sender on the Arpoone platform:
  • Accessed via: Profile Picture → Settings → Senders → SMS Senders;
• Configure the sender text (which can be numeric or alphanumeric) and attach a file proving the legitimacy of the usage for the requested sender;
• Wait for approval from the Arpoone team. A notification email will be sent once the request is accepted.

Payload

Example of an SMS send payload, with webhooks:

{
  "organizationId": <uuidv4> (Guid),
  "messages":
    [
        {
            "text": <string>,
            "to": <string> - MSISDN with country prefix,
            "from": <string> - sender,
            "expirationDateTime": <datetime>,
            "smsWebhooks": {
                "delivered": {
                    "url": <string>,
                    "enabled": <bool>
                },
                "not_delivered": {
                    "url": <string>,
                    "enabled": <bool>
                },
                "pending": {
                    "url": <string>,
                    "enabled": <bool>
                },
		"customPayload": <string>
            }
        },
        ...
    ]
}

Configuration

The messages property in the payload is an array, which means you can send multiple SMS messages in a single HTTP request.

Description of fields:

• to – recipient of the SMS;
• text – content of the message;
• from – the name of the sender to be used in the send, which must be pre-configured via the Arpoone platform;
• expirationDateTime – expiration date and time in UTC timezone when the SMS is sent. If there is any delay in sending SMS by the platform, and the current date exceeds the configured value in this field, the SMS will not be sent;
• smsWebhooks – destination URLs for notifications of SMS delivery status changes (see SMS Webhooks page). Specifying these URLs is optional. It is also possible to set the customPayload property, which will be forwarded back in the notifications for the given message (maximum size of 1KB).

Response

Similarly to the request body of the transactional SMS endpoint, the response also contains an array messages. There is a matching index between each item in the array of the request and the array of the response, where each object contains the result of the scheduling.

The transactional SMS endpoint returns Status Code 200 (HTTP OK) if no error prevents the processing of the request. The success/error indication for each message is made in the response body, within each item in the messages array, under the status property.

For each item, the scheduling status will be indicated in the status property (which reflects whether the SMS was sent successfully or not), the SMS identifier (messageId), the segment count of the SMS (segmentCount), the cost of sending it (cost, deducted from the organization’s balance), along with the recipient's country code and error description (error, if any).

Example:

{
    "error": null,
    "messages": [
        {
            "status": "SUCCESS",
            "messageId": "3f22f963-155b-4853-b8fb-0d1944345321",
            "segmentCount": 1,
            "encoding": 0,
            "cost": {
                "amount": 1,
                "countryCode": "PT"
            },
            "error": null
        },
        ...
    ]
}

Errors

In case of errors, the error property within each item of the messages array (in the response) will be populated with an object containing information about the error that occurred:

"error":
{
    "code": "PARAM_EXCEEDS_MAX_LENGTH",
    "param": "DisplayName",
    "description": ""
}

The code property specifies the type of error that occurred, while the param property specifies which parameter in the SMS send payload caused the error.

The complete list of error codes can be found here.

Access the API Reference