Skip to content
Developers

SMS messages

Send an SMS

Sends one text to one or more numbers (up to 100 per request).

POSThttps://api.falconzo.com/v1/sms/messages

Each number gets its own result. A number that can’t be texted is refused on its own, with an errorCode, and the others still go.

The whole request is charged when it is accepted. Messages refused later by the network are refunded.

Send an Idempotency-Key header so a request repeated after a timeout never sends twice.

Permission

The API key needs sms.send (send sms). Without it the answer is 403 MISSING_SCOPE.

Headers

Authorizationstringrequired
Bearer followed by your API key.
Idempotency-Keystring
Any unique text up to 200 characters, such as your order id and event. A repeat returns the first answer with "replayed": true and sends nothing.

Body

tostring | string[]required
Mobile numbers, local (0771234567) or international (+94771234567). Up to 100.
messagestring
The text, up to 1,600 characters. Required unless you send a template.
templateIdstring
An SMS template to send instead of message.
templateParamsobject
Values for the template’s placeholders, by name: { "name": "Nimal" }.
senderIdstring
The verified sender ID to use, by id or exact name (capitals count: FALCONZO and Falconzo are different sender IDs). Optional when you have only one.
clientReferencestring
Your own id, up to 100 characters. Returned with the message and in every webhook.

Errors

Besides UNAUTHORIZED, MISSING_SCOPE and RATE_LIMITED, which any endpoint can return:

  • QUEUE_FULL · 429Your organization already has 50,000 messages waiting to be sent. Wait for some to go out, then send again. Nothing was charged.
  • TEST_LIMIT_REACHED · 429Test keys have reached today’s 5,000 recipients. The limit resets at midnight UTC.
  • NOT_FOUND · 404The message or template doesn't exist, or belongs to the other mode (test or live).
  • IDEMPOTENCY_IN_PROGRESS · 409A request with the same Idempotency-Key is still running. Repeat it in a few seconds to get its result.
  • INSUFFICIENT_BALANCE · 402The balance doesn't cover the whole request. Nothing was sent.
  • SMS_NOT_ENABLED · 400SMS is not turned on for your account.
  • SMS_SUSPENDED · 400Sending is paused for your account. Contact support.
  • SENDER_ID_NOT_APPROVED · 400The sender ID isn't verified, or you have several and didn't choose one.
  • NO_PRICE · 400Prices aren't set up for your account yet. Contact support.
  • MESSAGE_TOO_LONG · 400The text is over 1,600 characters.
  • EMPTY_MESSAGE · 400The text (or the filled-in template) is empty.
  • INVALID_NUMBER · per numberNot a mobile number that can be texted. Only that number is refused.
  • UNSUPPORTED_COUNTRY · per numberA country we don't send to yet. Only that number is refused.
  • NOT_A_TEST_NUMBER · per numberIn test mode, the number isn't one of your verified test numbers.

All codes are listed in Errors and limits.