Twilio

Overview

Twilio is a cloud communications platform that enables your Emergent app to send SMS messages, make voice calls, and deliver notifications. This integration is ideal for apps that need to verify users via SMS, send transactional alerts, or implement two-factor authentication.

Note

Twilio charges per message or call. Review Twilio's pricing before implementing SMS or voice features at scale.

Prerequisites

Before integrating Twilio, you'll need:

A Twilio account (sign up here)
A Twilio phone number (purchased from your Twilio console)
Your Twilio Account SID and Auth Token (found in your Twilio console dashboard)

Setting up Twilio in Emergent

Describe your SMS or voice feature

Tell Emergent what you want to build with Twilio. For example:

"Add SMS verification when users sign up - send a 6-digit code to their phone number."
"Send an SMS notification when an order ships, including the tracking number."
"Let users opt in to receive weekly SMS reminders about their appointments."

Obtain your Twilio credentials

If you haven't already, purchase a phone number from Phone Numbers → Buy a Number. This number will be the sender for your SMS messages.

Provide your credentials to Emergent

When Emergent asks, provide your Account SID, Auth Token, and Twilio phone number. The agent will securely configure and wire them into your app.

Implement and test the integration

The agent will set up the required Twilio API calls and publish the changes. Test the SMS or voice functionality and check the Twilio Console logs to verify delivery.

Common use cases

Phone verification

Send a one-time passcode via SMS during signup or login to verify a user's phone number.

Transactional alerts

Notify users of important events - order confirmations, appointment reminders.

Two-factor authentication

Enhance security by requiring an SMS code in addition to a password when users log in.

Marketing campaigns

Send promotional messages to opted-in users. Ensure compliance with local regulations (e.g., TCPA, GDPR).

Example implementation

Below is an example of how Emergent agents might implement an SMS verification flow using Twilio's Node.js SDK:

(The agent writes and wires up this code for you.)

Info

Phone numbers must be in E.164 format (e.g.,

+14155552671

). Emergent agents typically validate and format numbers automatically when you describe your feature requirements.

Testing and debugging

Issue	Solution
Messages aren't being delivered	Verify your phone number is in E.164 format with a country code (e.g., `+1` for US). Check Twilio's console under Logs → Messaging for error codes. Ensure your Twilio account is not in trial mode or has sufficient credit balance. Confirm the recipient's carrier isn't blocking messages (some carriers filter shortcodes or toll-free numbers).
Environment variables not loading	If your app can't read `TWILIO_ACCOUNT_SID` or other variables, ask the agents: "Verify my Twilio environment variables are set correctly." The agents will check your configuration and re-publish if needed.
Rate limiting or throttling errors	Twilio enforces rate limits on message sending. If you're sending high volumes, consider: Queueing messages with a background job processor. Requesting a rate limit increase from Twilio support. Using Twilio's Messaging Services for better throughput.

Best practices

Validate phone numbers before sending to avoid wasted credits on invalid destinations.
Respect opt-outs: Honor unsubscribe requests immediately and maintain a suppression list.
Use short, clear messages: SMS has a 160-character limit (longer messages are split and billed per segment).
Monitor delivery status: Use Twilio webhooks to track delivery, failures, and user replies.
Secure your credentials: Never commit
```
TWILIO_AUTH_TOKEN
```
to version control. Emergent stores environment variables securely for you.

Compliance and regulations

Warning

SMS marketing is subject to legal restrictions in many countries. In the US, you must obtain explicit consent before sending promotional messages (TCPA). In the EU, GDPR requires clear consent and easy opt-out mechanisms.

Always consult legal counsel if you're sending marketing or promotional messages.