Sending messages

Every SMS that leaves your gateway follows the same path: it enters the queue, the gateway chooses a phone and a SIM that can send it right now, the phone hands it to the carrier, and its status follows what happens next. This page explains how to send, how to follow what you sent, and what the gateway does on its own when something goes wrong.

The ways to send

They all share the queue, the routing, the quotas and the retries described below. Campaigns are the only traffic held by the night and Sunday pauses.

See also: Conversations, Campaigns, Automation and the API guide.

Quick send

Quick send sends one message, now or later, to one or several recipients.

Choose the recipients

Pick one of the three modes under Recipients:

Numbers are read in international format: a leading + followed by the country code. A number written with 00 instead of + is accepted and converted, and spaces, dots, dashes and parentheses are ignored. A number without its country code (0341234567) is not recognised.

As you type, the screen counts valid recipients and the lines ignored, format not recognised. The same number pasted twice is sent only once.

In Contact group mode, the screen reads the whole group before you send, however many members it has, and shows the real number of recipients, plus the opted-out contacts left out. The Send button waits until the count is done. If the group cannot be read, a message says so with a Retry button.

Limits. A quick send takes at most 500 recipients, a whole group included. Beyond that, the screen says so (for a group: "This group has 1,250 contacts, more than the 500 recipients a quick send takes"), refuses to send and suggests a campaign, which is built for large sends: it paces the traffic, respects the night pause and gives you statistics. Nothing is ever sent to only part of a group.

Write the message

The counter under the message shows the number of characters, the number of SMS it will cost and the encoding:

A long message is never refused: it is split into several SMS that the recipient's phone joins back together. But each part is billed by your carrier and counts against the daily quota of the SIM. The screen warns you beyond six SMS per recipient, and shows the total, for example "3 messages, 6 SMS in total".

Shorten and track links

Under the message, the Shorten and track links switch (off by default) replaces every address starting with http:// or https:// by a short link served by your gateway, which counts the clicks. The replacement happens when you click Send; the same address written twice gets one link, shared by all the recipients. The screen tells you how many links will be made and how the length changes (characters and SMS per recipient, before and after), and the counter and the total cost are computed on the text with its short links. The links then appear in Short links. See Short links.

Choose the phone and the time

Click Send. The confirmation "N messages accepted by the gateway" means the messages are in the queue, not yet delivered. Recent sends, at the bottom of the screen, lists your last outbound messages with their live status.

A scheduled message waits in the queue with the status Queued and the mention "Scheduled for" its date. It leaves at that time, day or night: the night pause does not apply to it.

The queue

The Queue screen lists the messages and lets you relaunch those that did not leave. It opens filtered on Failed messages, since those are the ones that need you.

The columns show the Status, the Recipient, the Device that carried the message, the number of Attempts, the creation date and the Reason of a failure or a cancellation.

The Reason is a plain sentence in your language, the same one the conversation and the activity log show, for example "The SIM had no network signal." or "Withdrawn before leaving: its campaign was cancelled.". Hover it to see the technical code (NO_SERVICE, CAMPAIGN_CANCELLED...), the one the API returns in errorCode. A code the dashboard does not know yet, reported by a newer version of the phone app, is shown as "The phone or the gateway reported an error (CODE).".

When messages are waiting for a SIM daily quota, a banner at the top says how many, with an Edit quotas link to the Devices screen.

A Queued message that waits for the pace of its SIMs says so under its status, with the time of its next try: "Waiting for the SIM cadence, next try at 14:32" (the minimum interval) or "Waiting for the per-minute limit of the SIMs". Nothing is wrong: it leaves on its own at that time.

The statuses

Sent is not Delivered. "Delivered" depends on a delivery receipt from the recipient's carrier. Some carriers do not send them, or send them late: a message can stay Sent although it was received. A negative receipt, on the other hand, is final: the message moves to Failed.

Retries

When a send goes wrong, the gateway does not give up at once. What it does depends on the cause:

When the attempts run out, the message moves to Failed. The number of attempts and the waits between them are set in Settings > Sending (see Options).

In the API, the errorCode field of a failed or cancelled message gives the reason. The Reason column shows the same codes as sentences:

Treat any other code as a generic failure: a newer version of the phone app may add some.

Relaunch by hand

A message that is Failed, Quota reached or Paused can be relaunched:

• from the Queue, by ticking it and clicking Retry the selection;
• from its conversation, with Retry under the failed message;
• through the API, with POST /messages/{messageId}/retry.

