Twilio SMS

Datafly Signal sends transactional SMS through the Twilio Programmable Messaging API (the Messages resource) server-to-server. When a Signal conversion event fires (for example, Order Completed), Signal sends a real outbound SMS to the customer’s phone number. No client-side code is involved, and the customer’s phone number never leaves your infrastructure except in the call to Twilio.

⚠️

Twilio SMS is a send side-effect, not an analytics pixel. Every delivered event sends a real, billed SMS. Keep your event mapping tight (only the events you intend to send on) and test on a small audience first.

Prerequisites

Before configuring Twilio SMS in Signal, you need a Twilio account and a sender.

Create a Twilio account

Sign up at twilio.com. Trial accounts can only send to verified phone numbers — upgrade to a paid account before sending to real customers.

Find your Account SID and Auth Token

Open the Twilio Console. On the dashboard you will see your Account SID (starts with AC) and your Auth Token. These are your API credentials.

Provision a sender

Choose one of:

A Twilio phone number — buy one under Phone Numbers > Manage > Buy a number, with SMS capability enabled.
A Messaging Service — create one under Messaging > Services. A Messaging Service can pool multiple numbers, short codes, and Alphanumeric Sender IDs, and centralises geo-matching and delivery settings. Note its SID (starts with MG).

(Optional) Register for compliance

For US A2P traffic, register your brand and campaign (A2P 10DLC) under Messaging > Compliance. For other regions, check Twilio’s sender-ID and regulatory requirements for your destination countries.

Configuration

Field	Required	Description
`account_sid`	Yes	Your Twilio Account SID (starts with `AC`). Used as the HTTP Basic username and in the API path.
`auth_token`	Yes	Your Twilio Auth Token. Used as the HTTP Basic password.
`from`	One of `from` / `messaging_service_sid`	A Twilio phone number (E.164), short code, or Alphanumeric Sender ID to send from.
`messaging_service_sid`	One of `from` / `messaging_service_sid`	A Messaging Service SID (starts with `MG`). Use instead of `from` for sender pools and centralised settings.
`default_message`	Recommended	The SMS text sent when an event does not map its own message body. Up to 1,600 characters.
`status_callback`	No	HTTPS URL Twilio calls with asynchronous delivery-status updates.

Provide either from or messaging_service_sid, not both. If both are set, the Messaging Service takes precedence.

Configure in Signal

Go to Integrations > Add Integration > Twilio SMS.
Select the Default preset.
Enter your account_sid and auth_token.
Enter a sender — either from or messaging_service_sid.
Enter a default_message (e.g. “Thanks for your order! Your purchase is confirmed.”).
Select consent categories (typically marketing) — see Consent below.
Click Save.

API Endpoint

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json

Authentication is HTTP Basic: the username is your Account SID and the password is your Auth Token. The request body is application/x-www-form-urlencoded. A successful send returns HTTP 201 Created with the Message resource as JSON.

Identity Signals

Twilio SMS is delivery-by-phone-number — the recipient is identified directly, not matched probabilistically. Signal takes the recipient from the user’s identify traits:

Signal	Twilio field	Handling
`phone`	`To`	Normalised to E.164 (digits with country code, e.g. `+447700900123`). Not hashed — Twilio needs the real number to deliver the message.

Call datafly.identify() with a phone number before the triggering event fires:

datafly.identify("user-123", {
  phone: "+44 7700 900123"
});

Signal trims and normalises the number to E.164 before sending it to Twilio as the To parameter.

⚠️

The phone number must include a country code so it can be normalised to E.164. Numbers without one are rejected by Twilio with error 21211 (Invalid ‘To’ Phone Number).

Event Mapping

The Default preset sends one SMS on the Order Completed event. All other events are dropped, so the integration never sends an unintended message.

Signal event	Twilio action
`Order Completed`	Sends an SMS to `To` (the identified phone) with the configured `default_message`, or a per-event `Body`.

The message body resolves in this order:

A Body mapped on the event (from properties.sms_body) — use this to personalise per order.
Otherwise the integration’s default_message config value.

Example: Order confirmation SMS

Datafly.js call:

datafly.identify("user-123", { phone: "+44 7700 900123" });
 
datafly.track("Order Completed", {
  order_id: "ORD-001",
  sms_body: "Thanks! Order ORD-001 is confirmed and on its way."
});

Twilio request sent by Signal (form-encoded body):

POST https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Messages.json
Authorization: Basic <base64(AccountSid:AuthToken)>
Content-Type: application/x-www-form-urlencoded

To=%2B447700900123&From=%2B14155551234&Body=Thanks%21+Order+ORD-001+is+confirmed+and+on+its+way.

If you do not map sms_body, Signal uses your configured default_message for the Body instead.

To send on other events (e.g. Signed Up, Order Refunded), add them to the integration’s event mapping in the Management UI and map an appropriate Body.

Twilio has no consent field in its API. Signal gates delivery using the integration’s consent categories — set the category to marketing so a message is only sent when the user has granted marketing consent.

⚠️

SMS is a regulated channel. You are responsible for obtaining prior express consent where required (TCPA in the US, PECR/GDPR in the UK/EU, and equivalent rules elsewhere), honouring opt-outs (STOP), and meeting Twilio’s messaging policy and any A2P registration requirements for your destination countries.

Testing Your Integration

Use a verified number (trial accounts)

On a trial account, add your own phone number under Phone Numbers > Verified Caller IDs and use it as the test recipient. Trial sends to unverified numbers return error 21608.

Trigger the event

Fire Order Completed from your test site with an identified phone number. Within a few seconds the SMS should arrive.

Check the Twilio Console

Open Monitor > Logs > Messaging in the Twilio Console. You should see the outbound message with status queued → sent → delivered. Click a message to inspect the body, sender, and any error code.

(Optional) Watch delivery callbacks

If you configured status_callback, confirm your endpoint receives the asynchronous status updates (sent, delivered, failed, undelivered).

Troubleshooting

Problem	Solution
`401 Unauthorized`	Check the Account SID and Auth Token. The SID is the Basic username, the token is the password.
Error `21211` (Invalid ‘To’)	The phone number is not valid E.164. Ensure the identify trait includes a country code.
Error `21608` (unverified number)	Trial account sending to an unverified number. Upgrade the account or verify the recipient.
Error `21603` (no From / Messaging Service)	Set either `from` or `messaging_service_sid` in the integration config.
Blank message / no Body	Set `default_message`, or map a `Body` on the event. A message with no body and no media is rejected.
`429 Too Many Requests`	You exceeded Twilio’s send rate (long codes default to ~1 msg/s). Use a short code or Messaging Service for higher throughput.
Messages not sending at all	Confirm the event is enabled in the mapping and that marketing consent is granted (Signal drops the event otherwise).

Rate Limits

Twilio enforces per-sender send rates. Long codes default to roughly 1 message per second; short codes and Messaging Services support higher throughput. Signal applies a conservative per-integration rate limit by default to avoid Twilio 429 errors; raise it for high-throughput senders.

Mailchimp Brevo