Send an SMS

Sends one message to one subscriber of your service.

POST /api/sp/v1/dcb/sms

Request

Field	Type	Notes
msisdn	string	The recipient.
serviceId	integer	The service the message belongs to.
message	string	The text. Plain text, not hex.
spTransactionId	string	Yours, unique per attempt.

Response

{
  "requestId": "01JB2K9WQ4X7YH3M8N5P6R7T8V",
  "code": "OK",
  "data": { "messageId": "9183", "characters": 16 }
}

Field	Notes
messageId	Ours. Quote it in a support request about a specific message.
characters	How many characters we counted, as unicode characters rather than bytes.

Success means queued, not delivered. Delivery is a network event that happens after this call returns, and this endpoint does not report it.

characters is worth checking on your first integration. If it disagrees with your own count, the difference is almost always invisible characters or a different idea of what one character is - and since the length limit is enforced on our count, ours is the one that decides.

Legacy fields are refused, not ignored

msg and alphanumeric are prohibited. If you send either, the call fails validation.

This is deliberate. On the legacy platform msg carried hex-encoded text and alphanumeric set a sender ID. Accepting them silently would mean either double-encoding your message or quietly ignoring a sender you asked for. A loud refusal is better than either: see Migration from legacy.

The sender is derived from the service's short code and is not something a request can set.

Length, and why long messages are refused

Messages are not split. A message longer than the service permits returns CONTENT_TOO_LONG rather than arriving in pieces.

The limit is a single message part: 70 characters for Arabic or Kurdish, 160 for English, the boundary at which the operator would begin charging for a second part. Multi-part sending is not implemented yet, and refusing is deliberate rather than a gap we have not noticed: a message split across parts cannot currently be tracked or reconciled correctly.

Other limits

Every message counts against the subscriber's daily content budget for the service (CONTENT_LIMIT_EXCEEDED) and against the short code's own budget (SHORT_CODE_PART_LIMIT_REACHED). Services may also be configured to deliver only on certain days (CONTENT_NOT_ALLOWED_TODAY).