A relaunched message leaves at once, without waiting for the next scheduled attempt. It is refused if the recipient opted out in the meantime. Delivered, Sent and Cancelled messages cannot be relaunched: that would send them twice.

SIM cadence: a minimum interval between two SMS

You can make each SIM wait a minimum number of seconds between two SMS, in Settings > Sending, field Minimum interval between two SMS per SIM, in seconds. A SIM that sends at a steady, human pace looks less like a spam source to its carrier than one that fires a burst.

How it works.

• It applies to every SMS, whatever its source: API, quick send, campaign, conversation reply, automatic reply, alert by SMS, and retries.
• The interval is counted from the moment the gateway hands the SMS to the phone, not from the phone's confirmation or the delivery receipt.
• You never have to wait for anything: you can send 50 messages at once, they are all accepted, wait in the queue as Queued, and leave on their own, one after the other, as soon as their SIM is free. The Queue screen shows them as "Waiting for the SIM cadence" with the time of their next try.
• Each SIM has its own clock. A SIM that waits never holds back another SIM, not even the second SIM of the same phone: with two SIMs and 30 seconds, two SMS leave every 30 seconds.
• A message addressed to a given phone (deviceId) keeps it while it waits.
• Waiting spends no attempt. A retry after a failure also waits for the interval if needed.
• The acknowledgement timeout starts when the SMS is handed to the phone, so a message waiting for its SIM never times out in the queue.
• The gateway checks the queue every two seconds: a message leaves within about two seconds after the end of the interval.
• Messages waiting for their SIM are sent in order. There is no priority: an alert waits like any other SMS, but a message that arrives while others wait takes the next free slot.

A SIM with its own value. In Devices, the pencil next to a SIM opens a dialog where Own interval for this SIM replaces the setting for that SIM only (Superadmin). 0 means no wait on that SIM, even when the setting asks for one; turning the switch off makes the SIM follow the setting again. A new value applies to the next SMS; messages already waiting keep their time.

How it combines with the other limits. Each limit must allow a send; the strictest one wins.

Examples: with an interval of 10 seconds, a SIM sends at most 6 SMS a minute, so a per-minute limit of 6 or more changes nothing, and a lower one (say 3) still applies. A campaign at 60 messages per minute on two SIMs with an interval of 30 seconds actually sends 4 per minute: the interval is the limit. The daily quota still counts every SMS.

Set to 0, the default, the interval adds no wait: the gateway behaves as before.

Night and Sunday pauses: campaigns only

You can forbid campaigns from sending at night and on Sundays, in Settings > Sending, under Night pause for campaigns. A campaign message due during a pause moves to Paused and leaves automatically when the pause ends.

These pauses only hold campaigns. A quick send, an API call, a conversation reply or an automatic reply leaves at any hour: someone is waiting for it. A campaign is the only traffic nobody asked for at that moment, and a promotional SMS at three in the morning costs you more goodwill than it brings.

The hours are read in the platform time zone, set in the same tab. This time zone also governs the time of scheduled sends and how dates are shown in the dashboard. It is not the time of each phone: the header shows the local time of your phones and warns you when one lives at another hour (see Devices).

Follow the activity

The Dashboard shows how many messages left and arrived, in the Activity over the last 24 hours chart. Choose the period with the 24 h, 7 d, 30 d and 90 d buttons: the chart then shows one bar per hour, per six hours, or per day. Each bar stacks the outbound messages and the inbound ones, and the card gives the totals of the period. Hover or tap a bar for the exact times of the slot.

A message counts at its creation (when it was queued for an outbound one, when the phone received it for an inbound one), whatever its status since. The counts cover every message of the period, not a sample. Slots follow the platform time zone, daylight saving included. The chart refreshes every minute.

Through the API, GET /messages/stats?period=24h (or 7d, 30d, 90d) returns the same counts. It never returns a message text or a number.

Options

The sending settings are in Settings > Sending, reserved to a Superadmin, and apply to the next message without any restart.

Other settings that change what you send:

• the daily quota, the in service switch and the own interval of each SIM, in Devices (see Devices);
• the routing rules, which choose the SIM by number prefix (see Routing).

API fields of POST /messages

The Idempotency-Key header protects a single-recipient send against being queued twice when your software replays a request after a network error.

The request is checked as a whole before anything is queued: if one recipient is invalid or opted out, the request is refused and nothing is sent, so you always know what to replay.

Troubleshooting