A callback is an HTTP POST request with a notification made by the Sinch SMS REST API to a URI of your choosing.
The REST API expects the receiving server to respond with a response code within the 2xx
Success range. If no successful response is received, the REST API will either schedule a retry, if the error is expected to be temporary, or discard the callback, if the error seems permanent. The first initial retry will happen 5 seconds after the first try. The next attempt is after 10 seconds, then after 20 seconds, after 40 seconds, after 80 seconds, doubling on every attempt. The last retry will be at 81920 seconds (or 22 hours 45 minutes) after the initial failed attempt.
The SMS REST API offers the following callback options which can be configured for your account upon request to your account manager.
An inbound message is a message sent to one of your short codes or long numbers from a mobile phone.
To receive inbound message callbacks, a URL needs to be added to your REST API. This URL can be specified in your Dashboard.
The incoming message to your sinch number
type | string The object type. Either |
id | string The ID of this inbound message. |
from | string The phone number that sent the message. |
to | string The Sinch phone number or short code to which the message was sent. |
body | string The message body. Base64 encoded if type is |
client_reference | string If this inbound message is in response to a previously sent message that contained a client reference, then this field contains that client reference. Utilizing this feature requires additional setup on your account. Contact your account manager to enable this feature. |
operator_id | string The MCC/MNC of the sender's operator if known. |
send_at | string <date-time> When the message left the originating device. Only available if provided by operator. Formatted as ISO-8601: |
received_at | string <date-time> When the system received the message. Formatted as ISO-8601: |
A 200 status indicates that the data was received successfully.
{- "type": "mo_text",
- "id": "01XXXXX21XXXXX119Z8P1XXXXX",
- "from": "16051234567",
- "to": "13185551234",
- "body": "This is a test message.",
- "operator_id": "string",
- "send_at": "2022-08-24T14:15:22Z",
- "received_at": "2022-08-24T14:15:22Z"
}
A delivery report contains the status and status code for each recipient of a batch. To get a delivery report callback for a message or batch of messages, set the delivery_report
field accordingly when creating a batch.
The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch.
The callback URL can either be provided for each batch or provisioned globally for your account in your Sinch Customer Dashboard. Learn how to configure a webhook/callback here.
The type
is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of" in the response.
recipient_delivery_report_sms
is a delivery report for a recipient phone number. If you set per_recipient
for the delivery_report
parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch.delivery_report_sms
is a delivery report containing either a full report or summary report depending on your selection at the time the batch was sent.Return a 200 status to indicate that the data was received successfully. Or an error.
Choose the appropriate delivery report webhook type below.
If you set your delivery_report
to per_recipient
when sending the batch, you choose to receive recipient delivery reports.
type | string Default: "delivery_report_sms" The type of webhook for the delivery report. Returns a either a |
batch_id | string The ID of the batch this delivery report belongs to. |
total_message_count | string The total number of messages for the batch |
Array of objects Array with status objects. Only status codes with at least one recipient will be listed. | |
client_reference | string The client identifier of the batch this delivery report belongs to, if set when submitting batch. |
{- "batch_id": "string",
- "client_reference": "string"
}
{- "type": "delivery_report_sms",
- "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
- "total_message_count": "1000",
- "statuses": [
- {
- "code": "0",
- "status": "Queued",
- "count": 0,
- "recipients": [
- "+44231235674"
]
}
]
}