#SMS

#What it is

The SMS channel lets Threadline send and receive ordinary text messages (the kind every phone can read, with no app and no internet). You connect an SMS provider, which is a company that sends texts on your behalf. Threadline supports 14 of them.

SMS works like any other channel: replies arrive in the Inbox (where your provider supports it), the AI can answer from your assistant's knowledge, your team can take over, and you can send SMS campaigns and Send an SMS automation steps.

#The problem it solves

Many customers, especially for deliveries, appointments and one-time notices, still prefer or only have SMS. A text is read within minutes, needs no app, and works with no internet. If you only use chat apps, you cannot reach those people.

#How it works

1. You choose a provider and paste the keys from its dashboard.
2. Threadline sends your messages through it.
3. For providers that support it, you paste a reply address (a webhook) into the provider's dashboard so replies and delivery reports come back.
4. From then on SMS is one more channel in your Inbox.

#1. Connecting an SMS channel

1. Go to Channels, Connect a channel and choose SMS.
2. Give it a Name (for you only).
3. Choose your SMS provider. A short guide for that provider appears, and the right fields.
4. Enter the keys and the Sender: the phone number or sender name your messages come from. (Some providers can leave it empty to use your account default.)
5. Click Connect.

After connecting, the channel page shows an inbound address. Providers that support replies need it pasted into their dashboard; the guide on the page says where.

The provider cannot be swapped after connecting. To change provider, connect a new SMS channel.

You can connect more than one SMS channel (for example two providers, or one per country). Each campaign and each Send an SMS step picks which one to use.

Test before you launch. Send a message to your own phone from the Inbox, or a test from the campaign wizard, before sending to customers.

#Example: connecting Twilio

1. In the Twilio console, copy your Account SID and Auth token.
2. Buy a Twilio phone number, or verify a number you already own. A trial account can only text numbers you have verified.
3. In Threadline, choose SMS, pick Twilio, and enter the SID, the token and the number as the Sender.
4. Click Connect, then send a test message to your own phone.
5. For replies and delivery reports, paste the inbound address shown on the channel page into Twilio, where the on-page guide tells you.

#The providers

Provider	Replies and delivery reports?	Notes
Twilio	Yes	Account SID, Auth token. Sender: a Twilio number or a Messaging Service (MG…).
Vonage	Yes	API key and secret. A text sender name works only in some countries.
MessageBird (Bird)	Yes	A live access key.
Plivo	Yes	Auth ID and token. Replies need a Messaging application.
Telnyx	Yes	API key. The number must be on a messaging profile.
Infobip	Yes	Your own base URL and an API key.
ClickSend	Yes	Username and API key. Sender optional.
Amazon SNS	No (send only)	IAM keys and region. Move your AWS account out of the SMS sandbox first.
MSG91	Yes	Sends only approved templates: create one whose whole text is ##body## and paste its ID.
Fast2SMS (India)	No	Authorization key and route. Use 10-digit Indian numbers.
BulkSMS BD	No	API key and an approved sender ID. Numbers go out as 880….
SMS.BD (sms.net.bd)	No	API key. Sender optional.
MiMSMS	No	Your sign-in email and an API key. Sender must be registered.
REVE SMS	No	API key, secret key and an approved caller ID.

Where a provider can call back and you have pasted the inbound address, the campaign report shows each message as Delivered or Failed. Where a provider cannot call back, messages stay at Sent (never "Delivered"), and customers cannot reply into Threadline. That is normal for those providers, not an error.

#Other: a gateway that is not in the list

If your local SMS company is not listed, choose Other (custom HTTP API) and describe its HTTP API yourself. You need the gateway's own documentation for the address and the field names.

