Routing

Routing is the choice, for each outbound message, of the phone and the SIM that carry it. With a single phone and a single SIM there is nothing to choose. As soon as you have several SIMs, the choice matters: it spreads the load, keeps each SIM under its quota, and can save money when a message stays inside one carrier's network.

By default the gateway chooses on its own. The Routing screen, right under Devices in the sidebar, lets you add prefix rules: "numbers starting with +26134 leave from SIM 1 of the front desk phone".

How a SIM is chosen

For each message, the gateway goes down this list and stops at the first answer:

1. A phone named in the send. When you pick a Sending device in quick send or in a conversation, or pass deviceId to the API, that phone carries the message or nothing does. The rules are not consulted.
2. The SIM of the conversation. A reply in a conversation leaves from the SIM the correspondent already knows, as long as that SIM can send. Your customer always sees the same number.
3. The prefix rules. If a rule covers the number, its SIMs are tried in the order you set.
4. The automatic routing, over every phone.

A SIM can send when its phone is online, in the routing pool, its SIM is in service, its daily quota and its per-minute limit are not reached, and it has waited its minimum interval since its last SMS. A SIM that cannot send is simply skipped.

Automatic routing

The automatic routing applies to every number no rule covers. Its mode is chosen when the gateway is installed, with the GATEWAY_ROUTING_MODE variable of the .env file, followed by sms-gateway restart (see the installation guide):

The carrier mode needs the table of the prefixes of each carrier, given in GATEWAY_CARRIER_PREFIXES (for example Telma:+26134,+26138;Orange:+26132). Write each carrier name exactly as the phone reports it, as shown in the SIM column of Devices: a name spelled differently matches no SIM. Without the table, the gateway refuses to start rather than silently routing without carriers.

Changing the mode means changing the variable and restarting the gateway. The prefix rules, on the other hand, change live from the dashboard.

Prefix rules

A rule says: "messages to numbers starting with these prefixes leave from these SIMs, in this order". Typical uses:

• A SIM with an on-net plan for one carrier: send that carrier's numbers from it.
• A phone per country: numbers starting with +33 leave from the French SIM, +261 from the Malagasy one.
• A dedicated number for a customer segment, so they always see the same sender.

Create a rule

In Routing, click New rule (Superadmin). The dialog asks for:

The rule applies to the next message, with nothing to restart.

Which rule wins

When several rules cover a number, the longest prefix wins: +26134 beats +261 for +261341234567. That lets you write a general rule and more specific exceptions. Between two prefixes of the same length, the rule higher in the list wins.

Inside a rule, the first SIM of the list that can send carries the message. The next ones are there to take over when the first is offline, out of quota or out of service.

When none of the rule's SIMs can send

That is what Wait for these SIMs decides:

With Wait for these SIMs on, the wait depends on why the SIMs cannot send:

• their daily quota is reached: the message moves to Quota reached and leaves as soon as a quota is raised, or at midnight UTC;
• their per-minute limit is reached, or they have not waited their minimum interval: the message stays Queued and leaves as soon as one of them is free;
• their phone is offline, out of the routing pool, or the SIMs are out of service: the message stays Queued and the gateway tries again every minute, without spending an attempt. It leaves as soon as a SIM of the rule comes back.

Use it when the sender number matters more than the delay: a customer who must always see the same number, a SIM that is the only one allowed to send to a given network. A strict rule can hold messages as long as its phone stays away; you see them in the Queue.

The rules table

The Prefix rules table shows each rule with Numbers starting with, SIMs, in order (phone, SIM, carrier and masked number), If none can send (Wait or Automatic routing), an Active switch, and Actions to edit or delete.

Unpairing a phone removes its SIMs from every rule. A rule left with no SIM shows No SIM left: the rule is ignored. Deleting a rule sends its numbers back to the automatic routing; messages already sent are not affected.

Test a number

The Test a number card tells you which SIM a message to a given number would leave from right now, and why. Nothing is sent, and the test does not disturb the rotation of real traffic. The answer is one of:

Use it after creating a rule, and when a message did not leave from the SIM you expected.

Options

Other settings that change which SIM can send: the daily quota, SIM in service and the routing pool in Devices, and the Messages per minute and per SIM limit in Sending messages.

Who can do what: a Superadmin creates, edits and deletes rules. Operators and Read only accounts see the rules and can test a number.

API

POST /routing/test answers with an outcome (rule, fallback, held, automatic, unavailable), the matching rule and prefix, the chosen deviceId, deviceName and slot, and a reason when nothing can send (NO_DEVICE_AVAILABLE, QUOTA_EXHAUSTED, RATE_LIMITED, RULE_SIMS_UNAVAILABLE). Writing rules through an API key requires the admin scope.

Troubleshooting