Batches

Batches are sets of SMS messages. You can send a single message or many. Batches are queued and sent at the rate limit in First-In-First-Out order.

If you want more in-depth knowledge about SMS in general please read the API Overview.

Send

Sends a message or a batch of messages. Depending on the length of the body one message might be split into multiple parts and charged accordingly. Any groups targeted in a scheduled batch will be evaluated at the time of sending. If a group is deleted between batch creation and scheduled date it will be considered empty.

Authorizations:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll
Request Body schema: application/json
to
required
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items
Default: ["+15551231234","+15551256344"]

List of Phone numbers and group IDs that will receive the batch. Constraints: 1 to 1000 elements More info

body
required
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text

Enum: "mt_text" "mt_binary"
udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Must be after send_at. 3 days after send_at.

callback_url
string <uri> <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary 'example : "parameters: [{"name": { "123456789": "Joe", "default": "there"}]' Click here to learn more about parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

Responses

Response Schema: application/json
to
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info Constraints: 1 to 1000 elements

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text is regular SMS, mt_binary is a binary format.

Enum: "mt_text" "mt_binary"
body
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Must be after send_at. 3 days after send_at.

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary

Click here to learn more about parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

id
string

Unique identifier for batch

created_at
string <date-time>

Timestamp for when batch was created.

ISO-8601 format

modified_at
string <date-time>

Timestamp for when batch was last updated.

ISO-8601 format

canceled
boolean

Indicates if the batch has been canceled or not.

Request samples

Content type
application/json
{
  • "from": "12345",
  • "to": [
    • "+15551231212"
    ],
  • "body": "Hello how are you"
}

Response samples

Content type
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "from": "+15551231234",
  • "type": "mt_text",
  • "body": "This is a message to be sent!",
  • "udh": "string",
  • "delivery_report": "none",
  • "send_at": "2019-08-24T14:15:22Z",
  • "expire_at": "3 days after send_at",
  • "callback_url": "string",
  • "flash_message": false,
  • "parameters": {
    • "{parameter_key}": "string",
    • "{parameter_key}.{msisdn}": "string",
    • "{parameter_key}.default": "string"
    },
  • "client_reference": "string",
  • "max_number_of_message_parts": 1,
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "canceled": true
}

List Batches

With the list operation you can list batch messages created in the last 14 days that you have created. This operation supports pagination.

Authorizations:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll
query Parameters
page
integer

The page number starting from 0.

Example: page=4
page_size
integer <= 100
Default: 30

Determines the size of a page. Default: 30 Constraints: max 100

Example: page_size=50
to
string

Only list messages sent to this destination. Multiple phone numbers formatted as e164 can be comma separated. For more info

Example: to=+43243534234, +32434234456
start_date
string

Only list messages received at or after this date time formatted as ISO-8601

Default: Now-24

end_date
string

Only list messages received before this date time formatted as ISO-8601

Responses

Response Schema: application/json
page
integer

The requested page.

count
integer

The total number of batches matching the given filters.

page_size
integer

The number of batches returned in this request

Array of objects (sendBatchObject)

The page of batches matching the given filters

Request samples

const fetch = require('node-fetch');

const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
const resp = await fetch(
  `https://us.sms.api.sinch.com/xms/v1/${servicePlanId}/batches`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    }
  }
);

const data = await resp.text();
console.log(data);

Response samples

Content type
application/json
{
  • "page": 1,
  • "count": 2000,
  • "page_size": 50,
  • "batches": [
    • {
      • "to": [
        • "+15551231234",
        • "+15551256344"
        ],
      • "from": "+15551231234",
      • "type": "mt_text",
      • "body": "This is a message to be sent!",
      • "udh": "string",
      • "delivery_report": "summary",
      • "send_at": "2019-08-24T14:15:22Z",
      • "expire_at": "3 days after send_at",
      • "flash_message": false,
      • "parameters": {
        • "{parameter_key}": {
          • "{msisdn}": "{\"15551231212\":\"Joe\"}",
          • "default": "{\"default\":\"Customer\"}"
          }
        },
      • "client_reference": "string",
      • "max_number_of_message_parts": 1
      }
    ]
}

Dry run

This operation will perform a dry run of a batch which calculates the bodies and number of parts for all messages in the batch without actually sending any messages.

Authorizations:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll
query Parameters
per_recipient
boolean

Whether to include per recipient details in the response

Example: per_recipient=true
number_of_recipients
integer <= 1000
Default: 100

