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.

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: Configuration​

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.

Configure the webhook integration​

After editing the airy.yaml configuration 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 🎉

Step 2: Connect a Twilio provider to your instance​

There are 2 options to connect this connector's channel to your instance:

  • you can send an API request (using curl or an API platform such as Postman)
  • you can use the Control Center UI to connect and manage the channel in just a few clicks

We cover both options in this section.

Connect Twilio.SMS via API request​

You connect connect a Twilio.SMS channel 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 Twilio.SMS via the UI​

You can connect a Twilio.SMS channel via your Airy Core instance Control Center 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.

On your instance's Control Center, click on 'Catalog' on the left sidebar menu and select 'SMS'.

This will open a page with a form.

TwilioSMS connect

Add your Twilio phone number in the Twilio Phone Number field.

You can optionally add a name and an image. The display name will be used as the conversation's name while the image URL will be used as its icon in the Inbox UI's messenger. A fallback image will be used if you do not enter a valid image URL.

Upon successful connection, Twilio SMS will appear as connected in the Connectors page in your app's Control Center.

You can edit its configuration at any time by selecting 'SMS' in the list.

Step 3: 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 instantly in the Inbox UI's messenger 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