Skip to content

SmsSendMessage

POST sms/message

Queues a text message. The method answers as soon as the message is accepted into the queue: attempts, backoff and failover to a backup profile happen afterwards, without the caller waiting for the operator.

If profileId is omitted, the provider is chosen by routing — profiles of the brand allowed to send to that destination, ordered by routingPriority. An explicitly chosen profile is pinned to the message and is not replaced on retries.

Access Control

Allowed roles: admin, leader, manager. The message is created under the brand of the caller, and managerId comes from the session.

Request

POST https://{broker_domain}/sms/message
{
  "sendToParentType": "CUSTOMER",
  "sendToParentId": 140,
  "phone": "+380951234567",
  "message": "Your code is 4821",
  "kind": "TRANSACTIONAL",
  "idempotencyKey": "login-code-140-1755000000"
}

{
  "command": "SmsSendMessage",
  "extID": "1",
  "data": {
    "sendToParentType": "CUSTOMER",
    "sendToParentId": 140,
    "phone": "+380951234567",
    "message": "Your code is 4821",
    "kind": "TRANSACTIONAL",
    "idempotencyKey": "login-code-140-1755000000"
  }
}

const res = await platform.SmsSendMessage({
  sendToParentType: "CUSTOMER",
  sendToParentId: 140,
  phone: "+380951234567",
  message: "Your code is 4821",
  kind: "TRANSACTIONAL",
  idempotencyKey: "login-code-140-1755000000"
});

Request Data

Field Type Required Description
sendToParentType enum Yes CUSTOMER, MANAGER, or LEAD — what the number belongs to
sendToParentId int Yes Id of the customer, lead, or manager
phone string Yes Destination number in any human format; normalized and validated against the numbering plan
message string Yes Message text, 1..2000 characters
profileId int No Explicit provider profile. Omit to let routing choose
agentId int No Explicit agent link for INDIVIDUAL profiles
senderId string No Sender name or number; falls back to the profile default
kind enum No TRANSACTIONAL ignores send windows and marketing opt-outs; MARKETING is the default
sendAt string No Defer sending: ISO 8601 or YYYY-MM-DD HH:mm:ss, not further than [sms] maxScheduleDays
idempotencyKey string No Repeating a request with the same key returns the same message instead of sending a second one
truncate bool No Truncate the text to [sms] maxParts instead of rejecting it with MESSAGE_TOO_LONG

Behavior

  • The text is measured before sending: encoding is detected (GSM-7 or UCS-2) and the length is reported in segments, because the operator bills per segment, not per message. One Cyrillic character turns the whole message into UCS-2 and halves the segment size.
  • Checks that can reject the message for free run before the provider is contacted: number, blacklist and opt-out, duplicate window, segment limit, send window.
  • scheduleReason explains why a message is still waiting: IMMEDIATE, SEND_WINDOW (the local window of the recipient is closed), or SCHEDULED (sendAt was set).
  • idempotent: true means the key matched an existing message and nothing new was queued — the safe answer for a retried request.

Response Data

{
  "smsId": 812,
  "status": "PENDING",
  "phone": "380951234567",
  "senderId": "ScaleTrade",
  "kind": "TRANSACTIONAL",
  "encoding": "GSM7",
  "parts": 1,
  "profileId": 3,
  "scheduledFor": null,
  "scheduleReason": "IMMEDIATE",
  "idempotent": false
}

Errors

Code Error Description
400 INVALID_PHONE Number cannot be parsed
400 IMPOSSIBLE_PHONE Number length does not match the numbering plan of its country
400 INVALID_SEND_AT sendAt is unparsable, in the past, or beyond maxScheduleDays
403 PHONE_BLACKLISTED Destination is blacklisted or opted out; the message says which, and an opt-out blocks only MARKETING
404 NOT_FOUND Profile, provider, template, or agent not found
409 MESSAGE_TOO_LONG Text exceeds [sms] maxParts segments and truncate was not set
409 DUPLICATE_MESSAGE The same text to the same number inside the duplicate window
409 COUNTRY_NOT_ALLOWED Destination is not allowed for the profile
409 NO_ROUTE_AVAILABLE No profile of the brand can send to this destination
500 MISSING_CREDENTIALS Profile credentials are incomplete for this adapter