Max number of recipients to include per recipient details for in the response

Example: number_of_recipients=500
Request Body schema: application/json
to
required
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items
Default: ["+15551231234","+15551256344"]

List of Phone numbers and group IDs that will receive the batch. Constraints: 1 to 1000 elements More info

body
required
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text

Enum: "mt_text" "mt_binary"
udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Must be after send_at. 3 days after send_at.

callback_url
string <uri> <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary 'example : "parameters: [{"name": { "123456789": "Joe", "default": "there"}]' Click here to learn more about parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

Responses

Response Schema: application/json
number_of_recipients
integer

The number of recipients in the batch

number_of_messages
integer

The total number of SMS message parts to be sent in the batch

Array of objects

The recipient, the number of message parts to this recipient, the body of the message, and the encoding type of each message

Request samples

Content type
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "body": "This is a message to be sent!"
}

Response samples

Content type
application/json
{
  • "number_of_recipients": 0,
  • "number_of_messages": 0,
  • "per_recipient": [
    • {
      • "recipient": "string",
      • "message_part": "string",
      • "body": "string",
      • "encoding": "string"
      }
    ]
}

Get a batch message

This operation returns a specific batch that matches the provided batch ID.

Authorizations:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 4HJY56S2r4t6c

Responses

Response Schema: application/json
to
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info Constraints: 1 to 1000 elements

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text is regular SMS, mt_binary is a binary format.

Enum: "mt_text" "mt_binary"
body
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Must be after send_at. 3 days after send_at.

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary

Click here to learn more about parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

id
string

Unique identifier for batch

created_at
string <date-time>

Timestamp for when batch was created.

ISO-8601 format

modified_at
string <date-time>

Timestamp for when batch was last updated.

ISO-8601 format

canceled
boolean

Indicates if the batch has been canceled or not.

Request samples

const fetch = require('node-fetch');

const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
const batchId = 'YOUR_batch_id_PARAMETER';
const resp = await fetch(
  `https://us.sms.api.sinch.com/xms/v1/${servicePlanId}/batches/${batchId}`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    }
  }
);

const data = await resp.text();
console.log(data);

Response samples

Content type
application/json
{
  • "id": "9dfn32n423kljklj234",
  • "from": "12345",
  • "to": [
    • "+15551231212"
    ],
  • "body": "Hello how are you",
  • "created_at": "2020-02-25T23:01:01Z",
  • "modified_at": "2020-02-25T23:01:01Z",
  • "canceled": false
}

Update a Batch message

This operation updates all specified parameters of a batch that matches the provided batch ID.

Authorizations:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 4HJY56S2r4t6c
Request Body schema: application/json
toAdd
Array of strings [ 1 .. 100 ] items

List of phone numbers and group IDs to add to the batch.

Constraints: 1 to 100 elements.

toRemove
Array of strings

List of phone numbers and group IDs to remove from the batch.

constraints: 1 to 100 elements.

from
string

Sender number.

Default: Must be valid phone number, short code or alphanumeric.

body
string <= 1600 characters

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Constraints: Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary

delivery_report
string

Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.

Constraints: Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

f set in the future the message will be delayed until send_at occurs. ISO-8601 format.

Constraints: Must be before expire_at. If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Constraints: Must be after send_at

Default: 3 days after send_at

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Constraints: Must be valid URL. Max 2048 characters long.

Responses

Response Schema: application/json
to
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info Constraints: 1 to 1000 elements

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text is regular SMS, mt_binary is a binary format.

Enum: "mt_text" "mt_binary"
body
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Must be after send_at. 3 days after send_at.

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary

Click here to learn more about parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

id
string

Unique identifier for batch

created_at
string <date-time>

Timestamp for when batch was created.

ISO-8601 format

modified_at
string <date-time>

Timestamp for when batch was last updated.

ISO-8601 format

canceled
boolean

Indicates if the batch has been canceled or not.

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "from": "+15551231234",
  • "type": "mt_text",
  • "body": "This is a message to be sent!",
  • "udh": "string",
  • "delivery_report": "none",
  • "send_at": "2019-08-24T14:15:22Z",
  • "expire_at": "3 days after send_at",
  • "callback_url": "string",
  • "flash_message": false,
  • "parameters": {
    • "{parameter_key}": "string",
    • "{parameter_key}.{msisdn}": "string",
    • "{parameter_key}.default": "string"
    },
  • "client_reference": "string",
  • "max_number_of_message_parts": 1,
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "canceled": true
}

