> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Twilio SMS

[Back to messaging or digital channels](https://koreai.mintlify.site/agent-platform/channels.md#messaging-or-digital-channels)

Connect a Twilio phone number to your agent so customers reach it over SMS and MMS. You prepare a messaging-capable sender in Twilio, enter its account credentials in Artemis, then point the number's incoming-message webhook at a connection-specific URL that Twilio signs on every request.

The setup requires:

1. [Prepare the Twilio project and sender](#prepare-the-twilio-project-and-sender).
2. [Artemis channel configuration](#artemis-channel-configuration): create the connection, then copy its Webhook URL.
3. [Webhook configuration in Twilio](#webhook-configuration-in-twilio): set the number's incoming-message webhook.
4. [Verify the connection](#verify-the-connection) with signed two-way SMS and MMS.

After setup, an SMS to your Twilio number opens a session in Artemis, and the agent's reply goes back through Twilio's Messages API.

**Important considerations**

* **The Twilio phone number selects the connection**: Save the number in E.164 format, such as `+15551234567`. Artemis resolves the connection from the encoded number in the webhook path, then confirms the inbound `To` field matches. A friendly connection name isn't a valid identifier.
* **The reply doesn't travel in the webhook response**: Artemis returns an empty TwiML response immediately and sends the agent's reply separately. A 2xx proves only that Twilio delivered the inbound message.
* **Twilio signs the exact URL**: Scheme, host, port, path, the encoded plus sign, and form values all participate in signature validation. A proxy that rewrites any of them breaks it.
* **One account boundary**: The Account SID, Auth Token, phone number, and optional Messaging Service must come from the same Twilio project or subaccount.

## Prerequisites

Confirm these before you start.

* Access to the Twilio project or subaccount that owns the sender and its billing.
* A messaging-capable Twilio number for the destination countries, with any sender registration your traffic needs, such as [A2P 10DLC](https://www.twilio.com/docs/messaging/compliance/a2p-10dlc) for US long codes.
* Artemis project access with permission to open **Deployments** > **Channels**, and a deployed agent in the environment you intend to bind.

***

## How Artemis routes Twilio SMS messages

Twilio calls a URL you set per number, so Artemis puts the number in the path.

| Piece | Owner | What it does |
| - | - | - |
| **Twilio Phone Number** | Twilio | Routes inbound messages. Artemis encodes it in the webhook path, so a leading plus becomes `%2B`, and checks that it matches the inbound `To` field. |
| **Account SID** | Twilio | Identifies the account for the Messages API and authenticated MMS downloads. Starts with `AC`. |
| **Auth Token** | Twilio | Validates `X-Twilio-Signature` on inbound requests and authorizes outbound API calls. |
| **Messaging Service SID** | Twilio | Optional. When set, Artemis sends replies through that service. Starts with `MG`. |
| **Webhook URL** | Artemis | Receives the incoming-message callback at `/api/v1/channels/twilio_sms/webhook/{number}`. |

Artemis keys each conversation as `twilio_sms:{To}:{From}`, so a different sender or Twilio number starts a separate conversation.

***

## Prepare the Twilio project and sender

Do this in Twilio before you open Artemis. Select **Open Twilio Console** or **Open Messaging Services** in the setup guide to jump straight there.

**1. Use the project that owns the sender**

In the [Twilio Console](https://www.twilio.com/console), switch to the project or subaccount that owns the production number and billing. Every value you collect must come from this one account.

**2. Buy or select a messaging-capable number**

1. Go to **Phone Numbers** > **Manage** > **Active numbers**, or buy a number from **Buy a number**.
2. Confirm it supports SMS, and MMS if the agent handles media, for the destination countries.
3. Keep the full E.164 value, including the leading plus and country code.

**3. Complete sender and destination compliance**

Finish the registration, sender verification, consent, opt-out, and regional requirements Twilio shows for your countries and traffic type. A configured webhook doesn't bypass carrier or regulatory rules.

**4. Copy the Account SID and Auth Token**

From the account information panel on the Twilio Console dashboard, copy the `AC`-prefixed **Account SID**, then reveal and copy the **Auth Token**.

**5. Decide whether to use a Messaging Service**

A Messaging Service is optional. To use one, go to **Messaging** > **Services**, add your number to its **Sender Pool**, configure inbound handling at the service or number level, and copy the `MG`-prefixed SID.

> [!WARNING]
>
> Twilio trial restrictions still apply. Trial projects may limit recipients, sender choices, or message branding. Prove production behavior with an upgraded account and an approved sender before launch.

***

## Artemis channel configuration

Create the connection before you configure the Twilio webhook. The callback URL contains the encoded phone number, so you can't finalize it until the identifier exists.

1. Open Artemis and select the project.

2. Go to **Deployments** > **Channels** > **Twilio SMS** > **+ New**. The **New Twilio SMS Connection** dialog opens, with the setup guide on the left and the fields on the right.

3. Configure the fields:

   | Artemis field | Source / Notes | What it controls |
   | - | - | - |
   | **Display Name** | You choose it | The label operators see. Name it for the sender and environment. Routing ignores it. |
   | **Twilio Phone Number** | **Active numbers** | The routing identifier. Enter the exact E.164 value, including the plus sign and country code. |
   | **Account SID** | Twilio Console dashboard | Used with the Auth Token for the Messages API and authenticated MMS downloads. |
   | **Auth Token** | Twilio Console dashboard | Validates inbound `X-Twilio-Signature` and authorizes outbound calls. Use the token from the same account. |
   | **Messaging Service SID** | **Messaging** > **Services** | Optional. When set, Artemis sends with `MessagingServiceSid`. Leave it empty to reply from the inbound number. |
   | **Environment** | Your published environments | The environment whose active deployment answers messages. Leave the working copy default only while you develop. |
   | **Provider Verification Strength** | Defaults to **Weak** | How far the runtime trusts Twilio's identity assertion when it links a sender to an existing session. Choose **Strong** only when you base continuity and account-linking decisions on it. |
   | **Initial Status** | Defaults to **Active** | Keep it **Active**. |

4. Select **Create**.

5. Copy the **Webhook URL** from the connection's summary panel. It ends with the encoded number, where a leading plus appears as `%2B`.

***

## Webhook configuration in Twilio

Twilio calls this URL every time the sender receives a message.

1. Confirm the Artemis connection exists and is **Active**. Artemis resolves the connection from the encoded number before it verifies the signature or reads the form body.
2. Open the sender's incoming-message configuration. For a direct number, go to **Phone Numbers** > **Manage** > **Active numbers** and select the number. For a Messaging Service that owns inbound handling, use the service's **Integration** settings.
3. Paste the exact public HTTPS URL into **A message comes in**. Keep the encoded phone-number segment.
4. Select **HTTP POST**, and save. Twilio sends `application/x-www-form-urlencoded` fields including `MessageSid`, `AccountSid`, `From`, `To`, `Body`, `NumMedia`, and any `MediaUrlN`.
5. Keep the public callback URL exact. Twilio signs the full URL plus the sorted form fields with HMAC-SHA1 and the Auth Token. Artemis validates using its configured public Runtime URL, not an internal proxy URL.

Artemis returns HTTP `200` with an empty TwiML response and queues the agent. The agent's reply follows separately through the Messages API.

> [!WARNING]
>
> Proxy rewriting can break signature verification. Configure the Runtime public base URL to the same external URL Twilio calls, and forward `X-Twilio-Signature` unchanged.

### Validation checklist

Work down this list once per connection.

| Validation item | Expected result |
| :- | :- |
| Prepare the sender | Account SID, Auth Token, number, and any Messaging Service come from one account, with compliance complete. |
| Create the Artemis connection | Saved as **Active** with the E.164 number. |
| Configure the webhook | **A message comes in** points at the exact URL, with **HTTP POST**. |
| Send a real SMS | One session and exactly one reply. |

***

## Verify the connection

Artemis doesn't synthesize Twilio requests, so a real SMS is the only end-to-end proof.

1. From an allowed recipient, send a unique SMS to the Twilio number. Confirm Twilio reports a 2xx webhook result and Artemis creates one session.
2. Confirm the agent replies to the original `From` number, from the inbound Twilio number or the configured Messaging Service. The empty TwiML is only an acknowledgement.
3. Send a second message from the same customer to the same Twilio number. Confirm it continues the `twilio_sms:{To}:{From}` session.
4. Send MMS only where the number, destination, and carrier support it. Artemis authenticates downloads from allowed Twilio hosts and applies attachment type and size policy.
5. Repeat with the production sender and a normal recipient. Validate opt-in, opt-out, regional registration, throughput, delivery status, and segmentation costs.

| Input | What to confirm |
| - | - |
| `SMS text` | The agent receives and answers it. |
| `MMS image`, `MMS video`, `MMS audio`, `MMS file` | The download succeeds and the agent processes the file. |

***

## SMS behavior and limits

SMS is plain text with carrier economics attached.

| Area | Behavior |
| - | - |
| Formatting | Plain text only. Markdown, buttons, and rich cards have no SMS equivalent. |
| Length | Carriers split long messages into segments, and each segment bills separately. Unicode shrinks the per-segment character count. |
| Retries | Twilio can deliver the same webhook more than once. Artemis deduplicates on `MessageSid`. |
| Media | MMS depends on the number, destination, and carrier. |
| Compliance | Consent, opt-out keywords, and sender registration apply to every message. |

***

## Security and transport boundaries

One credential does two jobs, and the URL both sides see must match exactly.

* **Signatures**: Inbound requests require `X-Twilio-Signature`. Artemis computes HMAC-SHA1 with the Auth Token, the configured public callback URL, and the sorted form parameters.
* **Signed URL**: Keep HTTPS termination and reverse-proxy host and protocol aligned with the Runtime public base URL.
* **Auth Token**: It protects inbound verification and outbound Basic authentication. Rotate it in Artemis and Twilio as one coordinated change.
* **MMS downloads**: Artemis uses the Account SID and Auth Token, accepts only allowed Twilio hosts, then applies attachment policy.
* **Environments**: Use separate subaccounts or senders, credentials, webhooks, and connections for development and production.

***

## Manage the channel connection

Open a connection from **Deployments** > **Channels** > **Twilio SMS** to manage it. The page has a header, three tabs, and a summary panel on the right.

**Header.** Shows the connection name, its environment badge, its status, and when it last changed. The **...** overflow menu holds the connection-level actions.

**Summary panel.** Stays visible on every tab.

| Field | Description |
| - | - |
| **Channel** and **Connection Type** | Read **Twilio SMS** and **Channel Connection**. |
| **Identifier** | The Twilio phone number this connection routes on. |
| **Credentials** | Reads **Configured** once credentials save. |
| **Webhook URL** | The incoming-message URL for Twilio, with a copy control. |
| **Created** and **Updated** | Date and time of creation and of the last change. |

> [tab] Credentials
>
> Artemis encrypts credentials after you save them. Leave a field blank to keep its current value, or enter a new value to replace it.
>
> | Field | Description |
> | - | - |
> | **Use Auth Profile** | Turn it on, then select a saved auth profile in place of the fields below. |
> | **Account SID** | Replace it if the sender moves to another Twilio account. |
> | **Auth Token** | Replace it as soon as you rotate it in Twilio, because inbound validation and outbound sends both stop until you do. |
> | **Messaging Service SID** | Add it to send through a service, or clear it to reply from the inbound number. |
>
> Select **Save Credentials** to apply your changes.

> [tab] Configuration
>
> Update how the connection behaves. **Twilio SMS Settings** holds the provider-specific fields.
>
> | Setting | Description |
> | - | - |
> | **Display Name** | The label operators see. |
> | **Provider Verification Strength** | How far the runtime trusts Twilio's identity assertion. |
> | **Twilio Phone Number** | Read-only, with a copy control. To serve another number, create a new connection. |
> | **Message template** | The authorization message the connection sends when a tool needs the user to authorize. Keep it short, because SMS renders plain text and long templates split into extra segments. Insert variables from the chips, select **Show more** for the full list, and select **Show preview** to check it. |
> | **Webhook URL** | The incoming-message URL, with a copy control. |
>
> Select **Save Changes** to apply your changes.

> [tab] Deployment
>
> Choose which deployed version answers SMS.
>
> | Setting | Description |
> | - | - |
> | **Environment** | Under **Environment Binding**. Selects which deployed version handles incoming messages. |
> | **Active Deployment** | Shows the bound version and when someone deployed it. |
>
> Select **Save Changes** after you switch the environment.

***

## Troubleshoot connection issues

Most failures trace to the URL, the Auth Token, or the account boundary.

| Symptom | Likely cause | Recommended action |
| - | - | - |
| Connection not found | Wrong URL, number, or inactive connection | Confirm Twilio calls the full URL ending in the encoded E.164 number, the saved identifier has the same leading-plus number, and the connection is **Active**. |
| Webhook returns `401` | Signed URL or Auth Token mismatch | Compare the exact external URL Twilio called with the Runtime public base URL, preserve `X-Twilio-Signature`, and confirm the Auth Token belongs to the same Account SID. |
| Webhook returns `200` but no session appears | Empty payload or queue issue | Send a payload with `MessageSid` and either a non-empty `Body` or `NumMedia` greater than zero, then check queue health. |
| Inbound works but outbound fails | Credentials, ownership, or deployment | Verify the Account SID and Auth Token, sender ownership, destination eligibility, compliance, and that the environment can run. |
| Messaging Service sends from the wrong number or fails | Service or pool mismatch | Confirm the `MG` SID belongs to the same account and the number is in its **Sender Pool**, or clear the SID to reply from the inbound number. |
| SMS works but MMS fails | Media support or policy | Confirm carrier and number support, Twilio media URL access, allowed host, Basic-auth credentials, content type, and attachment size policy. |
| Users receive duplicate replies | Two handlers or retries | Confirm only one number or service handler points at this connection, and account for Twilio retries with `MessageSid` deduplication. |
| Long messages cost or render unexpectedly | Carrier segmentation | Shorten replies, and test representative Unicode and long content for the target countries. |

***

## Twilio reference

Use these pages when you need detail beyond what this article covers.

| Resource | Use it for |
| - | - |
| [Incoming message webhooks](https://www.twilio.com/docs/usage/webhooks/sms-webhooks) | The form fields Twilio posts. |
| [Webhook security](https://www.twilio.com/docs/usage/security) | How Twilio builds the signature. |
| [Messaging Services](https://www.twilio.com/docs/messaging/services) | Sender pools and service-level inbound handling. |
| [A2P 10DLC](https://www.twilio.com/docs/messaging/compliance/a2p-10dlc) | US long-code registration. |

***

**Related articles:**

* [Channels](https://koreai.mintlify.site/agent-platform/channels.md)
* [Set up WhatsApp](https://koreai.mintlify.site/agent-platform/channels/whatsapp)
* [Set up Zendesk](https://koreai.mintlify.site/agent-platform/channels/zendesk)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.