> ## Documentation Index > Fetch the complete documentation index at: /help/llms.txt > Use this file to discover all available pages before exploring further. # Twilio (text messages) > Coming soon: text your contacts (SMS) from your own Twilio number, stop the campaign when they text back, and never text someone who said STOP. > [!NOTE] > > **Coming soon.** Text messages (SMS) aren't available in Kerux yet, and nothing is charged for them. The **Send SMS** step, SMS broadcasts, the **SMS reply received** trigger and the Twilio row in **Integrations > Connections** show **Coming soon** until texting opens. This page shows how it will work. Once it opens, you connect your own Twilio account and add **Send SMS** steps to your campaigns, next to LinkedIn, email and WhatsApp. Texts go out from your Twilio number, and Twilio bills them to your Twilio account. ## Until texting opens * Twilio can't be connected: its row in **Integrations > Connections** says **Coming soon** and opens nothing. * A contact who reaches a **Send SMS** step (in a campaign that already had one) waits there with **Waiting for text messages to open in Kerux (coming soon): nothing is sent or charged, it goes on by itself**. Before launch, a campaign with a **Send SMS** step shows **Text messages: coming soon**. Remove the step if you don't want contacts to wait. * A reply in an SMS conversation in the inbox isn't sent: **Not sent: text messages are coming soon in Kerux.** * **Create with AI** leaves **Send SMS** steps out and says so in its notes. * You can already record each contact's consent to get texts (see [Sending rules and consent](/help/campaigns/sending-rules-and-consent.md#where-consent-comes-from)). ## Set it up (once texting opens) > [!WARNING] > > Only text people who gave you their number and agreed to get texts from you. Cold texts are illegal in the United States (TCPA) and break every carrier's rules. Kerux only texts contacts with a recorded consent: see [Sending rules and consent](/help/campaigns/sending-rules-and-consent.md). To text phones in the United States, your Twilio number needs an approved **A2P 10DLC** registration in your Twilio account. That registration stays in your Twilio account: Kerux never needs it. **1. Copy your Twilio keys** Sign in at [console.twilio.com](https://console.twilio.com). On the home page, under **Account info**, copy the **Account SID** (it starts with AC) and the **Auth Token** (click **Show** first). **2. Connect Twilio in Kerux** Go to **Integrations > Connections** and click **Connect** on the **Twilio (text messages)** row (under **Messaging**): its panel opens. Paste the **Account SID** and the **Auth Token**, tick the box **I will only text people who gave us their number and agreed to get texts from us, I will honor STOP and every other opt-out at once, and our US numbers are registered for A2P 10DLC in this Twilio account.** and click **Connect Twilio**. Kerux keeps who ticked it and when (later, **Change keys** shows **Consent and 10DLC confirmed on** that date instead of the box). Kerux checks the keys with Twilio (wrong keys are never saved) and lists your account's numbers that can send texts. The first connection needs an owner or admin, because the box is a statement for the whole workspace: a member sees **Only an owner or admin can connect Twilio the first time...** and can change the keys once an admin has connected it. Viewers can open the panel but can't change it (**Ask an owner, admin or member of this workspace to connect Twilio (viewers can't).**) **3. Send replies to Kerux** Next to each number, click **Send replies to Kerux**. Kerux sets the number's **A message comes in** webhook in your Twilio account, so texts back from contacts reach Kerux. If that number already sent its replies to another app, Kerux asks first, because that app stops getting them. **4. Say who sends** Go to **Settings > Sending rules** and fill in **Company name**. The first text a contact gets starts with it. SMS campaigns can't launch without it. **5. Add a Send SMS step** In your campaign, click **+** and choose **Send SMS** (under **SMS**). Pick the number in **Send from** (or leave it on your first number) and write the text. Variables like `{{contact.first_name}}` work like in a LinkedIn message. **6. Record each contact's consent** Only contacts with a recorded consent get texts. It is recorded by itself when a contact ticks a consent box on your form or texts you first; you can also record it when you import (tick **They agreed to get texts (SMS)** and confirm), or on the contact page under **Consent and contact** (tick **Texts (SMS): the contact gave consent**). If every contact you add already agreed, an owner or admin can turn on **Texts (SMS)** under **Contacts' consent** in **Settings > Sending rules** once, for the whole workspace. See [Sending rules and consent](/help/campaigns/sending-rules-and-consent.md). > [!TIP] > > To use an API key instead of your Auth Token, click **Use an API key instead** and paste the **API Key SID** (starts with SK) and its secret, from **Account > API keys & tokens**. Also paste the **Auth Token** in **Auth Token (for replies)**: Twilio signs replies with it, and without it Kerux can't check that a reply really comes from Twilio, so it refuses them. ## How texts are sent * Only to contacts with a recorded consent for that phone. The others wait at the step with **Waiting for consent: texts go only to people who agreed. Record it on the contact** (in **Needs attention**, **Record consent** opens the contact). Before launch, the checks say how many contacts have no consent. * Only from 8:00 to 21:00 in the contact's own time (from 8:00 to 20:00, and at most 3 texts a day, in Florida, Oklahoma and Maryland). Kerux reads where the contact is from their location and their phone's area code, and when it isn't sure it waits for an hour that is fine everywhere they could be. Contacts wait with **Waiting for the contact's local hours for texts (8:00 to 21:00, stricter in some states)** and go on by themselves. * The first text a contact gets in a campaign starts with your company name (for example **Northwind: Hi Ana...**) and ends with **Reply STOP to opt out.**, unless your text already has them. The step panel says so. * To the contact's **Phone**, written with its country code (like +1 415 555 0101). A contact without a phone, or with one that has no country code, waits in **Needs attention**: type the phone under **Fill it in on the contact (the step goes on by itself)** and click **Save and continue**, or choose **Skip this step** or **Retry now**. Once you fix the phone, the step continues by itself. * Never with an empty variable: a text that would go out with a blank waits in **Needs attention** instead. * Inside the campaign's sending hours, with a short random gap (20 to 90 seconds) between two texts from the same number. * Up to the number's daily limit: 100 texts a day by default. Change it in **Texts a day** next to the number (1 to 1,000). The Twilio panel shows how many each number sent in the last 24 hours. When a number reaches its limit, contacts wait with **Waiting: the Twilio number sent its texts for today** and go on by themselves later. * One text is up to 1,600 characters. Twilio bills it in parts: one part holds 160 characters, and a longer text goes in parts of 153. An emoji or a character outside the basic SMS alphabet (like á, í, ó, ú or curly quotes) changes that to 70 characters for one part and 67 per part, and most emoji count as two. `^ { } \ [ ~ ] |` and `€` count as two characters. The step shows the estimate (variables count as their name until the contact's real value fills them) and, for such a text, says **It has an emoji or a character outside the basic SMS alphabet, so each text holds 70 characters (67 when split).** * If Twilio can't be reached at all (nothing was sent), the contact waits with **Twilio couldn't be reached, so the text wasn't sent: it tries again by itself** and Kerux tries again a few times. If it still can't, the contact waits in **Home > Tasks**. ## Replies, STOP and START * When a contact texts back from the phone in their details, it counts as their reply: the campaign stops for them, like a LinkedIn reply (unless you turned off the **Replies** switch, **Stop when the contact replies**, in the campaign's **Settings**; then a **Wait until** step waiting for their reply moves on). Their text is on the contact's history as **Texted back** and in the [inbox](/help/inbox/use-the-inbox.md), in their SMS conversation with that number, where you can answer it (with the same rules: consent, STOP and their own hours). * A contact who texts **STOP** (or STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, OPT OUT, or plain words like "stop texting me", "remove me", "wrong number", also in Spanish, German and French) is never texted again from this workspace, and their consent no longer counts: their history says **Texted STOP: never texted again**, and a later **Send SMS** step takes them out of that campaign without sending, with **Text not sent: this phone texted STOP**. A STOP also counts as their reply. If they text **START**, they can get texts again (**Texted START: can get texts again**), and that counts as their consent. The Twilio panel shows how many phones texted STOP. * The **SMS reply received** campaign trigger (**Kerux events**) starts a campaign when a contact texts back. A STOP never starts anything, and people who aren't contacts are ignored. * Two contacts with the same phone: the reply goes to the one Kerux texted. If that isn't exactly one contact, nobody is moved and owners and admins get a notification to keep the phone on one contact only. * Your [webhooks](/help/developers/webhooks.md) get a text back as `sms.message_received` (with `message.text` and `message.channel` set to `sms`), never as a LinkedIn message. ## Common problems > [accordion] Twilio refused these keys > > Copy the **Account SID** and **Auth Token** again from the Twilio Console home page (**Account info**). If you rotated the Auth Token in Twilio, click **Change keys** in the Twilio panel and paste the new one. While the keys are refused, texts wait (nothing is sent) and continue once new keys are saved. > [accordion] No number can send texts > > Buy a number with SMS in Twilio (**Phone Numbers > Buy a number**), then click **Test connection** in the Twilio panel. Voice-only numbers aren't listed. Until a number can send, contacts on a **Send SMS** step wait with **Waiting for Twilio: connect it in Integrations > Connections**. > [accordion] Trial account > > A Twilio trial account only texts phones you verified in Twilio and adds a trial note to each text. Upgrade the Twilio account to text your contacts. > [accordion] Replies don't show up in Kerux > > On the Twilio panel, the number should say **Replies come to Kerux** (not **Replies go to another app** or **Replies go nowhere yet**). If it doesn't, click **Send replies to Kerux**, or click **Copy** and paste the URL shown in the panel in Twilio: **Phone Numbers > your number > Messaging configuration > A message comes in** (Webhook, HTTP POST). If the number is in a Twilio Messaging Service, the service's own settings can send replies elsewhere: check them in Twilio. > > If the panel says **Replies can't be checked: add the Auth Token (Change keys) so Kerux accepts them.**, you connected with an API key only: click **Change keys** and add the **Auth Token (for replies)**. > [accordion] We can't confirm the text went out > > If Twilio didn't answer in time, Kerux doesn't know whether the text left, so it never sends it again on its own. The contact shows **We can't confirm the text went out: check Twilio's Messaging logs and decide** and waits in **Home > Tasks** under **Unconfirmed sends**. Check Twilio's Messaging logs, then choose **It was sent**, **Send again** or **Skip this step**. > [accordion] Twilio says the phone isn't valid > > The contact waits in **Needs attention** with Twilio's words. Fix the phone on the contact and it continues by itself. > [accordion] Twilio refused the text for another reason > > For example the number can't text that country, or a trial account. Nothing was sent. The contact waits in **Home > Tasks** with Twilio's words: fix it in Twilio, then retry. > [accordion] Contacts wait with Waiting for consent > > The contact has no recorded consent to get texts on their current phone. Record it only if they really agreed: open the contact and, under **Consent and contact**, tick **Texts (SMS): the contact gave consent**. The step goes on by itself. If you change a contact's phone, record the consent again for the new one. > [accordion] Texts wait for who sends > > They show **Waiting for who sends in Settings > Sending rules: add your postal address (emails) or company name (texts)**. A text needs your company name: go to **Settings > Sending rules**, fill in **Company name** and click **Save**. Waiting texts go on by themselves. > [accordion] Texts wait for an admin to confirm consent and 10DLC > > The Twilio account was connected before Kerux asked for this, so SMS campaigns can't launch and texts wait. An owner or admin opens **Integrations > Connections**, clicks **Change keys** in the Twilio panel, pastes the keys again, ticks the box and clicks **Save keys**. Waiting texts go on by themselves. > [accordion] Launch says a Send SMS step has no number > > Launch is blocked while a **Send SMS** step can't send: Twilio isn't connected, its keys were refused, or the step's number left your Twilio account. Click **Fix**, then launch again. > [accordion] A number says Gone > > The number is no longer in your Twilio account. Steps set to it wait with **The Twilio number this step sends from isn't in the account any more: pick another**. Open the step and pick another number in **Send from** (or **Your first Twilio number (automatic)**). ## API and MCP While text messages are coming soon, connecting Twilio through the API answers `403 SMS_COMING_SOON` (nothing is saved or charged). Everything in the Twilio panel is in the [public API](/help/developers/api.md) and so in Kerux's MCP server: `GET /v1/sms` (the account, its numbers and the reply URL), `POST /v1/sms/twilio` (connect with `account_sid` and `auth_token`, or `api_key_sid` and `api_key_secret`, plus `attest: true` the first time), `POST /v1/sms/twilio/test`, `DELETE /v1/sms/twilio`, `PATCH /v1/sms-numbers/{id}` (`daily_limit`), `POST /v1/sms-numbers/{id}/replies-to-kerux` and `GET /v1/sms-opt-outs`. Connecting, replacing or disconnecting the keys and sending replies to Kerux need an API key with **admin** (a connected app such as claude.ai or ChatGPT can't). Keys go in and never come back out. A contact's consent is `POST /v1/leads/{id}/consent` (see [Sending rules and consent](/help/campaigns/sending-rules-and-consent.md)). Send SMS steps are part of the campaign like any other step (`type: "sms"`, with `text` and an optional `numberId`). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.