Twilio Integration Guide

Text the shift lead when a line stops, ring the on-call engineer when an alarm stays active, and check that the text arrived.

Authentication

API key (recommended) or Auth Token

Operations

Send Message, Make Call, Get Message

API

Twilio REST API 2010-04-01

Send SMS and voice calls from your pipelines through Twilio. This guide covers what you need in your Twilio account, the connection, and each function type.

Overview

The Twilio connector enables you to:

• Send SMS to one or several phone numbers; each number gets its own message and is reported on its own
• Make voice calls that read your text aloud, in the voice and language you choose
• Read a message's delivery status: queued, sent, delivered, undelivered or failed, with Twilio's error code
• Sign in with an API key (Twilio's recommendation, revocable per system) or the account's Auth Token

Executing texts and rings real phones

Send Message and Make Call reach real people and Twilio bills each message segment and each call minute. Test with numbers you own.

Prerequisites

1. Your Account SID. In the Twilio Console, the Account Info panel shows the Account SID (starting AC) and the Auth Token.
2. An API key (recommended). Go to Account → API keys & tokens → Create API key, choose Standard, and copy the key's SID (starting SK) and its Secret; Twilio shows the secret once. A Standard key can use every resource the connector needs. A Restricted key needs read access to phone numbers (and to Messaging Services for the sender picker), plus create access to Messages and Calls. You can use the Auth Token instead, but it cannot be revoked without changing it everywhere.
3. A sender. A Twilio phone number that can send SMS (and make calls, for Make Call), or a Messaging Service (SID starting MG) that holds such numbers. Messaging Services can only send SMS.
4. Messaging Geo Permissions. Under Messaging → Settings → Geo permissions, allow only the countries you text. For calls, the same list is under Voice → Settings → Geo permissions. This is your protection against someone making MaestroHub text or call premium-rate numbers: if a recipient number comes from data you do not control, an attacker who can write that data could otherwise run up charges ("SMS pumping").
5. US numbers: A2P 10DLC registration. Twilio filters texts from US 10-digit long-code numbers that are not registered for A2P 10DLC (error 30034). Register the brand and campaign in the Console, or send through a toll-free or short-code number.

Regions

Twilio credentials belong to one region. An account in a non-US Twilio region uses that region's API key and its API host as the connection's Custom API URL, for example https://api.dublin.ie1.twilio.com.

Connection Configuration

Creating a Twilio Connection

Navigate to Connections → New Connection → Twilio and configure the following:

Zoom

The Twilio connection form

1. Profile Information

Field	Default	Description
Profile Name	-	A descriptive name for this connection profile (required, max 100 characters)
Description	-	Optional description for this Twilio connection

2. Authentication

Field	Default	Description
Account SID	-	Your Twilio Account SID, AC followed by 32 hex digits (required)
API Key SID	-	The SID of a Twilio API key, SK followed by 32 hex digits. Leave empty to sign in with the Auth Token
API Key Secret or Auth Token	-	The API key's secret when an API Key SID is set, otherwise the Auth Token (required, stored encrypted)

3. Sender and Advanced

Field	Default	Description
Default Sender	-	Who messages come from when a function names no sender: a Twilio number in E.164 form (+15017122661), or a Messaging Service SID (MG…). Voice calls need a phone number
Custom API URL	https://api.twilio.com	A Twilio region's API host, or your own egress gateway. Messaging Services are listed from the region's matching messaging. host

Notes

• Required Fields: Profile Name, Account SID and the secret.
• Test Connection lists one of the account's phone numbers (GET …/IncomingPhoneNumbers.json?PageSize=1). It sends nothing and costs nothing. Rejected credentials (Twilio error 20003) fail at once.
• Security: the secret is stored encrypted and masked on edit. Leave the field empty to keep the stored value.

Function Builder

Creating Twilio Functions

After saving the connection:

1. Open the connection and go to its Functions tab → New Function
2. Select Send Message, Make Call or Get Message
3. Configure the function's parameters

Zoom

The Twilio function types

Send Message Function

Purpose: Text one or more phone numbers.

Field	Type	Required	Default	Description
To	List	Yes	-	Phone numbers in E.164 form (+4917612345678), at most 100. Spaces, hyphens, dots and brackets are removed; a number given twice is texted once. A templated value may hold several numbers separated by commas
Message	String	Yes	-	The text, at most 1,600 characters. Over 160 GSM-7 characters (70 when it holds an emoji or a non-Latin letter) it is sent, and billed, as several segments; the form counts them
Sender	String	No	connection's	A Twilio number in E.164 form, an alphanumeric sender ID, or a Messaging Service SID (MG…). Pick one from the account's numbers and services, or type it
Validity Period	Duration	No	15m	How long Twilio may hold the text in its own queue before giving up on it, 1 second to 10 hours. Twilio's own default is 10 hours, too late for most alerts
Timeout	Duration	No	30s	Bound on the whole call, every recipient included

Each number is its own request to Twilio, in the order given. Twilio answers queued (or accepted through a Messaging Service): the text is at Twilio, not yet on the phone. Use Get Message to read whether it was delivered.

Every field is checked before anything is sent: a number that is not E.164, an empty or too long text, no sender on the function or the connection, a Messaging Service SID of the wrong shape, or more than 100 numbers fails the call without contacting Twilio.

What happens when a send fails

Twilio takes no idempotency key, so every accepted request is a new text and a new charge. MaestroHub reports each number on its own:

• A number Twilio refuses for good (invalid, unsubscribed, not allowed by Geo Permissions) fails only that number; the others are still sent.
• A number refused for now (the sender's queue is full, error 21611, or Twilio is throttling, 429) stops the call: the numbers after it are reported not sent.
• When Retry on Fail, a For Each retry or store-and-forward sends the write again, the numbers that already got the text are skipped. The one exception is a number whose request left but whose answer never came back (a timeout): Twilio may have queued it, so it can get the text twice.

Make Call Function

Purpose: Ring one or more phone numbers and read a message aloud.

Field	Type	Required	Default	Description
To	List	Yes	-	Phone numbers in E.164 form, at most 100; one call each
Message	String	Yes	-	What is read aloud when the call is answered, at most 3,000 characters
Caller	String	No	connection's	A Twilio phone number that can make calls. A Messaging Service or an alphanumeric sender ID cannot place calls
Voice	String	No	alice	Twilio's text-to-speech voice: man, woman, alice, or a Polly or Google voice such as Polly.Joanna
Language	String	No	en-US	The language the text is read in, e.g. de-DE. The voice must speak it
Repeat	Number	No	2	How many times the message is read, 1 to 3
Timeout	Duration	No	30s	Bound on the whole call, every recipient included

The message is spoken exactly as written. MaestroHub places it, XML-escaped, inside one fixed <Say> instruction, so text such as <Dial>+1900…</Dial> from a templated value is read out, never run. Raw TwiML is not accepted.

Get Message Function

Purpose: Read what became of a sent message.

Field	Type	Required	Default	Description
Message SID	String	Yes	-	The message's SID, starting SM or MM, as Send Message returns it in result.messages[n].sid
Timeout	Duration	No	30s	Bound on the call

Using Parameters

Use ((parameterName)) in text fields to fill them from pipeline data at run time:

Zoom

Parameters detected in a Send Message function

Field	Supports Templating
To, Message, Sender (Send Message)	Yes
To, Message, Caller, Repeat (Make Call)	Yes
Message SID (Get Message)	Yes
Validity Period, Voice, Language	No

Pipeline Integration

Each function type is a node in the Pipeline Designer: Twilio Send Message, Twilio Make Call and Twilio Get Message. See the Twilio nodes page for their output.

Zoom

Twilio Send Message node

Send Message and Make Call can be buffered by store-and-forward while Twilio is unreachable. Both are time-bounded: set a maximum age on the node so an alert held back by an outage is dropped rather than delivered hours late. The text's Validity Period bounds the time it may then wait at Twilio.

Common Use Cases

Text the shift lead when a line stops

Pipeline Flow:

1. Modbus Read reads the line's running bit
2. Condition routes on running = false
3. Twilio Send Message texts the shift lead

Function Configuration:

To: +4917612345678
Message: Line 3 stopped at ((time)). Reason: ((reason)).
Validity Period: 15m

Escalate to a call when the text was not delivered

1. Twilio Send Message texts the on-call engineer
2. Delay waits five minutes
3. Twilio Get Message with Message SID ((sid)), filled from $node["Twilio Send Message"].result.messages[0].sid
4. Condition on result.status not delivered → Twilio Make Call to the same number

Troubleshooting

Problem	Cause and fix
Test Connection fails with Twilio error 20003: Authenticate (401)	The Account SID, API key SID or secret is wrong, or the key was deleted. With an API key, the secret is the key's secret, not the Auth Token
Test Connection fails with 403	A Restricted API key without read access to phone numbers. Give it that permission, or use a Standard key
Twilio error 21606	The sender is not a Twilio number on this account that can text this destination. Pick a sender from the list
Twilio error 21408 or 21215	The destination country is not enabled in Geo Permissions. Enable it if you mean to text or call there
Twilio error 21610	The recipient replied STOP to this sender. Only they can opt back in, by replying START
Twilio error 21611	The sender's queue is full. The number is reported retryable and is sent again later; send through a Messaging Service to spread the load
The send succeeds but Get Message shows undelivered with 30034	A US 10DLC number without A2P registration. Register it in the Console
Get Message shows undelivered with 30003, 30005 or 30007	The carrier could not deliver: the phone is off or out of coverage (30003), the number does not exist (30005), or the carrier filtered the text as spam (30007)
A call is placed but nothing is said	The voice does not speak the chosen language. Use a voice that does, or the language's default voice