GuidesReference
BlogUpdatesSlackGitHubConsole

Twilio

How to set up Twilio integration

Suggest Edits

Twilio lets you connect with customers everywhere they want to interact with you, including text messages, emails, phone calls, video, and more.

1467

Meya’s Twilio integration lets you use Twilio in a few ways:

  • As a Send and Receive messaging channel between your customer and a bot or agent
  • As a way for your bot to send SMS messages - useful for things like two-factor auth
  • As a way to verify a phone number

This guide will show you how to add the Twilio integration, use Twilio as a messaging channel and incorporate Twilio components into your bot.

Overview

The Twilio integration enables new components and a messaging channel.

Messaging channel

Twilio can also be used as a messaging channel, like the Orb or Twitter integrations.

📘

Regardless of whether you intend to use the components, the messaging channel, or both, the set up instructions are the same.

Near the end of this guide, we’ll show example flows that use the Twilio components, and an example that uses Twilio as a messaging channel.

Components

meya.twilio.component.message.send component

  • Send a message to a valid phone number
  • Example use-case: the user is interacting with the bot via another messaging integration, like the Orb, but you want to send them an SMS when their order is ready to be picked up.

meya.twilio.component.lookup component

  • Validates a phone number, and returns it in a standardized format, along with additional information about it, if available, such as the carrier.
  • Example use-case: you need to store a user’s mobile number with their profile but want to validate the number is correct before saving it to your CRM

Events

Twilio notify each step of a message exchange, it's possible to take advantage of that to create a more controlled and complete user experience.
You'll need to specify each event that you want to use on the extra_sms_status_events integration setting.
Meya's currently supported events:

  • accepted
  • queued
  • sending
  • sent
  • failed
  • delivered
  • undelivered
  • receiving
  • received
  • read

Adding the Twilio integration

Retrieve Twilio credentials

First, you’ll need to gather your Twilio account SID and API key.

📘

If you’re just testing the integration out and don’t want to send real messages yet, Twilio provides test credentials you can use. See the Test Credentials section below for details.

Live credentials

Login to your Twilio console. In the Project Info box you’ll see your Account SID. Make a note of it as you’ll be using it in the following step.

921

You should also pick which Twilio phone number you’ll be sending the messages from.

Test credentials

If you’re not ready to use your live Twilio credentials, you can use test credentials instead. Here’s how.

📘

If you’re using your Twilio live credentials, you can skip ahead to Add secrets to the vault.

  1. Login to your Twilio console. In the upper right corner, click the gear icon, and choose Settings.
810
  1. In the Test Credentials box, make a note of the Test Account SID.
1255

Create the API key

Navigate to the API key management page. Click the red + button to create a new key. Make sure the type is set to Standard.

1033

Make a note of the API secret and SID values.

Add the secrets to the vault

The vault is used to store secret information that shouldn’t be committed to version control. Let’s store the Twilio credentials there.

  1. In your app’s root folder, open vault.yaml and copy this code into it:
twilio.account_sid: xxx
twilio.api_key_secret: xxx
twilio.api_key_sid: xxx
twilio.phone_number: xxx
twilio.extra_sms_status_events: []

Remember not to store the actual values in your vault.yaml file. Just leave them set to xxx.

  1. Open vault.secret.yaml and copy this code into it:
twilio.account_sid: ACCOUNT_SID
twilio.api_key_secret: API_KEY_SECRET
twilio.api_key_sid: API_KEY_SID
twilio.phone_number: "PHONE_NUMBER"
twilio.extra_sms_status_events: []

Replace the values with your actual Twilio credentials.

📘

If you’re using test credentials, set the phone number to ”+15005550006”. This is a special phone number that will only work with your test credentials.

🚧

Depending on the format of the phone number, you may need to wrap it in quotes to ensure the app interprets it as a string, instead of an integer.

  1. Save these files and upload the new vault secrets using this command in your terminal:
meya vault upload --file vault.secret.yaml

Create the integration

Now that you’ve stored your credentials, you can create the integration using references to the vault.

In your app’s integration folder, create a new file called twilio.yaml and copy this code into it:

type: meya.twilio.integration
account_sid: (@ vault.twilio.account_sid )
api_key_sid: (@ vault.twilio.api_key_sid )
api_key_secret: (@ vault.twilio.api_key_secret )
phone_number: (@ vault.twilio.phone_number )
extra_sms_status_events: (@ vault.twilio.extra_sms_status_events )

