SMS REST API

The REST transport addresses a module method by HTTP method and path. It is the entry point for the CRM interface, the backoffice, mobile applications, and provider delivery reports.

The same methods are available over TCP by command name — see TCP API. Request fields and results are identical; only the addressing differs.

Base URL

https://{broker_domain}/sms/...

All paths of the module live under sms/. The prefix is what keeps the module apart from the other modules sharing the same host — including the public delivery-report path.

Authorization

Every endpoint except the public webhook requires a manager JWT:

Authorization: <JWT_TOKEN>

The platform resolves the token and passes the identity to the module. The brand and the author of a record always come from the token, never from the request body.

POST sms/handleWebhooks/:uuid is public — it is called by the SMS provider. Its protection is the unguessable uuid plus the signature check of the webhook secret.

Endpoints

Method	Endpoint	Access
SmsSendMessage	POST sms/message	admin, leader, manager
SmsSendFromTemplate	POST sms/message/fromTemplate	admin, leader, manager
SmsSendBulk	POST sms/message/bulk	admin, leader
SmsResendMessage	POST sms/message/resend	admin, leader, manager
SmsCancelMessage	POST sms/message/cancel	admin, leader, manager
SmsPreviewMessage	POST sms/message/preview	admin, leader, manager
SmsGetMessage	GET sms/message/:id	admin, leader, manager
SmsGetMessages	GET sms/messages/list	admin, leader, manager
SmsGetStats	GET sms/stats	admin, leader
SmsAddTemplate	POST sms/template	admin
SmsUpdateTemplate	PUT sms/template	admin
SmsCloneTemplate	POST sms/template/clone	admin
SmsDeleteTemplate	DELETE sms/template	admin
SmsGetTemplates	GET sms/templates/list	admin, leader, manager
SmsAddTrigger	POST sms/trigger	admin
SmsUpdateTrigger	PUT sms/trigger	admin
SmsDeleteTrigger	DELETE sms/trigger	admin
SmsFireTrigger	POST sms/trigger/fire	admin
SmsGetTriggers	GET sms/triggers/list	admin
SmsGetTriggerSubscriptions	GET sms/triggers/subscriptions	admin
SmsGetProviderAdapters	GET sms/providers/adapters	admin, provider
SmsAddProvider	POST sms/provider	provider
SmsUpdateProvider	PUT sms/provider	provider
SmsDeleteProvider	DELETE sms/provider	provider
SmsGetProviders	GET sms/providers/list	admin, provider
SmsAddProfile	POST sms/providerProfile	admin
SmsUpdateProfile	PUT sms/providerProfile	admin
SmsDeleteProfile	DELETE sms/providerProfile	admin
SmsGetProfiles	GET sms/providerProfiles/list	admin
SmsGetMyProfiles	GET sms/providerProfile/available/me	admin, leader, manager
SmsGetProfileBalance	GET sms/providerProfiles/balance	admin
SmsAddAgent	POST sms/agent	admin
SmsUpdateAgent	PUT sms/agent	admin
SmsDeleteAgent	DELETE sms/agent	admin
SmsGetAgents	GET sms/agents/list	admin
SmsAddBlacklistPhone	POST sms/blacklist	admin, leader, manager
SmsImportBlacklistPhones	POST sms/blacklist/import	admin
SmsDeleteBlacklistPhone	DELETE sms/blacklist	admin
SmsCheckBlacklistPhone	GET sms/blacklist/check	admin, leader, manager
SmsGetBlacklist	GET sms/blacklist/list	admin, leader
SmsAddSendWindow	POST sms/sendWindow	admin
SmsUpdateSendWindow	PUT sms/sendWindow	admin
SmsDeleteSendWindow	DELETE sms/sendWindow	admin
SmsCheckSendWindow	GET sms/sendWindow/check	admin, leader, manager
SmsGetSendWindows	GET sms/sendWindows/list	admin, leader
SmsAddWebhook	POST sms/webhook	admin
SmsUpdateWebhook	PUT sms/webhook	admin
SmsDeleteWebhook	DELETE sms/webhook	admin
SmsGetWebhooks	GET sms/webhooks/list	admin
SmsGetWebhookEvents	GET sms/webhookEvents/list	admin
SmsHandleWebhook	POST sms/handleWebhooks/:uuid	public
SmsPing	GET sms/ping	admin
SmsHealth	GET sms/health	admin

SmsGetLastMessagesByParents has no REST route: it is an internal method for CRM lists and is available over the bus only.

List queries

Every */list method accepts the same query contract:

Field	Type	Description
limit	int	Page size, 1..1000, default 100
offset	int	Rows to skip
orderBy	array	["id", "DESC"]
groupBy	array	Grouping, including date grouping such as DAY({field})
count, sum, min, max, avg	array	Aggregates over the listed fields
where, whereIn, whereLike, whereBetween, …	object	Filters, including grouped orWhere

Filter syntax is shared with the rest of the platform and is described in Table filter syntax.

The response is the requested page in rows, plus one key per requested aggregate:

{
  "rows": [],
  "count": [ { "id": 42 } ]
}

A row count is an aggregate, not a default: ask for it with count: ["id"] when the UI needs paging. For spend and delivery reports use SmsGetStats — it aggregates on the server instead of paging raw rows.

Status codes

Code	Meaning
200	Method succeeded
400	Validation failed, or the request contradicts itself
401	Missing or invalid JWT
403	The manager may not touch this record, or the number is blacklisted
404	Message, profile, provider, template, or adapter not found
409	Sending is not allowed: opt-out, destination, duplicate, message too long
429	Provider rate limit
500	Module or storage error
502	Module is unreachable on the bus
503	Provider is unavailable

On success the body is the method payload itself — there is no wrapper object to unwrap:

{ "smsId": 812, "status": "PENDING", "parts": 1 }

On failure the HTTP status carries the outcome and the body is the message:

HTTP/1.1 409 Conflict

"Message is 4 segment(s) long, limit is 3"

Branch on the status code and show the message to the operator. The error type listed on each method page names the same condition and appears in the module log; at the HTTP boundary the status code is the machine-readable part.