Help Center GMS API Compatibility

GMS API Compatibility

SMSBAT supports a compatibility layer with the GMS API. This allows you to migrate your existing integrations designed for GMS directly to SMSBAT without having to modify your message routing schemas, payload structures, or callback listeners.

Connection Settings

To route requests through SMSBAT, update the base URL and authentication credentials in your integration:

Base URL: https://restapi.smsbat.com
Endpoint: POST /api/GMSMessage/send_message
Request Format: application/json
Authentication: HTTP Basic Authentication (uses your SMSBAT API credentials)

Request Parameters

The GMS compatibility API accepts a JSON object with the following top-level parameters:

Parameter	Type	Required	Description
`phone_number`	string	Yes	Recipient phone number in international format (e.g., `380501234567`).
`tag`	string	Yes	Registered sender name / alpha name.
`channels`	array	Yes	List of channels to try, in priority order. Supported values: `viber`, `sms`, `push`. E.g., `["viber", "sms"]`.
`channel_options`	object	Yes	Map containing options for each active channel (see below).
`extra_id`	string	No	Your internal customer-side message ID.
`callback_url`	string	No	Endpoint URL on your system to receive delivery status callbacks.
`division_code`	string	No	Optional division code identifier (defaults to `main`).

Channel Options Settings

The channel_options object contains channel-specific configurations.

Used when viber is listed in the channels array.

Parameter	Type	Required	Description
`text`	string	Yes	Message body text.
`ttl`	integer	Yes	Time-To-Live in seconds.
`img`	string	No	Public HTTPS URL of the image to display.
`caption`	string	No	Button text label.
`action`	string	No	Destination URL when button is clicked.
`survey_options`	array	No	Array of strings (2 to 5 items) to display as survey options.
`carousel_items`	array	No	Array of slide objects to display as a Viber carousel (see structure in tab).

Viber Request Example:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

Enables Viber messaging with an automatic SMS fallback if Viber delivery fails within the TTL.

Fallback Request Example:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Used when sms is listed in the channels array.

Parameter	Type	Required	Description
`text`	string	Yes	Message body text.
`alpha_name`	string	Yes	Sender alpha name.
`ttl`	integer	Yes	Time-To-Live in seconds.
`ctr`	boolean	No	Enable CTR click tracking on links in text (`true`/`false`).

SMS Request Example:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Used to create Viber polls and surveys.

Warning

Viber survey configuration must have between 2 and 5 options inside survey_options.

Survey Request Example:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Used to send swipeable image slide cards. Each slide supports image, title, and buttons.

Carousel Request Example:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Choose an offer",
      "ttl": 60,
      "carousel_items": [
        {
          "title": "Offer 1",
          "image_url": "https://www.example.com/offer-1.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-1",
          "secondary_label": "More",
          "secondary_url": "https://www.example.com/offers"
        },
        {
          "title": "Offer 2",
          "image_url": "https://www.example.com/offer-2.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-2"
        }
      ]
    }
  }
}

Used when push is listed in the channels array.

Parameter	Type	Required	Description
`title`	string	Yes	Title text of the push notification.
`text`	string	Yes	Message body text.
`ttl`	integer	Yes	Time-To-Live in seconds.
`img`	string	No	Public HTTPS URL of the image to display.
`caption`	string	No	Button text label.
`action`	string	No	Destination URL when button is clicked.
`ctr`	boolean	No	Enable click tracking.

Push Request Example:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Response Format

The endpoint returns responses in JSON format with an HTTP 200 OK status code.

Successful Response

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Error Responses

If validation or processing fails, an error response with a non-null ErrorCode and detailed ErrorText will be returned.

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Callback Delivery Format

If callback_url was specified in the request, SMSBAT sends delivery status updates as a JSON POST payload to your endpoint.

Callback Request Example

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Callback Fields Description

Field	Type	Description
`number`	string	Recipient phone number.
`time`	number	Event timestamp in Unix milliseconds.
`status`	number	Simplified status identifier (see Status code table).
`substatus`	number	Detailed status identifier (see Substatus code table).
`hyber_status`	number	Detailed SMSBAT internal status code (see Hyber Status table).
`message_id`	string	SMSBAT message ID (GUID) generated on sending.
`extra_id`	string	Customer-side ID provided in the original request.
`sent_via`	string	Channel that processed the message: `viber`, `sms`, or `rcs`.
`matching_template_id`	number	Viber template match status (where applicable).

Status Mappings

1. Simplified Status (`status`)

Code	Meaning
`1`	Message accepted or being delivered.
`2`	Message delivered.
`3`	Processing or delivery error.

2. Detailed Status (`substatus`)

Code	Meaning
`12`	Accepted for processing.
`23`	Delivered.
`24`	Seen/read.
`35`	Not delivered within TTL (Expired).
`36`	Delivery error.

3. Channel Type (`sent_via`)

Channel	Description
`viber`	Status produced by Viber channel.
`sms`	Status produced by SMS channel.
`rcs`	Status produced by RCS channel.

4. Detailed SMSBAT Status (`hyber_status`)

Code	Channel	Status	Substatus	Meaning
23033	`viber`	`2`	`23`	Viber message delivered.
24013	`viber`	`2`	`24`	Viber message read by recipient (Seen).
36013	`viber`	`3`	`36`	Viber internal error.
36023	`viber`	`3`	`36`	Invalid or unavailable Viber service ID.
36033	`viber`	`3`	`36`	Invalid Viber payload data.
36037	`viber`	`3`	`36`	Viber image URL too long.
36038	`viber`	`3`	`36`	Invalid Viber image URL.
36039	`viber`	`3`	`36`	Viber text too long.
36044	`viber`	`3`	`36`	Empty Viber text.
36053	`viber`	`3`	`36`	Unsupported Viber message type.
36063	`viber`	`3`	`36`	Invalid Viber parameters.
36073	`viber`	`3`	`36`	Viber provider timeout.
36083	`viber`	`3`	`36`	Viber sender blocked by the recipient.
36093	`viber`	`3`	`36`	Recipient is not registered as a Viber user.
36103	`viber`	`3`	`36`	No Android/iOS device with Viber support found.
36113	`viber`	`3`	`36`	Unauthorized IP address for Viber sending.
36123	`viber`	`3`	`36`	Duplicate Viber message detected.
36143	`viber`	`3`	`36`	Viber billing error.
36153	`viber`	`3`	`36`	Message blocked by platform blacklist.
36163	`viber`	`3`	`36`	Viber platform internal processing error.
36173	`viber`	`3`	`36`	Wrong or missing Viber label.
36183	`viber`	`3`	`36`	Invalid Viber TTL value.
12011	`sms` / `rcs`	`1`	`12`	SMS/RCS accepted.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS enroute.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS delivered.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS expired (not delivered within TTL).
36021	`sms` / `rcs`	`3`	`36`	SMS/RCS message deleted.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS cannot be delivered.
36041	`sms` / `rcs`	`3`	`36`	Unknown SMS/RCS delivery status.
36051	`sms` / `rcs`	`3`	`36`	SMS/RCS message rejected.

Search Results

GMS API Compatibility

Connection Settings

Request Parameters

Channel Options Settings

Response Format

Successful Response

Error Responses

Callback Delivery Format

Callback Request Example

Callback Fields Description

Status Mappings

1. Simplified Status (status)

2. Detailed Status (substatus)

3. Channel Type (sent_via)

4. Detailed SMSBAT Status (hyber_status)

1. Simplified Status (`status`)

2. Detailed Status (`substatus`)

3. Channel Type (`sent_via`)

4. Detailed SMSBAT Status (`hyber_status`)