Skip to content
Developers

SMS

Sending SMS

Numbers, templates, sender IDs, length, price and statuses.

One request, many numbers

Send an SMS takes up to 100 numbers. To text many people, put them in one request rather than one request each: it is faster and stays well within the rate limit.

Numbers may be local (0771234567) or international (+94771234567). Each number gets its own result; a number that can’t be texted is refused on its own and the rest still go.

Text or template

Send your own text in message, or a saved SMS template with templateId and its values in templateParams. Templates keep wording in one place, so your team can change it in Falconzo without a code change. See List SMS templates for what each one needs.

json
{
  "to": "0771234567",
  "templateId": "cm1tpl4abc",
  "templateParams": {
    "name": "Nimal",
    "order": "#1042"
  }
}

Sender IDs

The sender ID is the name a message comes from, such as ABCSHOP. If you have one verified sender ID it is used automatically; with several, choose one in senderId (its id or name).

  • Transactional sender IDs are for messages people expect: order updates, appointment reminders, codes.
  • Promotional sender IDs are for marketing. Falconzo adds an opt-out line, and messages sent between 8 PM and 8 AM (Sri Lanka time) wait until 8 AM, as Sri Lankan rules require.

Length and price

One SMS holds 160 plain characters. Longer texts are split into parts of 153 characters, and each part is charged. Sinhala, Tamil or emoji switch the whole message to Unicode: 70 characters, then 67 per part. The answer tells you the parts and the price before anything is sent.

What a request costs

Price per part × parts × numbers accepted. The whole amount is taken from your balance when the request is accepted; if the balance can’t cover it you get 402 and nothing is sent. Messages the network refuses are refunded.

Statuses

  • QUEUED: saved and charged, about to go to the network.
  • SENT: the mobile network accepted it.
  • DELIVERED: it reached the phone.
  • FAILED: refused or couldn’t be delivered.
  • EXPIRED: the phone wasn’t reachable in time.
  • UNKNOWN: the network didn’t answer clearly. It is never sent again automatically, so nobody gets the same text twice.
Don’t poll for statuses. Add a webhook and Falconzo tells you the moment a message is sent, delivered or fails.