Replace a batch

This operation will replace all the parameters of a batch with the provided values. Effectively the same as cancelling a batch and sending a new one instead.

Authorizations:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 4HJY56S2r4t6c
Request Body schema: application/json
to
required
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items
Default: ["+15551231234","+15551256344"]

List of Phone numbers and group IDs that will receive the batch. Constraints: 1 to 1000 elements More info

body
required
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text

Enum: "mt_text" "mt_binary"
udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Must be after send_at. 3 days after send_at.

callback_url
string <uri> <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary 'example : "parameters: [{"name": { "123456789": "Joe", "default": "there"}]' Click here to learn more about parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

Responses

Response Schema: application/json
to
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info Constraints: 1 to 1000 elements

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text is regular SMS, mt_binary is a binary format.

Enum: "mt_text" "mt_binary"
body
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Must be after send_at. 3 days after send_at.

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary

Click here to learn more about parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

id
string

Unique identifier for batch

created_at
string <date-time>

Timestamp for when batch was created.

ISO-8601 format

modified_at
string <date-time>

Timestamp for when batch was last updated.

ISO-8601 format

canceled
boolean

Indicates if the batch has been canceled or not.

Request samples

Content type
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "body": "This is a message to be sent!"
}

Response samples

Content type
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "from": "+15551231234",
  • "type": "mt_text",
  • "body": "This is a message to be sent!",
  • "udh": "string",
  • "delivery_report": "none",
  • "send_at": "2019-08-24T14:15:22Z",
  • "expire_at": "3 days after send_at",
  • "callback_url": "string",
  • "flash_message": false,
  • "parameters": {
    • "{parameter_key}": "string",
    • "{parameter_key}.{msisdn}": "string",
    • "{parameter_key}.default": "string"
    },
  • "client_reference": "string",
  • "max_number_of_message_parts": 1,
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "canceled": true
}

Cancel a batch message

A batch can be canceled at any point. If a batch is canceled while it's currently being delivered some messages currently being processed might still be delivered. The delivery report will indicate which messages were canceled and which weren't.

Canceling a batch scheduled in the future will result in an empty delivery report while canceling an already sent batch would result in no change to the completed delivery report.

Authorizations:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 4HJY56S2r4t6c

Responses

Response Schema: application/json
to
required
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items
Default: ["+15551231234","+15551256344"]

List of Phone numbers and group IDs that will receive the batch. Constraints: 1 to 1000 elements More info

body
required
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text

Enum: "mt_text" "mt_binary"
udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full and per_recipient

Enum: "none" "summary" "full" "per_recipient"
send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past messages will be sent immediately.

expire_at
string <date-time>
Default: "3 days after send_at"

If set the system will stop trying to deliver the message at this point.

Must be after send_at. 3 days after send_at.

callback_url
string <uri> <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary 'example : "parameters: [{"name": { "123456789": "Joe", "default": "there"}]' Click here to learn more about parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

Request samples

const fetch = require('node-fetch');

const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
const batchId = 'YOUR_batch_id_PARAMETER';
const resp = await fetch(
  `https://us.sms.api.sinch.com/xms/v1/${servicePlanId}/batches/${batchId}`,
  {
    method: 'DELETE',
    headers: {
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    }
  }
);

const data = await resp.text();
console.log(data);

Response samples

Content type
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "from": "+15551231234",
  • "type": "mt_text",
  • "body": "This is a message to be sent!",
  • "udh": "string",
  • "delivery_report": "summary",
  • "send_at": "2019-08-24T14:15:22Z",
  • "expire_at": "3 days after send_at",
  • "flash_message": false,
  • "parameters": {
    • "{parameter_key}": {
      • "{msisdn}": "{\"15551231212\":\"Joe\"}",
      • "default": "{\"default\":\"Customer\"}"
      }
    },
  • "client_reference": "string",
  • "max_number_of_message_parts": 1
}

Incoming SMS Webhook

An inbound message is a message sent to one of your shortcodes 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 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.

operator_id
string

The MCCMNC of the sender's operator if known.

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

Responses

Request samples

Content type
application/json
{
  • "value": {
    • "type": "mo_text",
    • "id": "HYtJKLlsI32IK",
    • "from": "+11203494390",
    • "to": "+11203453453",
    • "body": "This is a test message",
    • "operator_id": null,
    • "sent_at": null,
    • "received_at": null
    }
}