SMS

SMS is a channel of its own in Kommio, with one provider behind it per inbox. Twilio is the first; each provider is its own listing in the Marketplace. The channel is for conversations with customers only: Kommio sends no campaigns or bulk messages from it, never messages someone who opted out, and does not send satisfaction surveys by SMS.

Set it up with Twilio

1. Get your credentials

   In the Twilio Console, copy the Account SID (it starts with AC) and the Auth token from the account dashboard. No number yet? Buy one with SMS capability, and read US numbers first if it is a US number.

2. Connect

   Settings › Marketplace › Twilio SMS › Install in this workspace, or Settings › Inboxes › Add inbox › SMS. Paste the Account SID and auth token and press Test connection: Kommio lists the account's numbers, with their SMS and MMS support and where their incoming messages go today, and its Messaging Services. Pick the one customers text.

3. Point incoming messages at Kommio

   Leave Point incoming messages at Kommio on (the default) and Kommio sets the number's (or the Messaging Service's) incoming webhook to the inbox's address, remembering what was there before. Turn it off to set it yourself; the inbox page shows the address to paste.

4. Try it

   Name the inbox, choose its agents, and text the number from a phone. The message arrives in the inbox, and your reply comes back by SMS.

Optionally, give a standard Twilio API key (its SID starts with SK; with its secret) and Kommio calls Twilio with the key instead of the auth token; the auth token is still required, because Twilio signs its webhooks with it. Both are stored encrypted and never returned. After rotating the auth token in Twilio, paste the new one on the inbox's page. A trial Twilio account sends only to numbers verified in Twilio and adds a trial notice to each message; the connection test says so.

A Messaging Service set to use each sender's own webhook sends incoming messages to the numbers instead; the inbox page warns about it. Pausing or deleting the inbox leaves your Twilio number as it is: point it elsewhere in Twilio when you stop using it.

Every incoming post must carry a valid Twilio signature for the inbox's own address, checked in constant time; anything else is refused. A message is stored once however often it is delivered, and delivery reports only ever move a message forward.

What is supported

Segments. One SMS carries 160 characters of the GSM alphabet; a single character outside it (an emoji, a curly quote, most non-Latin scripts) sends the whole message in UCS-2, 70 characters to a segment. Longer messages are cut into segments of 153 or 67, each billed as one SMS by your carrier. The composer shows the count as you type, for example "SMS segments: 2 · 170 characters · GSM-7".

MMS. Whether a number sends pictures comes from its Twilio capabilities; for a number without MMS the composer disables attachments and the API refuses files with a clear reason. Pictures reach Twilio through signed Kommio links that expire after 30 minutes, and incoming pictures are fetched only from your account's own media on Twilio.

Contacts. The customer is identified by their number in international format (+14155550100), the same phone identity contacts already use, so a text from a number already on a contact lands on that contact and their history. A message from a short code or an alphanumeric sender cannot be answered and is reported on the inbox instead.

Failures. An invalid, landline or unreachable number, a body Twilio refuses and an opted-out recipient fail the message for good, with Twilio's reason. If Twilio's answer never came after the request left, the message is marked failed rather than sent again, so a customer is never texted twice; the agent sees why and can send it again. When Twilio asks Kommio to slow down, it waits and retries.

STOP, START and HELP

A customer who texts STOP (or STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, OPTOUT: the whole message, in any case) is opted out of that number or Messaging Service:

• the conversation shows a line saying the customer opted out; it does not reopen a resolved conversation, and no bot or flow answers it;
• Kommio refuses to send to that number from that sender, whether an agent, a rule, a bot or the API tries, and says why;
• START (or YES, UNSTOP) opts them back in. HELP and INFO stay ordinary messages, which Twilio answers with your configured help text.

With Twilio's Advanced Opt-Out on a Messaging Service, Kommio follows Twilio's verdict for your own keywords and languages, and a send Twilio refuses because the customer opted out is recorded too. Opt-outs are kept per workspace, sender and number, survive deleting and recreating the inbox, and are kept when a contact is erased, so the number stays unmessaged.

US numbers

Health

The inbox and its installation show the sender, the Twilio account's status, when the last customer message arrived and the last delivery error of the past week. A check every five minutes turns the inbox red when the account is suspended or closed, the number left the account, or incoming messages were pointed elsewhere after Kommio set them up; a refused auth token asks for a reconnect.

API

# check credentials: the account, its numbers and Messaging Services
curl -X POST "$KOMMIO_URL/channels/sms/test" -H "Authorization: Bearer $KOMMIO_KEY" -H "Content-Type: application/json" \
  -d '{"config": {"provider": "twilio", "account_sid": "AC<account sid>", "auth_token": "<auth token>"}}'

# create the inbox for one number (or "messaging_service_sid": "MG<messaging service sid>")
curl -X POST "$KOMMIO_URL/inboxes" -H "Authorization: Bearer $KOMMIO_KEY" -H "Content-Type: application/json" \
  -d '{"name": "SMS", "channel_kind": "sms", "config": {"provider": "twilio", "account_sid": "AC<account sid>", "auth_token": "<auth token>", "phone_number": "+14155550100"}}'

The inbox's config then carries the sender's name, whether it sends MMS, whether Kommio set the webhook, the previous webhook address and the inbox's inbound and status addresses; its capabilities say that the composer counts SMS segments and that the channel has opt-outs. Replying to an opted-out customer returns 422 with the reason.