Download OpenAPI specification:Download

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.

Send

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

Be sure to use the correct region in the server URL.

SecurityBearerAuth

Request

path Parameters

service_plan_id

required

string

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

Example: jd63jf88477ll123ab4567cd89012ef3

Request Body schema: application/json

Default schema is Text if type is not specified.

One of:

body

required

string [ 0 .. 2000 ] characters

The message content

required

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from

string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

object (parameterObj)

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

Click here to learn more about parameterization.

type

string

Regular SMS

Value	Description
mt_text	Regular SMS

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

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

expire_at

string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url

string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be a valid URL. Learn how to set a default callback URL here.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

flash_message

boolean

Default: false

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts

integer <int32> >= 1

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

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

Responses

201

Created. A successful response, or an Error.

Response Schema: application/json

type

required

string

Regular SMS

string

Unique identifier for batch

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from

string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

canceled

boolean

Default: false

Indicates if the batch has been canceled or not.

object (parameterObj)

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

Click here to learn more about parameterization.

body

string [ 0 .. 2000 ] characters

The message content

created_at

string <date-time>

Timestamp for when batch was created. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at

string <date-time>

Timestamp for when batch was last updated. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

send_at

string <date-time>

expire_at

string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url

string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be valid URL.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

flash_message

boolean

Default: false

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts

integer <int32> >= 1

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

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

post/xms/v1/{service_plan_id}/batches

Request samples

application/json

{"from": "YOUR_Sinch_virtual_number",
"to": ["YOUR_recipient_number"
],
"body": "YOUR_message_body",
"type": "mt_text"
}

Response samples

application/json

{"id": "01FC66621XXXXX119Z8PMV1QPQ",
"to": [15551231234,
15551256344
],
"from": 15551231234,
"canceled": false,
"parameters": {"{parameter_key}": {"{msisdn}": 15551231234,
"default": "string"
}
},
"body": "Hi ${name}! How are you?",
"type": "mt_text",
"created_at": "2019-08-24T14:15:22Z",
"modified_at": "2019-08-24T14:15:22Z",
"delivery_report": "none",
"send_at": "2019-08-24T14:15:22Z",
"expire_at": "2019-08-24T14:15:22Z",
"callback_url": "myCallbackUrl",
"client_reference": "myReference",
"feedback_enabled": false,
"flash_message": false,
"truncate_concat": true,
"max_number_of_message_parts": 1,
"from_ton": 6,
"from_npi": 18
}

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.

SecurityBearerAuth

Request

path Parameters

service_plan_id

required

string

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

Example: jd63jf88477ll123ab4567cd89012ef3

query Parameters

