Unifier API

1. Introduction

The Unifier API is HORISEN's HTTP API for omnichannel messaging. Use it to send messages (including fallback routes), retrieve notifications for DLRs, inbound messages or download inbound media and other events.

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 Notification events (signed with X-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 client_secret on the customer connection. Some deployments also enforce IP whitelist on the connection.

Definitions:

A message request is an HTTP request sent from the customer to the Unifier API to send a message to the intended recipient's device, optionally including fallback messages.
An outbound message is a message that is delivered from our service to telecom networks or messaging channels (e.g. Google RBM, Whatsapp, etc.) to terminate at the intended recipient's device.
An inbound message is a message that was initiated and sent by a mobile subscriber (end user) through their device, routed via the SMS telecom network or messaging channel such as Google RBM, Whatsapp, etc., to the designated sender of the message request.
A DLR is a status sent back by the telecom network to confirm whether a previously submitted SMS message has been successfully delivered to the intended recipient's handset, or to report a failure/error if delivery was unsuccessful.
A notification is an information of an inbound message, a DLR or an event of a fallback.

2. Methods Overview

2.1 Message Request

2.2 Inbound and Outbound Message Retrievers

2.3 Notifications

2.4 Inbound and Outbound Messages

2.5 Webhooks

3. Methods Details

3.1 Message Request

POST/v1/messages

Request to send a message that may include fallback messages to a receiver.Up

Method Overview

The method requests to send a message that may include fallback messages to a receiver.

URL Parameters

No parameters.

Request Body

The request body for sending the messages. See MessageRequest.

{
  "message": {
    "msgId": "string",
    "sender": "string",
    "receiver": "string",
    "channel": "string",
    "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": "string",
      "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": {}
    }
  ]
}

Responses

Code	Description	Links
200	Successful operation (message accepted for processing; implementation returns HTTP 200). See MessageRequestResponse.	No links.
400	Invalid input. See FailureResponse.	No links.
401	Unauthorized.	No links.

Success Response 200: Successful operation

{
  "message": {
    "msgId": "string",
    "channel": "rbm",
    "hasFallbacks": true,
    "smsParts": {
      "total": 0
    }
  }
}

Bad Request 400: Invalid input

{
  "error": {
    "code": "string",
    "message": "string",
    "description": "string",
    "items": [
      {
        "name": "string",
        "message": "string",
        "description": "string"
      }
    ]
  }
}

3.2 Inbound and Outbound Message Retrievers

GET/v1/messages/{msgId}

Gets the message based on the message's ID.Up

Method Overview

The method gets the message based on the message's ID.

URL Parameters

Name	Type	Description
msgId	string($uuid) (path)	Message ID.

Responses

Code	Description	Links
200	Message is returned. See IndividualMessage.	No links.
401	Unauthorized.	No links.
404	Not found. See FailureResponse.	No links.

Success Response 200: Message is returned

{
  "msgId": "string",
  "sender": "string",
  "receiver": "string",
  "channel": "string",
  "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": {}
}

Error Response 404: Not found

{
  "error": {
    "code": "string",
    "message": "string",
    "description": "string",
    "items": [
      {
        "name": "string",
        "message": "string",
        "description": "string"
      }
    ]
  }
}

3.3 Notifications

GET/v1/updates

Gets a list of latest notifications for every message sent from the account.Up

Method Overview

The method gets a list of latest notifications for every message sent from the account.

URL Parameters

Name	Type	Description
order	string (query)	Order the list based on date.
msgid	string (query)	Return all notifications for a specific message ID ( the query name is lowercase `msgid`).
event	string (query)	Return all notifications for a specific event. See EventType.

Responses

Code	Description	Links
200	The response contains a list of messages received from receiver, including events. See CollectionOfNotifications.	No links.
401	Unauthorized.	No links.
404	Not found. See FailureResponse.	No links.

Success Response 200: list of messages received from receiver, including events

{
  "data": [
    {
      "msgId": "string",
      "receiver": "string",
      "sender": "string",
      "channel": "rbm",
      "messageBody": {
        "fileMessage": {
          "name": "string",
          "url": "string",
          "fileType": "string",
          "mimeType": "string",
          "size": 0,
          "playingLength": "string",
          "thumbnailName": "string",
          "thumbnailUrl": "string",
          "thumbnailMimeType": "string",
          "thumbnailSize": 0
        }
      },
      "messageStatus": "pending",
      "error": {
        "code": "string",
        "message": "string",
        "description": "string"
      },
      "fallbackMsgId": "string",
      "smsParts": {
        "total": 0,
        "receiveddlrs": 0
      },
      "createdAt": "2026-04-08T13:11:15.315Z",
      "event": "message"
    }
  ]
}

Error Response 404: Not found

{
  "error": {
    "code": "string",
    "message": "string",
    "description": "string",
    "items": [
      {
        "name": "string",
        "message": "string",
        "description": "string"
      }
    ]
  }
}

3.4 Inbound and Outbound Messages

GET/v1/files/{ID}

Downloads a media file delivered by inbound message.Up

Method Overview

