Set up Twilio SMS

Back to 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:

Prepare the Twilio project and sender.
Artemis channel configuration: create the connection, then copy its Webhook URL.
Webhook configuration in Twilio: set the number’s incoming-message webhook.
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 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.

Use the project that owns the sender

In the Twilio Console, switch to the project or subaccount that owns the production number and billing. Every value you collect must come from this one account.

Buy or select a messaging-capable number

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

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.

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.

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.

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.

Open Artemis and select the project.
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.

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.

Select Create.
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.

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.
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.
Paste the exact public HTTPS URL into A message comes in. Keep the encoded phone-number segment.
Select HTTP POST, and save. Twilio sends application/x-www-form-urlencoded fields including MessageSid, AccountSid, From, To, Body, NumMedia, and any MediaUrlN.
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.

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.

From an allowed recipient, send a unique SMS to the Twilio number. Confirm Twilio reports a 2xx webhook result and Artemis creates one session.
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.
Send a second message from the same customer to the same Twilio number. Confirm it continues the twilio_sms:{To}:{From} session.
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.
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.

Credentials
Configuration
Deployment

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.

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.

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	The form fields Twilio posts.
Webhook security	How Twilio builds the signature.
Messaging Services	Sender pools and service-level inbound handling.
A2P 10DLC	US long-code registration.

Related articles:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Prerequisites

How Artemis routes Twilio SMS messages

Prepare the Twilio project and sender

Artemis channel configuration

Webhook configuration in Twilio

Validation checklist

Verify the connection

SMS behavior and limits

Security and transport boundaries

Manage the channel connection

Troubleshoot connection issues

Twilio reference

​Prerequisites

​How Artemis routes Twilio SMS messages

​Prepare the Twilio project and sender

​Artemis channel configuration

​Webhook configuration in Twilio

​Validation checklist

​Verify the connection

​SMS behavior and limits

​Security and transport boundaries

​Manage the channel connection

​Troubleshoot connection issues

​Twilio reference

Prerequisites

How Artemis routes Twilio SMS messages

Prepare the Twilio project and sender

Artemis channel configuration

Webhook configuration in Twilio

Validation checklist

Verify the connection

SMS behavior and limits

Security and transport boundaries

Manage the channel connection

Troubleshoot connection issues

Twilio reference