page	integer >= 0 Default: 0 The page number starting from 0. Example: page=2
page_size	integer <= 100 Default: 30 Determines the size of a page. Example: page_size=50
from	Array of strings Only list messages sent from this sender number. Multiple originating numbers can be comma separated. Must be phone numbers or short code. Example: from=44345,45607
start_date	string <date-time> Only list messages received at or after this date/time. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`. Default: Now-24
end_date	string <date-time> Only list messages received before this date/time. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
client_reference	string [ 0 .. 2048 ] characters Client reference to include Example: client_reference=myReference

Responses

200

OK. A successful response, or an Error.

Response Schema: application/json

count	integer <int64> The total number of entries matching the given filters.
page	integer <int32> The requested page.
	Array of objects (Batch) The page of batches matching the given filters.
page_size	integer <int32> The number of entries returned in this request.

get/xms/v1/{service_plan_id}/batches

Request samples

Response samples

application/json

{"count": "2",
"page": "1",
"batches": [{"id": "abc123",
"to": ["01234567"
],
"from": "01234567",
"canceled": false,
"body": "Test message",
"udh": "abcxaf123",
"type": "mt_text",
"created_at": "2023-11-11T09:00:20.0",
"modified_at": "2023-11-11T09:00:20.0",
"delivery_report": "none",
"send_at": "2023-11-11T09:00:20.0",
"expire_at": "",
"callback_url": "",
"client_reference": "xyz",
"feedback_enabled": false,
"flash_message": false,
"truncate_concat": "false",
"max_number_of_message_parts": "1",
"from_ton": "0",
"from_npi": "0"
},
{"id": "def345",
"to": ["07654321"
],
"from": "012346790",
"canceled": false,
"body": "Test Message 2",
"udh": "abcxaf123",
"type": "mt_text",
"created_at": "2023-11-11T09:00:20.0",
"modified_at": "2023-11-11T09:00:20.0",
"delivery_report": "none",
"send_at": "2023-11-11T09:00:20.0",
"expire_at": "2023-11-11T09:00:20.0",
"callback_url": "",
"client_reference": "abc",
"feedback_enabled": false,
"flash_message": false,
"truncate_concat": "false",
"max_number_of_message_parts": "1",
"from_ton": "0",
"from_npi": "0"
}
],
"page_size": "10"
}

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.

SecurityBearerAuth

Request

path Parameters

service_plan_id

required

string

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

Example: jd63jf88477ll123ab4567cd89012ef3

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
required

One of:

body

required

string [ 0 .. 2000 ] characters

The message content

required

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from

string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

object (parameterObj)

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

Click here to learn more about parameterization.

type

string

Regular SMS

Value	Description
mt_text	Regular SMS

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

send_at

string <date-time>

expire_at

string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url

string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be a valid URL. Learn how to set a default callback URL here.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

flash_message

boolean

Default: false

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts

integer <int32> >= 1

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

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

Responses

200

OK. A successful response , or an Error.

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

post/xms/v1/{service_plan_id}/batches/dry_run

Request samples

application/json

{"from": "YOUR_virtual_number",
"to": ["YOUR_numbers_sending_to",
"another_number"
],
"body": "YOUR body text here",
"parameters": {"name": {"Phone_number_of_recipient": "recipient_name",
"default": "default_in_place_of_name"
}
}
}

Response samples

application/json

{"number_of_recipients": 1,
"number_of_messages": 1,
"per_recipient": [{"recipient": 15551231234,
"number_of_parts": 1,
"body": "Test Message",
"encoding": "GSM"
}
]
}

Get a batch message

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

SecurityBearerAuth

Request

path Parameters

service_plan_id required	string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3
batch_id required	string The batch ID you received from sending a message. Example: 01FC66621XXXXX119Z8PMV1QPQ

Responses

200

OK. A successful response , or an Error.

Response Schema: application/json

type

required

string

Regular SMS

string

Unique identifier for batch

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from

string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

canceled

boolean

Default: false

Indicates if the batch has been canceled or not.

object (parameterObj)

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

Click here to learn more about parameterization.

body

string [ 0 .. 2000 ] characters

The message content

created_at

string <date-time>

Timestamp for when batch was created. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at

string <date-time>

Timestamp for when batch was last updated. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

send_at

string <date-time>

expire_at

string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url

string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be valid URL.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

flash_message

boolean

Default: false

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts

integer <int32> >= 1

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

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

get/xms/v1/{service_plan_id}/batches/{batch_id}

Request samples

Response samples

application/json

{"id": "01FC66621XXXXX119Z8PMV1QPQ",
"to": [15551231234,
15551256344
],
"from": 15551231234,
"canceled": false,
"parameters": {"{parameter_key}": {"{msisdn}": 15551231234,
"default": "string"
}
},
"body": "Hi ${name}! How are you?",
"type": "mt_text",
"created_at": "2019-08-24T14:15:22Z",
"modified_at": "2019-08-24T14:15:22Z",
"delivery_report": "none",
"send_at": "2019-08-24T14:15:22Z",
"expire_at": "2019-08-24T14:15:22Z",
"callback_url": "myCallbackUrl",
"client_reference": "myReference",
"feedback_enabled": false,
"flash_message": false,
"truncate_concat": true,
"max_number_of_message_parts": 1,
"from_ton": 6,
"from_npi": 18
}

Update a Batch message

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

SecurityBearerAuth

Request

path Parameters

service_plan_id required	string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3
batch_id required	string The batch ID you received from sending a message. Example: 01FC66621XXXXX119Z8PMV1QPQ

Request Body schema: application/json
required

One of:

from

string

Sender number. Must be valid phone number, short code or alphanumeric.

type

string

Regular SMS

Value	Description
mt_text	Regular SMS

to_add

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

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

to_remove

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

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

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

send_at

string <date-time>

If set, in the future the message will be delayed until send_at occurs. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

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

expire_at

string <date-time>

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 [ 0 .. 2048 ] characters

Override the default callback URL for this batch.

Constraints: Must be valid URL.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

object (parameterObj)

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

Click here to learn more about parameterization.

body

string [ 0 .. 2000 ] characters

The message content

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

max_number_of_message_parts

integer <int32> >= 1

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

flash_message

boolean

Default: false

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

Responses

200

A successful response , or an Error.

Response Schema: application/json

type

required

string

Regular SMS

string

Unique identifier for batch

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from

string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

canceled

boolean

Default: false

Indicates if the batch has been canceled or not.

object (parameterObj)

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

Click here to learn more about parameterization.

body

string [ 0 .. 2000 ] characters

The message content

created_at

string <date-time>

Timestamp for when batch was created. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at

string <date-time>

Timestamp for when batch was last updated. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

send_at

string <date-time>

expire_at

string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url

string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be valid URL.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

flash_message

boolean

Default: false

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts

integer <int32> >= 1

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

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

post/xms/v1/{service_plan_id}/batches/{batch_id}

Request samples

application/json

{"to_remove": ["YOUR_numbers",
"to_remove",
"as_strings_in_array",
"with_country_code",
"16267890123"
],
"to_add": ["YOUR_numbers",
"to_add"
]
}

Response samples

application/json

{"id": "01FC66621XXXXX119Z8PMV1QPQ",
"to": [15551231234,
15551256344
],
"from": 15551231234,
"canceled": false,
"parameters": {"{parameter_key}": {"{msisdn}": 15551231234,
"default": "string"
}
},
"body": "Hi ${name}! How are you?",
"type": "mt_text",
"created_at": "2019-08-24T14:15:22Z",
"modified_at": "2019-08-24T14:15:22Z",
"delivery_report": "none",
"send_at": "2019-08-24T14:15:22Z",
"expire_at": "2019-08-24T14:15:22Z",
"callback_url": "myCallbackUrl",
"client_reference": "myReference",
"feedback_enabled": false,
"flash_message": false,
"truncate_concat": true,
"max_number_of_message_parts": 1,
"from_ton": 6,
"from_npi": 18
}

Replace a batch

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

SecurityBearerAuth

Request

path Parameters

service_plan_id required	string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3
batch_id required	string The batch ID you received from sending a message. Example: 01FC66621XXXXX119Z8PMV1QPQ

Request Body schema: application/json
required

One of:

body

required

string [ 0 .. 2000 ] characters

The message content

required

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from

string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

object (parameterObj)

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

Click here to learn more about parameterization.

type

string

Regular SMS

Value	Description
mt_text	Regular SMS

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

send_at

string <date-time>

expire_at

string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url

string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be a valid URL. Learn how to set a default callback URL here.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

flash_message

boolean

Default: false

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts

integer <int32> >= 1

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

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

Responses

200

A successful response , or an Error.

Response Schema: application/json

type

required

string

Regular SMS

string

Unique identifier for batch

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from

string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

canceled

boolean

Default: false

Indicates if the batch has been canceled or not.

object (parameterObj)

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

Click here to learn more about parameterization.

body

string [ 0 .. 2000 ] characters

The message content

created_at

string <date-time>

Timestamp for when batch was created. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at

string <date-time>

Timestamp for when batch was last updated. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

send_at

string <date-time>

expire_at

string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url

string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be valid URL.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

flash_message

boolean

Default: false

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts

integer <int32> >= 1

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

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

put/xms/v1/{service_plan_id}/batches/{batch_id}

Request samples

application/json

{"to": [15551231234,
15551256344
],
"body": "Hi ${name}! How are you?"
}

Response samples

application/json

{"id": "01FC66621XXXXX119Z8PMV1QPQ",
"to": ["+15551231234",
"+15551256344"
],
"from": "+15551231234",
"canceled": false,
"parameters": {"property1": {"property1": "string",
"property2": "string"
},
"property2": {"property1": "string",
"property2": "string"
}
},
"body": "Hi ${name}! How are you?",
"type": "mt_text",
"created_at": "2019-08-24T14:15:22Z",
"modified_at": "2019-08-24T14:15:22Z",
"delivery_report": "none",
"send_at": "2019-08-24T14:15:22Z",
"expire_at": "2019-08-24T14:15:22Z",
"callback_url": "string",
"client_reference": "myReference",
"feedback_enabled": false,
"flash_message": false,
"truncate_concat": true,
"max_number_of_message_parts": 1,
"from_ton": 6,
"from_npi": 18
}

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.

SecurityBearerAuth

Request

path Parameters

service_plan_id required	string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3
batch_id required	string The batch ID you received from sending a message. Example: 01FC66621XXXXX119Z8PMV1QPQ

Responses

200

Batch deleted or an Error.

Response Schema: application/json

type

required

string

Regular SMS

string

Unique identifier for batch

Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from

string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

canceled

boolean

Default: false

Indicates if the batch has been canceled or not.

object (parameterObj)

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

Click here to learn more about parameterization.

body

string [ 0 .. 2000 ] characters

The message content

created_at

string <date-time>

Timestamp for when batch was created. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at

string <date-time>

Timestamp for when batch was last updated. Formatted as ISO-8601:YYYY-MM-DDThh:mm:ss.SSSZ.

delivery_report

string (DeliveryReportType)

Kind of delivery report

Enum Value	Description
none	No delivery report callback will be sent.
summary	A single delivery report callback will be sent.
full	A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient	A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more

send_at

string <date-time>

expire_at

string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url

string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be valid URL.

client_reference

string [ 0 .. 2048 ] characters

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

feedback_enabled

boolean

Default: false

If set to true, then feedback is expected after successful delivery.

flash_message

boolean

Default: false

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

truncate_concat

boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts

integer <int32> >= 1

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

from_ton

integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi

integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

delete/xms/v1/{service_plan_id}/batches/{batch_id}

Request samples

Response samples

application/json

{"id": "01FC66621XXXXX119Z8PMV1QPQ",
"to": [15551231234,
15551256344
],
"from": 15551231234,
"canceled": true,
"parameters": {"{parameter_key}": {"{msisdn}": 15551231234,
"default": "string"
}
},
"body": "Hi ${name}! How are you?",
"type": "mt_text",
"created_at": "2019-08-24T14:15:22Z",
"modified_at": "2019-08-24T14:15:22Z",
"delivery_report": "none",
"send_at": "2019-08-24T14:15:22Z",
"expire_at": "2019-08-24T14:15:22Z",
"callback_url": "myCallbackUrl",
"client_reference": "myReference",
"feedback_enabled": false,
"flash_message": false,
"truncate_concat": true,
"max_number_of_message_parts": 1,
"from_ton": 6,
"from_npi": 18
}

Send delivery feedback for a message

Send feedback if your system can confirm successful message delivery.

Feedback can only be provided if feedback_enabled was set when batch was submitted.

Batches: It is possible to submit feedback multiple times for the same batch for different recipients. Feedback without specified recipients is treated as successful message delivery to all recipients referenced in the batch. Note that the recipients key is still required even if the value is empty.

Groups: If the batch message was creating using a group ID, at least one recipient is required. Excluding recipients (an empty recipient list) does not work and will result in a failed request.

SecurityBearerAuth

Request

path Parameters

service_plan_id required	string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3
batch_id required	string The batch ID you received from sending a message. Example: 01FC66621XXXXX119Z8PMV1QPQ

Request Body schema: application/json
required

A list of phone numbers (MSISDNs) that successfully received the message.

recipients

required

Array of strings

A list of phone numbers (MSISDNs) that have successfully received the message. The key is required, however, the value can be an empty array ([]) for a batch. If the feedback was enabled for a group, at least one phone number is required.

Responses

202

Accepted, or an Error. A successful response will return an empty 202 HTTP response, indicating that the request has been received and is processing.

post/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_feedback

Request samples

application/json

{"recipients": ["+15551231234",
"+15551256344"
]
}

Security Privacy Legal & Compliance Cookie Statement

Batches

Send

path Parameters

Request Body schema: application/json

Response Schema: application/json

List Batches

path Parameters

query Parameters

Response Schema: application/json

Dry run

path Parameters

query Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Get a batch message

path Parameters

Response Schema: application/json

Update a Batch message

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Replace a batch

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Cancel a batch message

path Parameters

Response Schema: application/json

Send delivery feedback for a message

path Parameters

Request Body schema: application/jsonrequired

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required