Streams the MO file referenced by the ID of the file (e.g. from a file URL in an inbound message).
Requires X-API-Key. Response is proxied from the provided channel.
The Content-Type header reflects the media type when it is known.

URL Parameters

Name	Type	Description
ID	string($uuid) (path) (required)	File identifier in UUID format.

Responses

Code	Description	Links
200	File bytes (binary stream).	No links.
401	Unauthorized.	No links.
404	File not found. See FailureResponse.	No links.

Error Response 404: Not found

{
  "error": {
    "code": "string",
    "message": "string",
    "description": "string",
    "items": [
      {
        "name": "string",
        "message": "string",
        "description": "string"
      }
    ]
  }
}

3.5 Webhooks

POST/webhook/notifications

Receives message update notifications (customer webhook).Up

Method Overview

Webhook endpoint that receives notifications forwarded by our platform. This endpoint must be configured by the customer on their platform and will be triggered when an inbound message is received, or DLR or another event.
Each request will contain X-Msg-Api-Signature (base64(SHA512(body + verifyToken))).

Parameters

Name	Type	Description
X-Msg-Api-Signature	string (header)	The signature for each request and contains the base64encode(sha512(payload, verifyToken)).

Request Body

The request body for sending the notification. See Notification.

{
  "msgId": "string",
  "receiver": "string",
  "sender": "string",
  "channel": "rbm",
  "messageBody": {
    "fileMessage": {
      "name": "string",
      "url": "string",
      "fileType": "string",
      "mimeType": "string",
      "size": 0,
      "playingLength": "string",
      "thumbnailName": "string",
      "thumbnailUrl": "string",
      "thumbnailMimeType": "string",
      "thumbnailSize": 0
    }
  },
  "messageStatus": "pending",
  "error": {
    "code": "string",
    "message": "string",
    "description": "string"
  },
  "fallbackMsgId": "string",
  "smsParts": {
    "total": 0,
    "receiveddlrs": 0
  },
  "createdAt": "2026-04-08T11:09:37.090Z",
  "event": "message"
}

Responses

Code	Description	Links
200	Successful operation.	No links.
500	Internal problems, retry again.	No links.

4. Data Models

Data Models define the structure of a JSON document and describe the data related to the Unifier API.

4.1 MessageRequest

Name	Type	Description
message (required)	object	See IndividualMessage.
fallback	array	Array of IndividualMessage.

4.2 IndividualMessage

Name	Type	Description
msgId	string	Message ID.
sender (required)	string	Based on the channel: - for RBM is Agent ID - for SMS is Short Code and alphanumeric sender IDs - for Telegram is Bot's username - for Email is an email address - for Instagram is Instagram's account ID.
receiver (required)	string	Based on the channel: - for RBM, WhatsApp and SMS, it is a phone number - for Telegram it is the numerical user's ID, not the username
channel (required)	string	Channel identifier as returned by the API. Possible values: "rbm", "sms", "telegram", "whatsapp". Note: `rbm` is RCS Business Messaging.
validityPeriod	number	Validity period.
connectionCName	string	Only needed for SMS messages that don't have a default Omnichannel_CName in whitelist.
dcs	string	Only needed for SMS messages and if the channel of the sender is in "auto". Possible values: "gsm", "unicode" and "auto".
body (required)	object	See MessageBody.
custom	object	Optional key-value bag for client-specific metadata.

4.3 MessageBody

Name	Type	Description
MessageBody	object	Message body can be one of: FileMessage, TextMessage, AudioMessage, PictureMessage, VideoMessage, LocationMessage, ContactMessage, TemplateMessage.

4.4 ComponentParameterCurrency

Name	Type	Description
code (required)	string	Code.
amount1000 (required)	integer	Amount.
fallbackValue	string	Fallback value.

4.5 ComponentParameterDateTime

Name	Type	Description
fallbackValue (required)	string	Fallback value.

4.6 ComponentParameterDocument

Name	Type	Description
link (required)	string	Link to a document.

4.7 ComponentParameterImage

Name	Type	Description
link (required)	string	Link to an image.

4.8 ComponentParameterVideo

Name	Type	Description
link (required)	string	Link to a video.

4.9 ComponentParameter

Name	Type	Description
ComponentParameterCurrency	object	See ComponentParameterCurrency.
ComponentParameterDateTime	object	See ComponentParameterDateTime.
ComponentParameterDocument	object	See ComponentParameterDocument.
ComponentParameterImage	object	See ComponentParameterImage.
ComponentParameterVideo	object	See ComponentParameterVideo.

4.10 TemplateComponent

Name	Type	Description
type (required)	string	Type.
subType	string	Subtype.
index (required)	integer	Index.
parameters (required)	array	Array of ComponentParameter.

4.11 TemplateMessage

Name	Type	Description
name (required)	string	Name.
languageCode (required)	string	Language code.
components (required)	array	Array of TemplateComponent.

4.12 ContactMessage

Name	Type	Description
name	string	Contact name.
email	string	Contact Email.
address	string	Contact address.
phone	string	Contact phone.
firstName	string	Contact first name.
lastName	string	Contact last name.
country	string	Contact country.
language	string	Contact language.

4.13 LocationMessage

