Omnichannel
Omnichannel lets you communicate with your customers across multiple channels through one single interface. With it you can:
- send messages with built-in fallback routes,
- receive delivery notifications (DLRs),
- handle inbound messages,
- download inbound media and other event data.
Supported channels: RBM, SMS, Telegram, WhatsApp, Facebook and Instagram Messenger, and Email (outbound only).
Unifier API
The Unifier API is the SMS.es HTTP API for omnichannel messaging. Use it to send messages (including fallback routes), retrieve notifications for DLRs and inbound messages, and download inbound media and other events.
The complete API reference is available in the OpenAPI specification.
What You Can Do with the Unifier API
The SMS.es Unifier API lets you send and receive messages across multiple channels through a single interface — with built-in fallback routes, delivery tracking and inbound message handling.
- Send messages — send a message to a receiver on any supported channel, with one or more fallback messages if the primary channel fails.
- Retrieve messages — get a previously sent message by its ID, including its sender, receiver, channel and body.
- Get notifications — poll for the latest notifications (DLRs, inbound messages and fallback events) across all channels.
- Webhooks — register a webhook to receive the same notifications pushed in real time, instead of polling.
- Download media — download media files (images, audio, video, documents) delivered by inbound messages.
- Senders — look up the available senders, filtered by one or more channel types.
Supported channels
RBM, SMS, Telegram, WhatsApp, Facebook and Instagram Messenger, and Email (outbound only).
Common scenarios
- Multi-channel notifications with fallback — for example, try RBM first and fall back to SMS if the receiver doesn’t have RCS.
- Rich messaging — cards, carousels, WhatsApp templates, location and contact messages, in addition to plain text.
- Delivery tracking — DLR and status updates via webhook, or by polling for updates.
- Inbound handling — receive customer replies and download any media they send.
Authentication
Every REST call, except your own webhook endpoint, must include the API key in the X-API-Key header. The key is the client_secret of your customer connection; some deployments also enforce an IP whitelist.
Send a Message with a Fallback
curl -X POST "{{BASE}}/v1/messages" \
-H "X-API-Key: <X-API-Key>" \
-H "Content-Type: application/json" \
-d '{
"message": {
"sender": "SMSes_Agent",
"receiver": "34600123456",
"channel": "whatsApp",
"body": {
"textMessage": {
"content": "Your order has shipped!"
}
}
},
"fallback": [
{
"sender": "SMSes",
"receiver": "34600123456",
"channel": "sms",
"body": {
"textMessage": {
"content": "Your order has shipped! (SMS fallback)"
}
}
}
]
}'The response confirms which channel actually carried the message:
{
"message": {
"msgId": "b1f6b8b2-6e7b-4a9a-9a3e-2f7e6a3c9b10",
"channel": "whatsApp",
"hasFallbacks": true
}
}Get the Latest Notifications
curl "{{BASE}}/v1/updates?order=desc" \
-H "X-API-Key: <X-API-Key>"List Senders by Channel
curl "{{BASE}}/v1/senders?channelType=whatsApp,sms" \
-H "X-API-Key: <X-API-Key>"Receiving Notifications via Webhook
Instead of polling for updates, register a webhook URL in your connection settings to receive the same Notification payloads pushed in real time. Each request carries an X-Msg-Api-Signature header (base64(SHA512(body + verifyToken))) so you can verify that it was sent by the platform.
Technical Characteristics
- REST HTTP API with JSON payloads
- API key authentication (
X-API-Keyheader), with optional IP whitelisting - Multi-channel: RBM, SMS, Telegram, WhatsApp, Facebook and Instagram Messenger, and Email (outbound only)
- Fallback message chains and rich message types (text, media, cards, carousels, templates, location, contacts)
- Push notifications via signed webhook, or on-demand polling for updates
Unifier API
The Unifier API is the SMS.es HTTP API for omnichannel messaging. Use it to send messages (including fallback routes), retrieve notifications for DLRs and inbound messages, and download inbound media and other events.
UnifierAPI
Unifier API is an HTTP API for omnichannel messaging. Use it to send messages (including fallback routes), retrieve notifications for DLRs and inbound messages, or download inbound media and other events.
The API base URL is:
{{BASE}}
Supported channels: RBM, SMS, Telegram, WhatsApp, Email*, Facebook and Instagram Messenger.
* Outbound only
Typical flows:
- Send messages with optional fallback messages (
POST /v1/messages). - Poll for notifications (
GET /v1/updates). - Register a customer webhook URL in your connection settings to receive the same notification payloads as push-style
Notificationevents (signed withX-Msg-Api-Signature).
Authentication: every REST call (except your own webhook endpoint) must include the API key in the X-API-Key header. Keys are the client_secret of the customer connection. Some deployments also enforce an IP whitelist on the connection.
Definitions:
- Message request — the HTTP request from the customer to the Unifier API to send a message to the intended recipient’s device. It can also contain fallback messages.
- Outbound message — a message delivered from our service to the telecom network, or to Google RBM, WhatsApp, etc., to terminate on the intended recipient’s device.
- Inbound message — a message initiated and sent by a mobile subscriber (end user) from their device, routed via the SMS telecom network or Google RBM, WhatsApp, etc., to the designated sender of the message request.
- DLR — a status sent back by the telecom network to confirm whether a previously submitted SMS was delivered to the recipient’s handset, or to report a failure/error if delivery was unsuccessful.
- Notification — information about an inbound message, a DLR or a fallback event.
Authentication
| Security Scheme Type: | apiKey |
|---|---|
| Header parameter name: | X-API-Key |
API key obtained from the client_secret of your customer connection. Send it as X-API-Key: <your-key-here>
Message Request
A message request is the HTTP request you send to the Unifier API (POST /v1/messages) to deliver a message to a receiver.
Each request specifies the sender, the receiver, the channel (one of rbm, sms, telegram, whatsApp, email, instagram, facebook) and the message body.
The body can be any of the supported message types: plain text, file, audio, picture, video, location, contact card, email, WhatsApp template, RBM card, RBM carousel or RBM suggestions.
A request can also include an optional fallback array — alternate messages, which can target different channels, sent automatically if the primary message is not delivered.
Request to send a message that may include fallback messages to a receiver
Request to send a message that may include fallback messages to a receiver.
Request
{
"message": {
"msgId": "string",
"sender": "string",
"receiver": "string",
"channel": "rbm",
"validityPeriod": 0,
"connectionCName": "string",
"dcs": "gsm",
"body": {
"fileMessage": {
"name": "string",
"url": "string",
"fileType": "string",
"mimeType": "string",
"size": 0,
"playingLength": "string",
"thumbnailName": "string",
"thumbnailUrl": "string",
"thumbnailMimeType": "string",
"thumbnailSize": 0
}
},
"custom": {}
},
"fallback": [
{
"msgId": "string",
"sender": "string",
"receiver": "string",
"channel": "rbm",
"validityPeriod": 0,
"connectionCName": "string",
"dcs": "gsm",
"body": {
"fileMessage": {
"name": "string",
"url": "string",
"fileType": "string",
"mimeType": "string",
"size": 0,
"playingLength": "string",
"thumbnailName": "string",
"thumbnailUrl": "string",
"thumbnailMimeType": "string",
"thumbnailSize": 0
}
},
"custom": {}
}
]
}Bodyrequired
messageobjectrequired
rbm], [sms], [telegram], [whatsApp], [email], [instagram], [facebook]rbm is RCS Business Messaging).gsm], [unicode], [auto]bodyoneOfrequired
fileMessageobject
textMessageobject
audioMessageobject
pictureMessageobject
videoMessageobject
locationMessageobject
contactMessageobject
componentsTemplateComponent[]required
parametersComponentParameter[]required
emailMessageobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentobjectrequired
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentMessageContentCard[]required
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
customobject
fallbackIndividualMessage[]
rbm], [sms], [telegram], [whatsApp], [email], [instagram], [facebook]rbm is RCS Business Messaging).gsm], [unicode], [auto]bodyoneOfrequired
fileMessageobject
textMessageobject
audioMessageobject
pictureMessageobject
videoMessageobject
locationMessageobject
contactMessageobject
componentsTemplateComponent[]required
parametersComponentParameter[]required
emailMessageobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentobjectrequired
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentMessageContentCard[]required
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
customobject
Responses
Successful operation (message accepted for processing; implementation returns HTTP 200).
{
"message": {
"msgId": "7d0f9c1e-2b1a-4c3e-9f5a-0e6b2d7a8c41",
"channel": "rbm",
"hasFallbacks": true,
"smsParts": {
"total": 0
}
}
}Schema
messageobject
rbm], [sms], [telegram], [whatsApp], [email], [instagram], [facebook]rbm is RCS Business Messaging).smsPartsobject
Invalid input
{
"error": {
"code": "string",
"message": "string",
"description": "string",
"items": [
{
"name": "string",
"message": "string",
"description": "string"
}
]
}
}Schema
errorobject
itemsobject[]
Unauthorized
Inbound and Outbound message retrievers
Use GET /v1/messages/{msgId} to look up a single message by its UUID and get its full details — sender, receiver, channel and body.
It is useful to check a specific inbound or outbound message without waiting for its next notification event.
Get the message based on the message's ID
Get the message based on the message’s ID.
Request
Path Parameters
Responses
Return the message.
{
"msgId": "b1f6b8b2-6e7b-4a9a-9a3e-2f7e6a3c9b10",
"sender": "SMSes_Agent",
"receiver": "34600123456",
"channel": "rbm",
"validityPeriod": 0,
"body": {
"textMessage": {
"content": "Your order #4521 has shipped and arrives tomorrow."
}
},
"custom": {
"orderId": "4521"
}
}Schema
rbm], [sms], [telegram], [whatsApp], [email], [instagram], [facebook]rbm is RCS Business Messaging).gsm], [unicode], [auto]bodyoneOfrequired
fileMessageobject
textMessageobject
audioMessageobject
pictureMessageobject
videoMessageobject
locationMessageobject
contactMessageobject
componentsTemplateComponent[]required
parametersComponentParameter[]required
emailMessageobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentobjectrequired
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentMessageContentCard[]required
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
customobject
Unauthorized
Not Found
{
"error": {
"code": "string",
"message": "string",
"description": "string",
"items": [
{
"name": "string",
"message": "string",
"description": "string"
}
]
}
}Schema
errorobject
itemsobject[]
Notifications
Use GET /v1/updates to get the latest notifications for the messages sent from your account. You can filter by message ID (msgid) or by event type (event), and order the results ascending or descending by date.
Event types: message, isTyping, messageStatus, response, subscribed, unsubscribed, fallback.
Message statuses: pending, dispatched, sent, delivered, displayed, undelivered, rejected, redispatched, buffered, deleted, failed.
| event | Description |
|---|---|
message | Inbound message from an end user. |
isTyping | The end user is typing. |
messageStatus | Status update / DLR of an outbound message. |
response | The end user replied to a suggestion (postback). |
subscribed | The end user subscribed to the sender. |
unsubscribed | The end user unsubscribed from the sender. |
fallback | A fallback was triggered; see fallbackMsgId. |
Instead of polling, you can register a webhook URL; the platform pushes the same payloads to it as events happen. Each webhook call includes the X-Msg-Api-Signature header — a Base64-encoded SHA-512 hash of the payload and your verify token — so you can confirm the notification came from the platform.
Get list of latest notifications for every message send from the account
Get list of latest notifications for every message send from the account.
Request
Query Parameters
asc], [desc]msgid).message], [isTyping], [messageStatus], [response], [subscribed], [unsubscribed], [fallback]Responses
The response contains the list of messages received from the receiver, including events.
{
"data": [
{
"msgId": "string",
"receiver": "string",
"sender": "string",
"channel": "rbm",
"messageBody": {
"textMessage": {
"content": "string"
}
},
"messageStatus": "pending",
"error": {
"code": "string",
"message": "string",
"description": "string"
},
"fallbackMsgId": "string",
"smsParts": {
"total": 0,
"receiveddlrs": 0
},
"contact": {
"firstName": "string",
"lastName": "string",
"name": "string",
"avatarUrl": "string",
"country": "string",
"city": "string",
"address": "string",
"language": "string",
"phone": "string",
"email": "string",
"birthday": "string"
},
"createdAt": "2026-11-09T14:02:11Z",
"event": "message"
}
]
}Schema
dataNotification[]
rbm], [sms], [telegram], [whatsApp], [email], [instagram], [facebook]rbm is RCS Business Messaging).messageBodyoneOf
fileMessageobject
textMessageobject
audioMessageobject
pictureMessageobject
videoMessageobject
locationMessageobject
contactMessageobject
componentsTemplateComponent[]required
parametersComponentParameter[]required
emailMessageobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentobjectrequired
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentMessageContentCard[]required
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
pending], [dispatched], [sent], [rejected], [failed], [redispatched], [delivered], [displayed], [undelivered], [buffered], [deleted]errorobject
smsPartsobject
receiveddlrs is the JSON field name in API responses).contactobject
message], [isTyping], [messageStatus], [response], [subscribed], [unsubscribed], [fallback]Unauthorized
Not Found
{
"error": {
"code": "string",
"message": "string",
"description": "string",
"items": [
{
"name": "string",
"message": "string",
"description": "string"
}
]
}
}Schema
errorobject
itemsobject[]
Receive message update notifications (customer webhook)
Webhook endpoint that receives notifications forwarded by our platform. This endpoint must be configured by the customer on their platform and is triggered when an inbound message is received, or on a DLR or another event. Each request contains X-Msg-Api-Signature (base64(SHA512(body + verifyToken))).
Request
Header Parameters
base64encode(sha512(payload + verifyToken)).{
"msgId": "string",
"receiver": "string",
"sender": "string",
"channel": "rbm",
"messageBody": {
"textMessage": {
"content": "string"
}
},
"messageStatus": "pending",
"error": {
"code": "string",
"message": "string",
"description": "string"
},
"fallbackMsgId": "string",
"smsParts": {
"total": 0,
"receiveddlrs": 0
},
"contact": {
"firstName": "string",
"lastName": "string",
"name": "string",
"avatarUrl": "string",
"country": "string",
"city": "string",
"address": "string",
"language": "string",
"phone": "string",
"email": "string",
"birthday": "string"
},
"createdAt": "2026-11-09T14:02:11Z",
"event": "message"
}Body
rbm], [sms], [telegram], [whatsApp], [email], [instagram], [facebook]rbm is RCS Business Messaging).messageBodyoneOf
fileMessageobject
textMessageobject
audioMessageobject
pictureMessageobject
videoMessageobject
locationMessageobject
contactMessageobject
componentsTemplateComponent[]required
parametersComponentParameter[]required
emailMessageobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentobjectrequired
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
layoutobject
HORIZONTAL], [VERTICAL]LEFT], [RIGHT]SMALL_WIDTH], [MEDIUM_WIDTH]contentMessageContentCard[]required
mediaobject
SHORT_HEIGHT], [MEDIUM_HEIGHT], [TALL_HEIGHT]suggestionsSuggestion[]required
replyWithobject
openUrlobject
dialNumberobject
composeMessageobject
showMapLocationobject
createCalendarEventobject
pending], [dispatched], [sent], [rejected], [failed], [redispatched], [delivered], [displayed], [undelivered], [buffered], [deleted]errorobject
smsPartsobject
receiveddlrs is the JSON field name in API responses).contactobject
message], [isTyping], [messageStatus], [response], [subscribed], [unsubscribed], [fallback]Responses
Successful operation
Internal problems, retry again
Senders
Use GET /v1/senders to get the list of senders available to your account. You can filter by one or more channel types with the optional channelType query parameter, as a comma-separated list such as rbm,sms,whatsApp. If omitted, the endpoint returns the senders configured for all channels.
Depending on the channel, a sender is an RBM agent ID, an SMS short code or alphanumeric sender ID, a Telegram bot username or a WhatsApp phone number.
Get list of senders filtered by one or more channel types
Get list of senders filtered by one or more channel types.
Request
Query Parameters
channelType=rbm,sms,whatsApp). Omit to return senders for all channels.Example: rbm,sms,whatsApp
Responses
List of senders for the specified channel type.
{
"data": [
{
"id": 101,
"senderId": "SMSes_Agent",
"msisdn": "",
"name": "SMS.es",
"url": "",
"channel": "rbm"
},
{
"id": 102,
"senderId": "SMSes",
"msisdn": "",
"name": "SMS.es",
"url": "",
"channel": "sms"
},
{
"id": 103,
"senderId": "34911222333",
"msisdn": "+34911222333",
"name": "SMS.es",
"url": "",
"channel": "whatsApp"
}
]
}Schema
dataSender[]
rbm], [sms], [telegram], [whatsApp], [email], [instagram], [facebook]rbm is RCS Business Messaging).Invalid channel type
{
"error": {
"code": "string",
"message": "string",
"description": "string",
"items": [
{
"name": "string",
"message": "string",
"description": "string"
}
]
}
}Schema
errorobject
itemsobject[]
Unauthorized
Not Found
{
"error": {
"code": "string",
"message": "string",
"description": "string",
"items": [
{
"name": "string",
"message": "string",
"description": "string"
}
]
}
}Schema
errorobject
itemsobject[]
Inbound and Outbound messages
Use GET /v1/files/{ID} to download a media file sent by a mobile subscriber — a picture, audio, video or other attachment from an inbound message. The ID is the file identifier taken from the file URL of the inbound message.
The request requires the X-API-Key header. The response is passed through from the channel provider, and its Content-Type header reflects the media type when known.
Download a media file delivered by inbound message
Streams the MO file referenced by the file ID (e.g. from a file URL in an inbound message). Requires X-API-Key. The response is proxied from the channel provider; the Content-Type header reflects the media type when known.
Request
Path Parameters
Responses
File bytes (binary stream).
Schema
*/* — string <binary>Unauthorized
File not found
{
"error": {
"code": "string",
"message": "string",
"description": "string",
"items": [
{
"name": "string",
"message": "string",
"description": "string"
}
]
}
}