# Twilio

Send SMS, MMS and WhatsApp messages and place calls with Twilio, look up phone numbers, and send and check verification codes.

## Connect Twilio

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `twilio` and choose **Twilio**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **Account SID · Required**: Starts with AC (Console › Account info).
- **Auth Token · Optional**: The account’s Auth Token, which Twilio signs its webhooks with. Optional for steps when an API key is entered.
- **API key SID · Optional**: Starts with SK. Leave empty to use the Auth Token.
- **API key secret · Optional**: The secret shown once when the API key was made.

Enter your Account SID with its Auth Token, or with an API key (SID and secret): Twilio Console › Account › API keys & tokens. An API key is better for production. Twilio signs the webhooks it sends with the Auth Token.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Twilio**. The trigger uses the same connection as the steps.

### On Message Received

Starts a run for each SMS, MMS or WhatsApp message sent to the Twilio number. Publishing points the number's incoming messages at this workflow; unpublishing puts back the address it had. Twilio signs every delivery with the account's Auth Token (the connection must have it); an unsigned or wrongly signed request starts nothing, and a message Twilio sends again starts no second run. A number that already sends its messages elsewhere (other than Twilio's demo reply) is refused unless Take Over is on; a number whose messages go to a Messaging Service or a TwiML App is refused (point that at the workflow's address instead). WhatsApp messages arrive here when the WhatsApp sender uses the number's own message address; a sender with its own webhook (Messaging › Senders) sends them there instead.

- **Phone Number · Required**: The Twilio number whose incoming messages start a run.
- **Take Over · Optional**: If the number already sends its messages to another address, point it here anyway (unpublishing puts that address back). Off by default.

A later step can use its data, such as `{{trigger.Body}}`, `{{trigger.From}}`, `{{trigger.MessageSid}}` and 4 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Twilio

Add a **Twilio** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Message (SMS, MMS, WhatsApp)](https://docs.gorunner.io/apps/twilio#fields-f-sms): Send · Get · Get Many · Cancel Scheduled · Delete
- [Call](https://docs.gorunner.io/apps/twilio#fields-f-call): Make · Get · Get Many · End · Delete
- [Phone Number Lookup](https://docs.gorunner.io/apps/twilio#fields-f-lookup): Look Up
- [Verification Code](https://docs.gorunner.io/apps/twilio#fields-f-verify): Send Code · Check Code

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Twilio can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Twilio says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Twilio is `pieceId: "twilio"` with `actionId: "twilio"`, set by `resource` and an `operation_…` field, such as `operation_call`. Its trigger is `twiliotrigger` / `twilio_message`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Twilio › Message (SMS, MMS, WhatsApp)

### Send

- **From · Optional**: The Twilio number (or WhatsApp sender) it is sent from. Empty when a Messaging Service is set below.
- **To · Required**: The recipient's number in E.164 form, such as +4915112345678 (or whatsapp:+4915112345678).
- **Send via WhatsApp · Optional**: Send it on WhatsApp through Twilio (both numbers get whatsapp: in front, once). Off by default.
- **Message · Optional**: The text, up to 1,600 characters (an SMS over 160 GSM characters is sent and billed in parts). Optional with media or a content template.
- **Media URLs · Optional**: Up to 10 public addresses of images or files to send (MMS or WhatsApp), one per line.
- **Messaging Service SID · Optional**: Send through a Messaging Service (MG…): it picks the sender, and is needed to schedule a message.
- **Content Template SID · Optional**: A Content Template (HX…) to send instead of the text: WhatsApp requires an approved template outside the 24-hour reply window.
- **Template Variables · Optional**: The template's variables, such as {"1": "Ada", "2": "Friday"}.
- **Send At · Optional**: Schedule the message (15 minutes to 35 days ahead; needs a Messaging Service). Empty: send now.
- **Status Callback URL · Optional**: An address Twilio tells about each status change (sent, delivered, failed).
- **Give Up After (seconds) · Optional**: How long Twilio keeps trying to deliver it (1–36,000 seconds). Empty: 36,000.

### Get, Cancel Scheduled and Delete

- **Message SID · Required**: The message's SID (SM… or MM…).

### Get Many

- **To · Optional**: Only messages sent to this number.
- **From · Optional**: Only messages sent from this number.
- **Sent On Or After · Optional**: Only messages sent on or after this day (UTC).
- **Sent On Or Before · Optional**: Only messages sent on or before this day (UTC).
- **Return All · Optional**: Read every message, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many messages to return (1–5000). Default: 50. Shows when **Return All** is off.

### Twilio › Call

### Make

- **From · Required**: The Twilio number (or verified caller ID) the call comes from.
- **To · Required**: The number to call in E.164 form, such as +4915112345678 (or client:name, sip:…).
- **Message Is TwiML · Optional**: Off: the message is read out to the person who answers. On: the message is TwiML that runs the call. Off by default.
- **Message · Required**: What is said, or the TwiML (\<Response>…\</Response>, at most 4,000 characters).
- **Voice · Optional**: The voice that reads the message, such as Polly.Joanna or Google.de-DE-Standard-A. Empty: Twilio's default. Shows when **Message Is TwiML** is off.
- **Language · Optional**: The language it is read in, such as en-US or de-DE. Shows when **Message Is TwiML** is off.
- **Status Callback URL · Optional**: An address Twilio tells when the call is answered and ends.
- **Record · Optional**: Record the call. Off by default.
- **Ring For (seconds) · Optional**: How long it rings before giving up (5–600). Empty: 60.
- **Detect Voicemail · Optional**: Find out whether a person or a machine answered (billed). Empty: off. Options: Detect a machine, Wait for the voicemail greeting to end.

### Get, End and Delete

- **Call SID · Required**: The call's SID (CA…).

### Get Many

- **To · Optional**: Only calls to this number.
- **From · Optional**: Only calls from this number.
- **Status · Optional**: Only calls in this state. Options: queued, ringing, in-progress, canceled, completed, failed, busy, no-answer.
- **Return All · Optional**: Read every call, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many calls to return (1–5000). Default: 50. Shows when **Return All** is off.

### Twilio › Phone Number Lookup

### Look Up

- **Phone Number · Required**: The number, in E.164 form (+4915112345678) or national form with a Country below.
- **Country · Optional**: For a number in national form: its country (ISO code, such as DE). Empty: US.
- **Data Packages · Optional**: Extra data to look up: each is billed by Twilio. Empty: the free check (valid, E.164 and national format, country). Options: Line type (mobile, landline, VoIP), Caller name (US), SMS pumping risk, SIM swap, Call forwarding, Line status, Reassigned number (US), Identity match, Quality score, Pre-fill, Validation details.

### Twilio › Verification Code

### Send Code

- **Verify Service · Required**: The Verify Service (VA…) that sends and checks the codes (Twilio Console › Verify › Services).
- **To · Required**: The phone number (E.164) or email address the code goes to.
- **Channel · Optional**: How the code is sent. Options: SMS, WhatsApp, Voice call, Email (needs an email integration on the service). Default: SMS.
- **Language · Optional**: The language of the message, such as de or en-GB. Empty: from the number's country.

### Check Code

- **Verify Service · Required**: The Verify Service (VA…) that sends and checks the codes (Twilio Console › Verify › Services).
- **To · Required**: The phone number (E.164) or email address the code goes to.
- **Code · Required**: The code the person typed (4–10 characters).

Source: https://docs.gorunner.io/apps/twilio