Destination type

Twilio SMS Destination

Use Twilio SMS destinations when routed events should become text-message alerts for operators, customers, or test recipients through Twilio Programmable Messaging.

TWILIO_SMSTwilio Messages API for SMSPOSTCommunication

All destination types Destinations docs

For Twilio SMS destinations, FastHook renders the SMS body template, sends through Twilio's Messages API, and stores the Twilio response as delivery attempt evidence.

When to use this destination type

Choose TWILIO_SMS when the receiver target is Twilio Messages API for SMS. Destinations are outbound delivery targets: they do not decide whether a source request should be accepted, and they do not own connection filters or transformations. They own where the final delivery goes and how FastHook should authenticate, pace, disable, and inspect that delivery.

A destination can be reused by multiple connections when several source branches should feed the same receiver. Reuse keeps receiver capacity, credentials, and attempt evidence attached to one destination id.

FastHook dashboard fields

In the dashboard, create a destination, set Destination Type to TWILIO_SMS, then fill the fields below.

From sender

SMS-capable Twilio number, short code, or approved alphanumeric sender ID. Leave blank only when using a Messaging Service SID.

To recipient

Recipient phone number in +E.164 format, or a template value that renders to +E.164.

Message body

Plain SMS body template with FastHook tokens such as {{event_id}}, {{payload.message}}, and {{message}}.

Messaging Service SID

Optional MG... service SID for sender pools, compliance configuration, and Twilio-managed sender selection.

Account SID

Twilio AC... account identifier from Twilio Console or API keys & tokens.

Auth Token

Twilio account auth token from API keys & tokens. Treat it as a secret and rotate it if exposed.

Max delivery rate

Built-in one message per second pacing.

API config fields

The REST API stores destination-specific behavior under config. Use PATCH for focused edits and PUT only when your request contains the full config you want to keep.

config.from

SMS sender in E.164 format, short code, or alphanumeric sender ID. Required unless config.messaging_service_sid is set.

config.to

Required SMS recipient in +E.164 format. Supports FastHook template tokens that render to a phone number.

config.body_template

Required SMS body template. FastHook renders tokens such as {{event_id}}, {{payload.message}}, and {{message}} before sending.

config.messaging_service_sid

Optional Twilio Messaging Service SID starting with MG. Use this when Twilio should choose from a sender pool.

config.auth_type

TWILIO_AUTH_TOKEN.

config.auth.account_sid

Twilio Account SID used in the Messages API URL and Basic Auth username.

config.auth.auth_token

Twilio Auth Token used as the Basic Auth password.

config.rate_limit

Built-in delivery pacing for SMS messages.

config.rate_limit_period

Rate-limit period. Twilio SMS destinations use second.

Twilio SMS destination config

{
  "name": "ops-sms-alerts",
  "type": "TWILIO_SMS",
  "config": {
    "from": "+16824246644",
    "to": "+37120000000",
    "body_template": "FastHook event {{event_id}}\n{{payload}}",
    "messaging_service_sid": null,
    "auth_type": "TWILIO_AUTH_TOKEN",
    "auth": {
      "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "auth_token": "twilio-auth-token"
    },
    "rate_limit": 1,
    "rate_limit_period": "second"
  }
}

Create Twilio SMS destination with cURL

curl -X POST "https://api.fasthook.io/v1/destinations" \
  -H "Authorization: Bearer $FASTHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "ops-sms-alerts",
  "type": "TWILIO_SMS",
  "config": {
    "from": "+16824246644",
    "to": "+37120000000",
    "body_template": "FastHook event {{event_id}}\n{{payload}}",
    "messaging_service_sid": null,
    "auth_type": "TWILIO_AUTH_TOKEN",
    "auth": {
      "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "auth_token": "twilio-auth-token"
    },
    "rate_limit": 1,
    "rate_limit_period": "second"
  }
}'

Authentication

Destination authentication is outbound. It helps the receiver trust or accept FastHook delivery, and it is separate from source authentication that verifies the original webhook producer.

Twilio Account SID and Auth Token
SMS-capable Twilio sender number or Messaging Service
Trial verified recipient and geo permissions for testing

HTTP methods and rate limit

This destination type uses the methods below for delivery attempts. Rate limits apply at the destination boundary, so every connection that targets the same destination shares that capacity.

POST

Rate limit: Locked to 1 request per second.

Delivery behavior

FastHook renders the SMS body per delivery and sends through Twilio's Messages API.
SMS recipients use +E.164 format, for example +37126430246. Rendered template values must become a valid phone number.
There is no WhatsApp Sandbox join code for SMS. Twilio trial accounts can usually send only to verified recipient numbers.
The From sender must be a Twilio SMS-capable number, short code, approved alphanumeric sender ID, or a Messaging Service SID.
A Twilio API 201 response means Twilio accepted the message. Final delivery can still fail later in Twilio message logs.
Twilio SMS destinations are locked to 1 request per second to avoid message bursts.

Setup checklist

Open Twilio Console and copy the Account SID and Auth Token from API keys & tokens.
Use a Twilio phone number that can send SMS, or create a Messaging Service and add one or more SMS-capable senders.
If the account is in trial mode, verify every recipient number in Twilio before sending.
Confirm Messaging Geo Permissions allow SMS to the destination country.
Create a FastHook destination and choose TWILIO_SMS as the destination type.
Set From sender to the Twilio SMS sender, or set Messaging Service SID and leave From sender blank.
Set To recipient to the target phone number, or use a template token that renders to +E.164.
Paste the Twilio Account SID and Auth Token, then connect only SMS-worthy events through filters.

Troubleshooting

Attempts fail with Twilio error 21608.

Trial accounts can send only to verified recipient numbers. Verify the To number in Twilio, upgrade the account, or use a production-approved flow.

Attempts fail with Twilio error 21606.

The From sender cannot send SMS to that To number. Use an SMS-capable Twilio number, short code, alphanumeric sender ID, or Messaging Service configured for SMS.

Attempts fail with Twilio error 21408.

Enable SMS Geo Permissions for the destination country in Twilio Console, then retry.

Twilio returns 201 but the recipient does not see the SMS.

Open Twilio message logs for the message SID and check the final status and error_code. FastHook records the Twilio response body on the attempt.

Attempts fail with authentication errors.

Check config.auth.account_sid and config.auth.auth_token, then rotate the Auth Token if it was exposed or revoked.