Overview
Twilio is gaiia's SMS delivery provider. Once the integration is installed, gaiia uses it to send every outbound SMS — system communications, mass communications, work order notifications and any SMS sent from a workflow — and reports the delivery outcome of each message back into the notification history.
This article covers what you need from Twilio, how to install the integration in gaiia, and how to read delivery failures.
Before you start
You need a Twilio account and a phone number that is provisioned for SMS. If you don't have an account yet, create one at twilio.com.
Collect the following three values — they are the only things gaiia asks for:
| Value | Where to find it in Twilio |
|---|---|
| Account SID | Account Info panel on your Twilio Console dashboard. |
| Auth Token | Account Info panel on your Twilio Console dashboard. Treat it like a password. |
| Sender number | The Twilio phone number messages will be sent from. It must already exist in your Twilio console with SMS capability enabled. |
In the United States, sending SMS from a 10-digit long code to a US recipient requires A2P 10DLC registration with Twilio before the number can be used by an application like gaiia. Unregistered traffic is filtered by the carriers, not by gaiia. Complete Twilio's registration process first.
Twilio offers several number types, each with different throughput, cost and registration requirements. Review the options before you buy a number:
Installing the integration in gaiia
Installing an integration requires the Admin > Integrations > Edit permission.
- In gaiia, go to Settings > Integrations > App Directory.
- Find Twilio and start the installation.
-
Enter your Account SID, Auth Token and Sender number. All three are required.
Your Auth Token is encrypted at rest and is never displayed again after installation. The sender number stays visible so you can confirm which number is in use.
- Save the integration.
gaiia registers its own status callback with Twilio as part of the installation. You do not need to configure a webhook URL in the Twilio console yourself.
Validating the integration
Send a test SMS to a number you control — a quick way is a mass communication targeted at a single test account — then open that account's Communications tab. A successfully delivered message moves to a “Delivered” state once Twilio confirms it.
How delivery status is reported
Twilio calls gaiia back as each message progresses, and gaiia records the outcome against the message in the notification history. Every callback is signature-verified, so a spoofed status update is rejected rather than recorded.
Three outcomes are recorded:
- “Delivered” — the carrier confirmed handset delivery.
- “Failed” — Twilio could not send the message.
- “Undelivered” — Twilio sent the message but the carrier did not deliver it.
For the last two, gaiia stores the Twilio error code alongside a plain-language explanation.
Common Twilio error codes
These are the codes gaiia translates for you in the notification history. Anything outside this list is recorded with its raw Twilio code.
| Code | Meaning | What it usually indicates |
|---|---|---|
| 11200 | HTTP retrieval failure | A callback endpoint could not be reached. Usually transient. |
| 12300 | Invalid Content-Type | A malformed response to a Twilio request. |
| 21617 | The concatenated message body exceeds the 1600 character limit | The rendered template is too long. Shorten the template or the merge tag values feeding it. |
| 30003 | Unreachable destination handset | The phone is off, out of coverage, or the number is no longer in service. |
| 30005 | Unknown destination handset | The number does not exist. Check the contact details on the account. |
| 30006 | Landline or unreachable carrier | The number cannot receive SMS. Collect a mobile number for this contact. |
| 30007 | Message filtered | The carrier blocked the message. Most often a registration or content-compliance problem — confirm your A2P 10DLC registration is complete and in good standing. |
| 30008 | Unknown error | No reason supplied by the carrier. Retry, and escalate to Twilio if it persists. |
| 30032 | Toll-Free Number Has Not Been Verified | You are sending from an unverified toll-free number. Complete Twilio's toll-free verification. |
Codes 30003, 30005 and 30006 describe the recipient's number, not your configuration. A cluster of them points at contact data quality rather than at the integration.
Twilio publishes the full list in its error and warning dictionary.
Customer opt-outs
Customers can opt out of SMS communications, and that preference is honoured before a message is ever handed to Twilio. See How to Opt-in/Out of SMS Communications.
Related to