Twilio Integration with SmythOS

Need to send automated SMS or WhatsApp messages? Connect Twilio to SmythOS and empower your agents to send transactional notifications, alerts, and messages directly from your workflows.

TL;DR

Securely link your Twilio account to SmythOS using your Account SID and Auth Token. These credentials must be Base64 encoded. Then, use our components to send SMS and WhatsApp messages or manage services like Rate Limits.

List of Twilio Components

Quickly compare Twilio components by what they do and their key I/O. Click any component name to jump directly to its detailed guide.

Component	Action	What it Does	Inputs	Key Outputs	Use Case
Send SMS	Write	Sends a text message to a specified phone number.	required accountSID, twilioPhoneNumber, recipientPhoneNumber, body	messageSID, status	Sending appointment reminders or 2FA codes.
Send WhatsApp Message	Write	Sends a message to a specified WhatsApp number.	required accountSID, twilioWhatsAppNumber, recipientWhatsAppNumber, body	messageSID, status	Sending order confirmations or support updates via WhatsApp.
Create Rate Limit	Write	Creates a new rate limit for a Twilio service.	required serviceSID, description, uniqueName	rateLimitSID	Protecting your services from abuse.
Fetch Rate Limit	Read	Retrieves the details of a specific rate limit.	required serviceSID, rateLimitSID	description, url	Auditing the configuration of a specific rate limit.
List Rate Limits	Read	Retrieves a list of all rate limits for a service.	required serviceSID	rateLimits	Getting an overview of all configured rate limits.
Delete Rate Limit	Write	Permanently deletes a specific rate limit.	required serviceSID, rateLimitSID	Response	Removing an old or unnecessary rate limit.
Create Webhook	Write	Creates a new webhook for a Twilio service.	required serviceSID, webhookUrl, friendlyName	webhookSID	Configuring real-time event notifications.

INFO

Why Integrate Twilio with Your Agent?

Twilio is a leading cloud communications platform. Integrating it with SmythOS allows you to build agents that can communicate with users and systems via SMS and WhatsApp.

• Automated Notifications: Create agents that send real-time SMS alerts for critical system events, new sales leads, or important updates, ensuring immediate notification without relying on email.
• Transactional Messaging: Automatically send order confirmations, shipping updates, or appointment reminders to customers via SMS or WhatsApp for a better customer experience.
• Two-Factor Authentication (2FA): Build a secure login flow where an agent generates a one-time password and sends it to a user's phone via SMS for verification.
• Interactive Workflows: While these components focus on sending, you can build agents that are triggered by incoming messages (via webhooks) to create interactive bots for customer support or information retrieval.

Prerequisites

Before you begin, please ensure you have the following:

• An active SmythOS account. (Sign up here).
• A Twilio account with a provisioned phone number (for SMS) or WhatsApp sender.
• Your Twilio Account SID and Auth Token.

Getting Started With Twilio

The connection between SmythOS and Twilio is configured using your Account SID and Auth Token, which must be Base64 encoded.

Step 1: Get Your Twilio Credentials

1. Log in to the Twilio Console.
2. On your main dashboard, you will find your Account SID and Auth Token. Copy both of them.

Step 2: Base64 Encode Your Credentials

Twilio's API uses Basic Authentication. You need to combine your credentials and Base64 encode them.

1. Combine your credentials into a single string with a colon in between: YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN.
2. Use an online Base64 encoder or a local script to encode this entire string.
3. Copy the resulting Base64 encoded string (e.g., QUMxMjM0NTY...ZmRhNzg5).

Step 3: Store Your Encoded Key in SmythOS Vault

Your encoded key is a sensitive credential. Use the SmythOS Vault to store it securely.

1. In your SmythOS dashboard, navigate to the Vault.
2. Create a new secret and paste your Base64 encoded string as the value. Give it a memorable name, like twilio_base64_auth.
3. For more details, see the Vault Documentation.

Step 4: Configure a Twilio Component

1. In your SmythOS agent graph, drag and drop any Twilio component.
2. Click the component to open its Settings panel.
3. In the authentication field (e.g., Base64 Encoded Credentials), select the secret you saved in the Vault.
4. Your connection is now configured for that component.

Heads-up

You must add the Base64 encoded secret from the Vault to each Twilio component you use. This ensures all your API calls are properly authenticated.

Which Twilio Component Should I Use?

If you need to…	Target	Use this Component	Why this one?
Send a text message to a customer	A phone number	Send SMS	The standard component for sending messages via the cellular network.
Send a message over the internet to a WhatsApp user	A WhatsApp number	Send WhatsApp Message	Specifically for interacting with users on the WhatsApp platform.
Protect a service from too many requests	A serviceSID	Create Rate Limit	The primary method for defining usage rules for your Twilio services.
Remove a previously set rate limit	A rateLimitSID	Delete Rate Limit	The standard way to permanently remove a rate limit configuration.
Set up a URL to receive event data	A serviceSID	Create Webhook	Essential for building interactive, two-way communication agents.

Component Details

This section provides detailed information for each Twilio component.

Send SMS

Sends a text message from your Twilio phone number to a recipient's phone number.

INFO

This component requires Base64 encoded credentials for authentication, as detailed in the Getting Started section.

Inputs

