Skip to main content

Connect to Twilio

Learn how to connect to Twilio and send SMS messages, make voice calls, and manage communications in Retool.

Twilio is a cloud communications platform for SMS, voice, and messaging. Connect Twilio to Retool to build customer notification systems, SMS campaigns, voice call interfaces, and communication dashboards.

What you can do with Twilio​

  • Send SMS messages: Send text messages to customers with delivery tracking and status updates.
  • Make voice calls: Initiate and manage voice calls programmatically with call recording and transcription.
  • Manage phone numbers: Provision, configure, and manage Twilio phone numbers for your applications.
  • Track message status: Monitor delivery status, errors, and engagement metrics for SMS and voice communications.
  • Handle incoming messages: Process and respond to incoming SMS messages and voice calls.

Before you begin​

To connect Twilio to Retool, you need the following:

Create a Twilio resource​

Follow these steps to create a Twilio resource in Retool.

1. Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for Twilio and click the Twilio tile to begin configuration.

2. Configure connection settings​

Configure the following connection settings for your Twilio resource.

Resource name and description​

Specify a name for the resource that indicates which Twilio account it connects to. Include a description that can provide more context to users about how to use the resource.

Example NameExample Description
Twilio (production)Production Twilio account for sending customer SMS and voice calls.
Twilio (development)Development Twilio account for testing SMS and voice features.

3. Configure authentication​

Twilio uses Account SID and Auth Token authentication. Provide both credentials to authenticate requests.

Account SID​

Provide your Twilio Account SID. Find your Account SID in the Twilio Console dashboard.

Example
{{ retoolContext.environment.twilioAccountSid }}

Auth Token​

Provide your Twilio Auth Token. Find your Auth Token in the Twilio Console dashboard.

Example
{{ retoolContext.environment.twilioAuthToken }}
Protect API credentials

Store Twilio credentials in configuration variables or Retool secrets rather than hardcoding them in the resource configuration.

When developing and testing with Twilio, use test credentials to avoid charges.

Test vs Production accounts

Twilio provides test credentials for development. Test Account SIDs begin with AC followed by test account identifiers. Always use test credentials during development to avoid incurring charges.

4. Test the connection​

Click Test connection to verify Retool can connect to your Twilio account. A successful test confirms the Account SID and Auth Token are valid and have the necessary permissions.

If the connection test fails, verify:

  • Account SID is correct and matches your Twilio account
  • Auth Token is correct and hasn't been revoked
  • Credentials have the necessary permissions for the operations you plan to perform

5. Save the resource​

Click Create resource to save your Twilio resource. The resource is now available to use in apps, workflows, and agent tools across your Retool organization.

Query Twilio data​

Once you've created a Twilio resource, you can query it in apps, workflows, and agent tools.

Create a query​

To create a Twilio query in a classic app:

  1. In the Retool app IDE, open the Code tab, then click + in the page or global scope.
  2. Select Resource query.
  3. Choose your Twilio resource.
  4. Select the Twilio operation and configure parameters.

Twilio operations​

Twilio queries provide access to common Twilio API operations organized by resource type.

Operation categoryAvailable operations
MessagesSend message, list messages, retrieve message, delete message.
CallsMake call, list calls, retrieve call, update call, delete call.
Phone NumbersList phone numbers, purchase phone number, update phone number, release phone number.
Available NumbersSearch available phone numbers by area code or capabilities.

Query configuration​

Each Twilio operation has specific parameters. Common parameters include:

  • To: Recipient phone number in E.164 format (e.g., +14155551212)
  • From: Your Twilio phone number in E.164 format
  • Body: Message text for SMS messages
  • Url: TwiML URL for voice calls and message responses
  • Filters: Limit results by date, status, or other criteria

Common use cases​

The following examples demonstrate typical Twilio operations in Retool apps.

send an SMS message

First, add a Form component with fields for the recipient number and message body.

Next, create a Twilio query to send an SMS message.

Configure the query:

  • Operation: Send message
  • Parameters:
Example parameters
{
  "to": {{ phoneNumberInput.value }},
  "from": {{ twilioPhoneSelect.value }},
  "body": {{ messageTextArea.value }}
}

Then, add an event handler to the form's Submit event that runs the send message query and displays the delivery status.

Phone number format

