Skip to main content

SMS via Twilio

Sending and receiving SMS with every phone on the planet.

This document provides a step-by-step guide to integrate a Twilio SMS source with your Airy Core Platform instance.

The Twilio SMS source provides a channel for sending and receiving SMS using the Twilio API.

What you will learn
  • The required steps to configure the Twilio SMS source
  • How to connect a Twilio SMS source to Airy Core
note

The SMS via Twilio source is not enabled by default.

You need to add configuration in your airy.yaml file and apply it to activate it.

Configuration#

Twilio is a communication platform specialized in phone services. Airy Core supports Twilio as a provider of 2 different sources: Twilio WhatsApp and Twilio SMS. The Twilio provider requires the following configuration:

Let's proceed step by step.

First, to connect a Twilio provider to your Airy Core instance, you must have a Twilio account and a phone number. If this is not your case: head over to Twilio's website, create an account and buy a phone number.

Step 1: Find the authToken and accountSid#

Once you have a Twilio account, log in and find your Twilio auth token account SID on your Twilio dashboard (underlined in red in the screenshot below).

https://www.twilio.com/console
Twilio token

Copy and paste your Auth token and Account Sid as strings next to authToken: and accountSid:, below components/sources/twilio in your airy.yaml file.

Make sure the Auth token and Account Sid are contained within a pair of either single quotation marks '' or double quotation marks "" and paste the tokens as they are (do not add or remove additional spaces).

note

Refer to the Configuration Docs on how to input these values.

Step 2: Configure the webhook integration#

After editing the airy.yaml file, create an Airy Core instance.

You are now ready to configure the Webhook.

On the Twilio dashboard, open the left menu sidebar and go to the Phone numbers section.

Select the phone number that you want to use and copy and paste your Twilio Webhook URL as the Webhook URL of your phone number (in 'Messaging', below 'A MESSAGE COMES IN' - 'Webhook' should be selected from the dropdown).

https://www.twilio.com/console/phone-numbers
Twilio webhook

note

Your Twilio Webhook URL should have the following format:

https://your-public-fqdn/twilio

or if you are using Ngrok:

https://RANDOM_STRING.tunnel.airy.co/twilio

Success! You are now ready to connect a Twilio.SMS source to your Airy Core instance πŸŽ‰

Connect a Twilio provider to your instance#

There are 2 options to connect a Twilio.SMS source to your instance:

  • you can connect the source via an API request (using curl or platforms such as Postman)
  • you can connect the source via the UI

We cover both options in this document.

Connect a Twilio.SMS source via API request#

You connect connect a Twilio.SMS source by sending a request to the Channels endpoint.

Channels endpoint

Connect a Twilio SMS source to your Airy Core instance through the Channels endpoint


POST /channels.twilio.sms.connect
  • phone_number The phone number as listed in your Twilio dashboard. It must not contain spaces and must include the country code.
  • name is the custom name for the connected phone number
  • image_url is the custom image URL

Sample request

{
phone_number: '+491234567',
name: 'SMS for receipts',
image_url: 'https://example.com/custom-image.jpg', // optional
}

Sample response

{
id: 'channel-uuid-1',
metadata: {name: 'SMS for receipts', image_url: 'https://example.com/custom-image.jpg'},
source: 'twilio.sms',
source_channel_id: '+491234567',
connected: true,
}

Connect a Twilio.SMS source via the UI#

You can connect a Twilio.SMS source via your Airy Core instance UI.

On your instance's Airy Core UI, click on 'Channels' on the left sidebar menu and select the SMS channel. Add your Twilio phone number in the Twilio Phone Number field. You can optionally add a name and an image.

TwilioSMS connect

Your twilio.sms channel will appear as connected in the UI.

Make sure the variables have been successfully applied to your instance, otherwise you won't be able to connect the Twilio SMS channel through the UI.

note

Refer to the Configuration Docs on how to input these values.

Send and receive messages with the Inbox UI#

After connecting the source to your instance, it's time to create a conversation between your Airy Core instance, and a Twilio.SMS source.

Send a text message (SMS) from a mobile phone to the Twilio phone number you have used. This will create a conversation: a Twilio.SMS conversation will appear in the UI with the text message you have sent.

If the channel has been successfully connected, but the message you sent does not appear in a conversation and a conversation is not created, please see below for debugging advice.

note

If you encounter errors, please follow this debugging advice:

  • make sure that the authToken and accountSid tokens you have added to the airy.yaml file (refer back to step 1) have been applied to your Airy Core instance. An Airy Core instance should be created after editing the airy.yaml file.

  • verify your webhook integration (refer back to step 2). Make sure that your Twilio Webhook URL has been correctly added to your phone number in your Twilio dashboard (check for typos). The Webhook URL should be added in the 'Messaging', 'Incoming Message' section.

  • check the messaging logs in your Twilio dashboard (see screenshot below): select your phone number from the phone numbers list, click on the Messaging Logs tab, and select Incoming from the dropdown. The error codes from the logs are precious hints of API errors' causes.

https://www.twilio.com/console/phone-numbers/instance/INSTANCE_STRING
Twilio webhook

Once a conversation has been successfully created, you will be able to send messages through the Messages endpoint.

Messages endpoint

Send messages to your Airy Core instance from different sources through the Messages endpoint


Sending a text message

{
"conversation_id": "a688d36c-a85e-44af-bc02-4248c2c97622",
"message": {
"Body": "Hello World"
}
}

Sending media

To send media you need to enable MMS for your phone number.

{
"conversation_id": "a688d36c-a85e-44af-bc02-4248c2c97622",
"message": {
"MediaUrl": "https://picsum.photos/"
}
}
Last updated on