1. Start from an example (optional). The three examples are common patterns, not specific providers.
2. The request. Pick GET or POST, paste the address, and choose how the details travel: added to the address, as a form, or as JSON. Add one row per parameter, and any headers.
3. Placeholders. Use {{to}} (the phone number), {{to_local}} (without the country code), {{message}}, {{sender}} (the sender box above), {{status_url}} (the address for delivery reports) and {{secret.NAME}}. At least one parameter must contain {{message}}. Quotes and & in a message are encoded for you.
4. Secrets. Put passwords and keys in Secrets and use them as {{secret.NAME}}. They are stored encrypted and hidden once saved; leave one untouched when you edit and it keeps its value.
5. How to tell it worked. An HTTP 2xx answer counts. Add a rule if your gateway also reports errors that way, for example status must equal success, or the answer must not contain ERROR. Say where the message id is (a JSON path such as data.id, or a pattern) so delivery reports can find the message.
6. Send a test. Type your own number and press Send. You see exactly what was sent (secrets hidden) and what came back, which is how you fix a wrong field name.
7. Replies and delivery reports (optional). If the gateway can call a web address, tick the options and name the fields it sends: sender, text and id for replies, and message id and status for delivery reports, with what each status word means. After saving, the channel page shows the address to give your gateway.

Examples

A GET API: method GET, address https://gw.example/send, parameters user={{secret.username}}, pass={{secret.password}}, to={{to}}, msg={{message}}.

A JSON API: method POST, send as JSON, header Authorization: Bearer {{secret.token}}, parameters to={{to}}, from={{sender}}, text={{message}}, message id path id.

Good to know

• The address must be https and public. Addresses inside a private network are refused. If your gateway only offers plain http, ask the platform owner to allow it (Settings → Advanced).
• The gateway has 15 seconds to answer. Redirects are not followed.
• Values are sent as text. If a gateway needs a number or a list, it cannot be described here.
• SMPP is not supported, because it needs a connection that stays open, which ordinary hosting cannot run. Put an SMPP-to-HTTP bridge such as Kannel or Jasmin in front of it and use this option.
• Gateways that send many numbers in one request are not supported.

#2. Writing SMS: characters and parts

A text is split into parts (also called segments), and you are charged per part.

Kind of text	Characters per single part	Characters per part when longer
Plain letters, digits and common symbols (GSM-7)	160	153
Anything else: emoji, Arabic, Bangla, Chinese, many accents (Unicode)	70	67

A counter under the message box in the Inbox and in the campaign wizard shows the characters, the number of parts and the encoding while you type. One emoji turns the whole message into Unicode, which can triple the cost. Keep texts short and avoid emoji unless they matter.

#3. SMS campaigns

In the Broadcast wizard, choose an SMS channel, write the message (merge tags such as {{contact.name}} work), and send a test to your own phone. Campaigns send up to about 10 texts a second. The report shows each provider's own failure reason for anyone who did not get it.

#4. Consent, STOP and START

• A campaign or Send an SMS step only reaches people who agreed to SMS. See Contacts.
• A person who writes STOP (also unsubscribe, cancel, end, quit) is opted out on that SMS number only. START brings them back if they had agreed before.
• Keep a short opt-out line in marketing texts, for example "Reply STOP to opt out". Many countries require it.

#5. Plan limits

Your plan may limit SMS per month. Once it is used up, further texts are marked Failed with the reason ("Your plan's monthly limit of SMS per month has been used up") until next month. Each part counts. See Plans and Billing.

#Common questions

My campaign stays "queued" and nothing is sent. Sending runs in the background, one batch at a time. If it never starts, the background worker is not running. Tell the person who runs your Threadline installation to check the cron job (Owner, Cron & Health). See Troubleshooting.

My texts show Sent but never Delivered. Your provider does not send delivery reports (see the table). The text may still have arrived.

A customer replied but I do not see it. The provider needs the inbound address set in its dashboard, or it does not support replies.

Connect failed. Check the keys, and that the sender is allowed by your provider and your country's rules. Some countries require registered sender names.

Why did one text count as three? It is long, or contains emoji or non-Latin letters, so it was split into parts.