Always use E.164 format for phone numbers: + followed by country code and number (e.g., +14155551212 for a US number). Retool can help format numbers using the formatPhoneNumber() helper function.

make a voice call

First, add a Form component with fields for the recipient number and call instructions.

Next, create a Twilio query to initiate a voice call.

Configure the query:

  • Operation: Make call
  • Parameters:
Example parameters
{
  "to": {{ phoneNumberInput.value }},
  "from": {{ twilioPhoneSelect.value }},
  "url": "https://your-app.com/twiml/greeting.xml",
  "statusCallback": "https://your-app.com/webhooks/call-status"
}

Then, add an event handler that runs the query and displays the call status.

TwiML for voice calls

The url parameter should point to a TwiML (Twilio Markup Language) document that defines the call flow. You can host TwiML files on your server or use Twilio's TwiML Bins for simple call scripts.

list and display messages

First, create a Twilio query to list recent messages.

Configure the query:

  • Operation: List messages
  • Parameters:
Example parameters
{
  "pageSize": 100,
  "dateSentAfter": {{ dateRange.value.start }},
  "dateSentBefore": {{ dateRange.value.end }}
}

Next, add a Table component to the app and set its Data property to {{ listMessagesQuery.data }}.

Format the table columns:

  • To/From: Display formatted phone numbers
  • Status: Use status badge formatter to highlight delivered, failed, or pending messages
  • Date Sent: Use timestamp formatter for the dateSent field
search and purchase phone numbers

First, add a Form component with fields to search for available numbers (area code, capabilities).

Next, create a Twilio query to search for available phone numbers.

Configure the query:

  • Operation: Search available phone numbers
  • Parameters:
Example parameters
{
  "areaCode": {{ areaCodeInput.value }},
  "smsEnabled": true,
  "voiceEnabled": true,
  "limit": 20
}

Display the results in a Table component with a Button in each row to purchase the number.

Create a second query to purchase the selected number:

Configure the query:

  • Operation: Purchase phone number
  • Parameters:
Example parameters
{
  "phoneNumber": {{ table1.selectedRow.data.phoneNumber }},
  "friendlyName": {{ friendlyNameInput.value }}
}
track message delivery status

First, create a Twilio query to retrieve message details.

Configure the query:

  • Operation: Retrieve message
  • Message SID: {{ table1.selectedRow.data.sid }}

Next, add a Button component that triggers the query and displays message details including:

  • Delivery status (queued, sent, delivered, failed)
  • Error code and error message (if failed)
  • Price and price unit
  • Number of segments

Use a Modal component to display the detailed message information.

Best practices​

Follow these best practices to optimize performance, maintain security, and ensure data integrity when working with Twilio.

Performance​

  • Cache responses: For data that doesn't change frequently, enable query caching to reduce API calls and improve response times.
  • Use pagination: Implement pagination for endpoints that return large datasets to reduce payload size and improve performance.
  • Batch operations: When available, use Twilio's batch endpoints to combine multiple operations into fewer requests.
  • Set appropriate timeouts: Configure query timeouts based on expected API response times to prevent hung requests.
  • Minimize payload size: Request only the fields you need using query parameters or API-specific field selection features.

Security​

  • Use configuration variables: Store API keys and tokens in configuration variables or Retool secrets rather than hardcoding them.
  • Use HTTPS only: Always connect to APIs over HTTPS to encrypt data in transit and protect authentication credentials.
  • Rotate credentials regularly: Follow your API provider's recommendations for credential rotation and key management.
  • Validate SSL certificates: Keep SSL certificate verification enabled unless absolutely necessary for development environments.
  • Use resource environments: Organizations on an Enterprise plan can configure multiple resource environments to maintain separate configurations for production, staging, and development.
  • Apply least privilege: Use API keys with minimal required permissions. Create separate keys for different environments.

Data integrity​

  • Validate user input: Sanitize and validate all user input before including it in API requests to prevent injection attacks.
  • Handle errors gracefully: Configure error notifications and fallback behavior for failed API calls to improve user experience.
  • Use idempotency keys: For APIs that support idempotency keys (like Stripe), include them in POST/PATCH requests to prevent duplicate operations.
  • Verify responses: Check response status codes and validate response data structure before using it in your app.
  • Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.
  • Log API interactions: Enable query logging to track API requests and responses for debugging and auditing.