Callbacks
The gateway pushes events to your server by itself. The address is taken from the URL/Email for notification about SMS statuses field in your API settings, or from the notification address of your dedicated number.
This page describes the callbacks of the HTTP and XML API. If messages are sent through the JSON API with the hook parameter, the gateway sends the JSON webhook instead of these callbacks.
Incoming SMS
Sent when a subscriber sends an SMS to your dedicated number.
HTTP method: POST
Content-Type: multipart/form-data
| Parameter | Type | Description |
|---|---|---|
id | number | Message identifier assigned by the gateway |
message | string | Message text exactly as it was received from the subscriber |
phone | string | Phone number of the subscriber |
short_phone | string | Your dedicated number the message was sent to |
test | number | 1 — test message, it is not charged; 0 — real message |
timestamp | number | Unix time when the message was received |
password | string | md5(api_key). Use it to make sure the request comes from the gateway |
Request example
id=1234567&message=INFO%20123&phone=380501234567&short_phone=7060&test=0×tamp=1755772800&password=5f4dcc3b5aa765d61d8327deb882cf99
Response
The body of your response is sent back to the subscriber as a reply SMS.
| Your response | What the subscriber receives |
|---|---|
Body of 1–200 characters without an <html> tag | The body of your response |
Empty body, longer than 200 characters, or containing an <html> tag | The default reply configured for the dedicated number |
Timeouts: 5 seconds to connect, 20 seconds in total.
For an individual dedicated number a signature parameter can be agreed instead of password. It is calculated as sha1(values of all parameters sorted by parameter name and concatenated + api_key).
Viber 2 Way reply
Sent when a subscriber replies to your Viber message.
This callback is used only for messages that were not sent through the JSON API. For JSON API messages the reply is delivered in the replies array of the JSON webhook.
HTTP method: POST
Content-Type: application/x-www-form-urlencoded
| Parameter | Type | Description |
|---|---|---|
action | string | Always viber/2way |
sender | string | Sender name the subscriber replied to |
phone | string | Phone number of the subscriber |
message | string | Text of the reply |
datetime | string | Date and time of the reply Format: YYYY-MM-DDThh:mm:ss±hh:mm |
Request example
action=viber%2F2way&sender=SMSTest&phone=380501234567&message=Yes&datetime=2026-08-19T12%3A55%3A39%2B03%3A00
Response
You will receive code 200 in response. The response body is ignored.
The callback does not contain a message identifier — match the reply to the message by phone and sender. Media files attached to a reply are not delivered by this callback; they are available only in the JSON webhook.
Timeouts: 5 seconds to connect, 5 seconds in total. The request is sent once, without retries.
Delivery report by email
If the notification field contains an email address instead of a URL, the delivery report is not sent over HTTP — it is sent to that address as an email titled SMS delivery report.
The body of the letter contains the fields of the delivery report, one per line, in the format parameter: value.
| Parameter | Description |
|---|---|
id | Message identifier assigned by the gateway |
status | Message status code |
datetime | Date and time of the status change Format: YYYY-MM-DDThh:mm:ss±hh:mm |
parts | Number of parts the message was split into |
price | Cost of sending |
api_key | Your API key |
user_id | Unique message identifier in your system ⚠️ Present only if it was passed when sending |
Letter example
id: 1234567
status: 101
datetime: 2026-08-21T10:12:33+03:00
api_key: bb56a4369eb19***cfec6d1776bd25
parts: 1
price: 0.35
user_id: 100500
An email delivery report is not suitable for automatic processing — it has no signature and its delivery is not guaranteed. For integration use an HTTP address.