Save the file and upload it:

meya format
meya push

Using Twilio as a messaging channel

Let’s create a simple flow to test and make sure users can interact with our app via SMS.

Create a flow

In your app’s flow folder, create a new file called hi.yaml. Copy this code into the file:

triggers:
  - keyword: hi

steps:
  - say: Hello! Great to meet you.

Save the flow, then run these commands in your terminal to upload your changes:

meya format
meya push

Try it out

In your phone’s messaging app, send the word hi as a text message to your Twilio phone number. The app should reply with Hello! Great to meet you.

1467

👍

Great! You’ve set up the Twilio integration and confirmed that users can send and receive SMS messages from your app.

📘

Did you know Twilio supports MMS (i.e. multimedia messages) as well? Check out MMS messages below for more info.

Using the Twilio components

Let’s create a flow that uses the meya.twilio.component.lookup to validate the user’s phone number. Then we’ll use the meya.twilio.component.message.send component to send the message.

Create a flow

In your app’s flow folder, create a file called twilio.yaml and copy this code into it:

triggers:
  - keyword: twilio

steps:
  - (input)
  - ask_form: What mobile number do you want to send to?
    label: Phone
    icon: (@ config.icon.phone )
    placeholder: 'Mobile phone #'
  - flow_set: to

  - (lookup)
  - type: meya.twilio.component.lookup
    integration: integration.twilio
    phone_number: (@ flow.to )
  - if: (@ flow.ok )
    then:
      jump: valid
    else:
      jump: invalid

  - (invalid)
  - say: ❌ Invalid phone number. Try again. (@ flow.status ) -  (@ flow.data )
  - end

  - (valid)
  - flow_set: enriched_phone
  - say: |
      ✅ Valid phone number.
      Formatted: (@ flow.enriched_phone.national_format )
      Country:  (@ flow.enriched_phone.country_code )
    quick_replies:
      - text: Send an SMS

  - (text)
  - ask_form: What message to send?
    label: Message
    icon: (@ config.icon.message )
    placeholder: ex. Hi there!
  - flow_set: body

  - (sms)
  - type: meya.twilio.component.message.send
    integration: integration.twilio
    to: (@ flow.to )
    body: (@ flow.body )
  - if: (@ flow.ok )
    then:
      jump: sent
    else:
      jump: not_sent

  - (not_sent)
  - say: ❌ Something went wrong. No message was sent. (@ flow.status ) -  (@ flow.data
      )
  - end

  - (sent)
  - say: ✅ A text message was sent to (@ flow.enriched_phone.national_format | default(flow.to) )

🚧

Twilio’s lookup API does not work with test credentials. If you’re using test credentials:

  • comment out lines 12 to 33
  • update line 59 to - say: ✅ A text message was sent to (@ flow.to )

Save the file and upload your work:

meya format
meya push

Try it out

Open your app’s simulator in the browser. To trigger the flow, type twilio. When prompted, enter a valid phone number, then a message.

If everything went well, the app will print a message saying the SMS was sent successfully.

480

Results when using test credentials

If you’re using test credentials, Twilio won’t actually send the message. The API will return a successful response, though, as if it had. This means flow.ok will be true and the flow will continue.

You can further verify that everything worked properly by going to your app’s Logs page and filtering the logs to only show entries related to Twilio, like this:

url:*twilio* type:meya.http.entry.response

Verify that the response status was 201. This indicates your message was received by Twilio and would have been sent to the destination phone number if you had been using live credentials (and assuming you used a valid to phone number).

969

MMS messages

The Twilio integration also supports multimedia messages. Here’s an example flow that uses the meya.image.component component to send an image to the user.

triggers:
  - keyword: santa

steps:
  - say: HO HO HO
  - url: https://i.pinimg.com/originals/2c/bf/5d/2cbf5deae8808fb724ffc7efff831b45.jpg
    alt: santa

Here’s the result:

864

📘

If the user’s carrier does not support MMS, the message are sent as an SMS with a shortened URL linking to your media. The shortened URL link (http://m.twil.io/ followed by 6 unique characters) will be appended to the end of the SMS message body.

Troubleshooting

If anything is misconfigured in your Twilio account, Twilio’s API will return an error message explaining what went wrong. You can find these responses in your app’s Log page using this GridQL query:

url:*twilio* type:meya.http.entry.response

For detail on Twilio errors and how to fix them, check out their documentation.

Updated over 2 years ago