Name	Type	Description
latitude	number	Location latitude
longitude	number	Location longitude
text	string	Message text.
url	string	Location URL.

4.14 VideoMessage

Name	Type	Description
name	string	Name.
url	string	Message URL.
mimeType	string	MIME type.
size	integer	Video message size.
playingLength	integer	Playing length.
thumbnailName	string	Thumbnail name.
thumbnailUrl	string	Thumbnail URL.
thumbnailMimeType	string	Thumbnail MIME type.
thumbnailSize	integer	Thumbnail size.

4.15 PictureMessage

Name	Type	Description
name	string	Name.
url	string	Message URL.
mimeType	string	MIME type.
size	integer	Picture message size.
thumbnailName	string	Thumbnail name.
thumbnailUrl	string	Thumbnail URL.
thumbnailMimeType	string	Thumbnail MIME type.
thumbnailSize	integer	Thumbnail size.

4.16 AudioMessage

Name	Type	Description
name	string	Name.
url	string	Message URL.
mimeType	string	MIME type.
size	integer	Audio message size.
playingLength	integer	Playing length.

4.17 TextMessage

Name	Type	Description
content	string	Content.

4.18 FileMessage

Name	Type	Description
name	string	Name.
url	string	Message URL.
fileType	string	File type.
mimeType	string	MIME type.
size	integer	Video message size.
playingLength	integer	Playing length.
thumbnailName	string	Thumbnail name.
thumbnailUrl	string	Thumbnail URL.
thumbnailMimeType	string	Thumbnail MIME type.
thumbnailSize	integer	Thumbnail size.

4.19 MessageRequestResponse

Name	Type	Description
message	object	Message. See Message.

4.20 Message

Name	Type	Description
msgId	string	Message ID.
channel	string	Channel identifier as returned by the API. Possible values: "rbm", "sms", "telegram", "whatsapp". Note: `rbm` is RCS Business Messaging.
hasFallbacks	boolean	If it has fallbacks.
smsParts	object	SMS part / DLR counters (`receiveddlrs` is the JSON field name in API responses). See SmsPartsDLR.

4.21 SmsPartsDLR

Name	Type	Description
total	number	Total number of SMS parts.
receiveddlrs	number	Number of received DLRs.

4.22 Error

Name	Type	Description
code	string	Error code.
message	string	Error message.
description	string	Error description.

4.23 FailureResponse

Name	Type	Description
Error	object	See Error.

4.24 EventType

Name	Type	Description
EventType	string	Update event type (values emitted by the platform for notifications). Possible values: message, isTyping, messageStatus, response, subscribed, unsubscribed, fallback.

4.25 Notification

Name	Type	Description
msgId (required)	string	Message ID.
receiver (required)	string	Receiver.
sender (required)	string	Sender.
channel (required)	string	Channel identifier as returned by the API. Possible values: "rbm", "sms", "telegram", "whatsapp". Note: `rbm` is RCS Business Messaging.
messageBody	object	See MessageBody.
messageStatus	string	Message status. Possible values: pending, dispatched, sent, rejected, failed, redispatched, delivered, displayed, undelivered, buffered, deleted.
error	object	Present when a message failed or triggered a fallback. See Error.
fallbackMsgId	string	On fallback events, the identifier of the next message that will be sent.
smsParts	object	See SmsPartsDLR.
createdAt (required)	string($date‑time)	Created at specific date and time.
event (required)	object	See EventType.

4.26 CollectionOfNotifications

Name	Type	Description
data	array	Array of Notification.

Unifier API

1. Introduction

2. Methods Overview

2.1 Message Request

2.2 Inbound and Outbound Message Retrievers

2.3 Notifications

2.4 Inbound and Outbound Messages

2.5 Webhooks

3. Methods Details

3.1 Message Request

Method Overview

URL Parameters

Request Body

Responses

Success Response 200: Successful operation

Bad Request 400: Invalid input

3.2 Inbound and Outbound Message Retrievers

Method Overview

URL Parameters

Responses

Success Response 200: Message is returned

Error Response 404: Not found

3.3 Notifications

Method Overview

URL Parameters

Responses

Success Response 200: list of messages received from receiver, including events

Error Response 404: Not found

3.4 Inbound and Outbound Messages

Method Overview

URL Parameters

Responses

Error Response 404: Not found

3.5 Webhooks

Method Overview

Parameters

Request Body

Responses

4. Data Models

4.1 MessageRequest

4.2 IndividualMessage

4.3 MessageBody

4.4 ComponentParameterCurrency

4.5 ComponentParameterDateTime

4.6 ComponentParameterDocument

4.7 ComponentParameterImage

4.8 ComponentParameterVideo

4.9 ComponentParameter

4.10 TemplateComponent

4.11 TemplateMessage

4.12 ContactMessage

4.13 LocationMessage

4.14 VideoMessage

4.15 PictureMessage

4.16 AudioMessage

4.17 TextMessage

4.18 FileMessage

4.19 MessageRequestResponse

4.20 Message

4.21 SmsPartsDLR

4.22 Error

4.23 FailureResponse

4.24 EventType

4.25 Notification

4.26 CollectionOfNotifications

Information about cookies