Download OpenAPI specification:Download

Webhooks

Callbacks

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.

  • Callback with mutual authentication over TLS (HTTPS) connection by provisioning the callback URL with client keystore and password.
  • Callback with basic authentication by provisioning the callback URL with username and password.
  • Callback with OAuth 2.0 by provisioning the callback URL with username, password and the URL to fetch OAuth access token.
  • Callback using AWS SNS by provisioning the callback URL with an Access Key ID, Secret Key and Region.

Incoming SMSWebhook

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.

Request
Request Body schema: application/json

The incoming Message to your sinch number

type
string

The object type. Either mo_text or mo_binary.

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

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: YYYY-MM-DDThh:mm:ss.SSSZ

received_at
string <date-time>

When the system received the message.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ

Responses
200

A 200 status indicates that the data was received successfully.

Request samples
application/json
{
  • "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"
}

Delivery ReportWebhook

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 you need to set the delivery_report field accordingly when creating a batch.

The callback URL can either be provided for each batch or provisioned globally for your account in your Dashboard.

Request
Request Body schema: application/json
type
string
Default: "delivery_report_sms"

The object type. Will always be delivery_report_sms.

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.

Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "delivery_report_sms",
  • "batch_id": "01FC66621VHDBN119Z8PMV1QPQ",
  • "total_message_count": "20000",
  • "statuses": [
    • {
      },
    • {
      }
    ]
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2022 Sinch. All rights reserved.