Field	Type	Required	Notes
accountSID	string	Yes	The SID of your Twilio account.
twilioPhoneNumber	string	Yes	Your Twilio phone number in E.164 format (e.g., +15551234567).
recipientPhoneNumber	string	Yes	The recipient's phone number in E.164 format.
body	string	Yes	The text content of the SMS message.

Outputs

Field	Type	Description
messageSID	string	The unique identifier (SID) for the sent message.
status	string	The delivery status of the message (e.g., queued, sending, sent).
Response	object	The full, raw JSON response from the Twilio API.

Use Case

An agent sends a two-factor authentication (2FA) code to a user's phone number when they attempt to log in from a new device.

Send WhatsApp Message

Sends a message from your Twilio WhatsApp number to a recipient's WhatsApp number.

INFO

This component requires Base64 encoded credentials for authentication, as detailed in the Getting Started section.

Inputs

Field	Type	Required	Notes
accountSID	string	Yes	The SID of your Twilio account.
twilioWhatsAppNumber	string	Yes	Your Twilio WhatsApp number, prefixed with whatsapp: (e.g., whatsapp:+14155238886).
recipientWhatsAppNumber	string	Yes	The recipient's number, prefixed with whatsapp:.
body	string	Yes	The content of the WhatsApp message.

Outputs

Field	Type	Description
messageSID	string	The unique identifier (SID) for the sent message.
status	string	The delivery status of the message.
Response	object	The full, raw JSON response from the Twilio API.

Use Case

An e-commerce agent sends an order confirmation and tracking link to a customer via WhatsApp for a more interactive experience.

WhatsApp Templates

To initiate conversations with users, you must typically use a pre-approved WhatsApp Message Template. Direct freeform messages are usually only allowed within a 24-hour window after the user messages you first.

Rate Limit Components

Includes Create Rate Limit, Fetch Rate Limit, List Rate Limits, and Delete Rate Limit. These components manage usage rules for a Twilio Verify service.

INFO

These components require Base64 encoded credentials for authentication, as detailed in the Getting Started section.

Common Inputs

Field	Type	Required	Notes
serviceSID	string	Yes	The SID of the Verify service you are managing rate limits for.
rateLimitSID	string	Varies	The unique ID of a specific rate limit (for Fetch/Delete).
uniqueName	string	Varies	A developer-defined name for a new rate limit (for Create).

Outputs

Field	Type	Description
rateLimitSID	string	(Create) The SID of the newly created rate limit.
rateLimits	array	(List) An array of rate limit objects for the service.
description	string	(Fetch) The description of the specific rate limit.

Use Case

An agent uses Create Rate Limit to ensure that a single user cannot request more than five 2FA codes from a specific Verify service within a 10-minute window, preventing SMS spam and abuse.

Best Practices & Advanced Tips

• Secure Your Credentials: Your Account SID and Auth Token provide full access to your Twilio account. Always store the Base64 encoded string in the SmythOS Vault.
• Use E.164 Format: All phone numbers should be in E.164 format ([+][country code][phone number], e.g., +14155238886). This is the international standard and ensures reliable message delivery.
• Handle Message Status: Twilio messages go through several statuses (queued, sending, sent, delivered, failed). For critical messages, your agent may need to poll the message status using its messageSID to confirm delivery.
• Verify Numbers: To send SMS messages from your Twilio account to a personal number during development, you must first verify that number in your Twilio Console.

Troubleshooting Common Issues

• Error: 401 Unauthorized

  • Cause: The Base64 encoded Account SID:Auth Token string is incorrect or invalid.
  • Solution: Carefully re-create the Account SID:Auth Token string, ensure there are no extra spaces, and re-encode it. Update the secret in your SmythOS Vault.

• Error: 21211 - Invalid 'To' Phone Number

  • Cause: The recipientPhoneNumber is not a valid phone number or is not in the correct E.164 format.
  • Solution: Ensure the recipient's number is correct and formatted with a + and the country code (e.g., +1...).

• Error: 21610 - Unverified 'To' Number

  • Cause: You are trying to send an SMS from a trial Twilio account to a phone number that has not been verified in your Twilio Console.
  • Solution: Log in to Twilio and add the recipient's number to your list of verified phone numbers.

• WhatsApp Message Fails

  • Cause: You may be trying to send a freeform message outside of the 24-hour customer service window, or your WhatsApp sender is not properly configured.
  • Solution: Ensure you are using an approved Message Template if initiating a conversation. Check the status of your WhatsApp sender in the Twilio Console.

What's Next?

You are now ready to build powerful communication workflows with the SmythOS Twilio Integration!

Consider these ideas:

• Build an Agent That...

  • Connects to your calendar. 15 minutes before a meeting, it sends an SMS reminder to all attendees.
  • Powers a password reset flow. A user requests a reset, and the agent generates a secure, one-time code and sends it to their phone via SMS.
  • Monitors an e-commerce platform. When an order ships, the agent sends a WhatsApp message to the customer with their tracking number.

• Explore Other Integrations:

  • Combine Twilio with a database integration like Firestore. When a new user record is created, trigger an agent to send them a welcome SMS.
  • Use an LLM component to generate a personalized message, then use Twilio to send it to a user.
  • For two-way communication, configure a Twilio webhook to trigger a SmythOS agent when an incoming SMS is received. The agent can then process the message and reply.