Download OpenAPI specification:Download

Messages

Send a message to one or many recipients. This API supports the same channels as Conversation API.

Send a batch of messages

Send a message to multiple recipients. Parameter variables can be included in all string fields and customized with recipient specific values. Each recipient in the request will generate a message and subsequent delivery reports based on the channel used.

SecurityBearerAuth
Request
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

Request Body schema: application/json
required
app_id
required
string

The ID of the app sending the message.

required
Card (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object) (AppMessage)

Message that will be sent to the recipients. Parameters can be specified in any of the string fields inside this structure in the format ${parameter}, where parameter is the parameter name.

required
Array of objects (RecipientAndParam) [ 1 .. 1000 ] items

A list of recipients who will receive the message. Each recipient entry can include custom parameters and metadata that apply only to that recipient.

processing_strategy
string (ProcessingStrategy)

Overrides the app's Processing Mode. Default value is DEFAULT.

Enum Value Description
DEFAULT

The request will inherit the app's configured processing mode.

DISPATCH_ONLY

Forces the request to be processed in dispatch mode (without storing contacts and conversations), regardless of the app's configured processing mode. Please note that user replies will still be processed in the app's default processing mode and that the conversation_metadata and correlation_id fields are not supported when using this option with an app in CONVERSATION mode.

object

Custom metadata that will be attached to the batch itself and returned in the response. This metadata can later be used to manage the batch. For example, you can use the metadata to cancel it. Note: _batch_id is a reserved field that should not be included in this object, as it will be automatically added by the API.

object

Optional metadata that will be associated with the messages generated by the batch. Returned in the metadata field of a Message Delivery Receipt. This map is converted to a JSON string for compatibility with the Conversation API. See Conversation API metadata for details.

object

Metadata that will be associated with the conversation of each message in the batch. This metadata will be included in delivery receipts and can be used to correlate MO (mobile originated) messages with the original batch. See Conversation API metadata reference for details.

send_after
string <date-time>

Specifies when the batch should be sent. If not provided, it defaults to the current time and sends immediately. The value must be in UTC. If the scheduled time is less than 1 minute from the API call, it will be used as-is (with second-level precision). For times further in the future, the value will be rounded up to the next five-minute mark. The maximum allowed delay is 7 days. The final send_after value is returned in the response.

channel_priority_order
Array of strings (Channel Identifier)

Defines the channels to use for message delivery and the order in which they will be attempted. See Conversation API reference for details.

Items Enum Value Description
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBER

The Viber Bot channel.

VIBERBM

The Viber Business Messages channel.

MMS

The MMS channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

KAKAOTALKCHAT

The KakaoTalk chat channel (used primarily in ConsultationTalk).

LINE

The LINE channel.

WECHAT

The WeChat channel.

APPLEBC

The Apple Messages for Business channel.

ttl
string

The timeout allotted for sending the message, expressed in seconds. Passed to channels which support it and emulated by the Conversation API for channels without ttl support but with message retract/unsend functionality. Channel failover will not be performed for messages with an expired TTL.

The format is an integer with the suffix s (for seconds). Valid integer range is 3 to 315,576,000,000 (inclusive). Example values include 10s (10 seconds) and 86400s (24 hours).

object

Channel-specific properties. The key in the map must point to a valid channel property and the maximum allowed property value length is 1024 characters.

correlation_id
string

An arbitrary identifier that will be propagated to callbacks related to this message, including MO messages from the recipient. The MO callbacks will always use the last correlation_id available in the conversation, similar to how conversation_metadata works. Only applicable to messages sent with the CONVERSATION processing mode. Up to 128 characters long.

Responses
200

OK

Response Schema: application/json
batch_id
string

The ID of the batch sent. This ID will be present in the metadata field of all the delivery receipts for messages generated from this batch request, with the key _batch_id.

send_after
string <date-time>

Time at which the batch of messages will be sent to the recipients.

400

Malformed request

401

Invalid credentials

403

Permission denied. The specified project may not be allowed to use the batch endpoint.

500

Internal error

post/v1/projects/{project_id}/messages
Request samples
application/json
{
  • "app_id": "{{APP}}",
  • "message": {
    • "text_message": {
      • "text": "Hello ${user}! Your code is ${code}"
      }
    },
  • "recipient_and_params": [
    • {
      • "recipient": {
        • "contact_id": "{{CONTACT-1}}"
        },
      • "parameters": {
        • "user": "User 1",
        • "code": "123"
        }
      },
    • {
      • "recipient": {
        • "contact_id": "{{CONTACT-2}}"
        },
      • "parameters": {
        • "user": "User 2",
        • "code": "456"
        }
      },
    • {
      • "recipient": {
        • "contact_id": "{{CONTACT-3}}"
        },
      • "parameters": {
        • "user": "User 3",
        • "code": "789"
        }
      }
    ]
}
Response samples
application/json
{
  • "batch_id": "01GCA8RWNW9FVGVSYS1BMKRW80",
  • "send_after": "2022-11-28T12:46:59Z"
}

Cancel scheduled messages

Cancel one or more scheduled message batches by ID or by batch metadata. If using metadata, all batches matching the given key and value will be cancelled.

To successfully cancel a batch, you must do so before the send_after time. Batches without a send_after value (i.e., batches that are sent immediately) cannot be cancelled.

Cancellation is performed asynchronously. This means that this method always returns a 200 response, even if the cancellation fails.

SecurityBearerAuth
Request
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

Request Body schema: application/json
required
One of:

ID of the batch to be cancelled.

batch_id
string
Responses
200

OK

401

Invalid credentials

403

Permission denied. The specified project may not be allowed to use the batch endpoint.

500

Internal error

delete/v1/projects/{project_id}/messages
Request samples
application/json
{
  • "batch_id": "01GJJE4HZTAR53YE1WAA6VCF4D"
}
Response samples
application/json
{
  • "error": {
    • "code": 403,
    • "message": "",
    • "status": "PERMISSION_DENIED",
    • "details": [ ]
    }
}

Get the status of batch of messages

Retrieve the status of a batch of messages by its unique batch ID.

SecurityBearerAuth
Request
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

batch_id
required
string

The unique ID of the batch. This ID is returned when submitting a batch of messages.

Responses
200

OK

Response Schema: application/json
batch_id
string

The ID of the batch of messages.

object

The metadata associated with the batch of messages.

status
string

The status of the batch of messages.

Enum: "READY" "SCHEDULED" "PROCESSED" "CANCELLED"
send_after
string <ISO 8601>

The date and time when the batch of messages is or was scheduled to be sent to recipients.

401

Invalid credentials

403

Permission denied. The specified project may not be allowed to use the batch endpoint.

404

Batch not found

500

Internal error

get/v1/projects/{project_id}/messages/{batch_id}
Request samples
Response samples
application/json
{
  • "batch_id": "string",
  • "meta_data": {
    • "property1": "string",
    • "property2": "string"
    },
  • "status": "READY",
  • "send_after": "string"
}