Start text conversations using Proactive SMS Campaigns

Overview

The Proactive SMS Campaign feature allows you to start personalized two-way conversations using Short Message Service (SMS) messages.

Requirements

To use Proactive SMS Campaigns you need to have:

• Ada’s SMS channel

• A Twilio account

About Twilio accounts

• There is no cost for setting up a Twilio account, although there is a monthly cost per phone number. This cost varies based on client region and the type of phone number (Local Number, Toll-Free Number, Short Code).

• There is a cost per SMS message segment sent and received via Twilio. SMS pricing is based on the destination, type of message sent, and the carrier receiving the SMS. Consult Twilio’s SMS Pricing page for pricing details.

• Before sending SMS messages with your bot and Twilio account, it is your responsibility to ensure that you are complying with all relevant laws and regulations in your region. For more information, see SMS Guidelines at Twilio’s documentation.

Create a new Proactive SMS Campaign

To setup a new Proactive SMS Campaign:

1. On the Ada dashboard, go to Build > Campaigns.

2. Click New Campaign. The Create a new Campaign dialog appears.

3. Click the Choose a channel drop-down menu, then select SMS from the list.

4. Add a Name and Description to the corresponding dialog fields.

5. Click Next. The dialog disappears to reveal your new Campaign’s configuration settings.

Configure a new Proactive SMS Campaign

There are a few configuration options available for your Proactive SMS Campaign. Let’s look at how to set them up.

Campaign content

Campaign content is the messaging for your Campaign. There are two parts to Campaign content:

• The Answer sent via SMS to your customers.

• The unsubscribe message appended to the end of your Proactive SMS Campaign Answer.

To define the Campaign’s content:

1. Click the Choose an Answer drop-down menu, then select an Answer from the list. If an appropriate Answer does not yet exist, click Create a new Answer.

2. Review the unsubscribe messaging appended to your first SMS message of the Campaign. If your bot has multilingual functionality, you can view the translated versions by selecting a language from the drop down menu of enabled languages.

Use variables in Proactive SMS Campaign content

A variable is like a container for storing data. Think of a variable as a placeholder for information that can be unique to each person who interacts with your bot.

You can use existing variables, or create new ones, to use in your Proactive SMS Campaign Answers. There are two ways to create a variable for use in a Proactive SMS Campaign Answer:

• Test Webhook Call - Complete a test call to the Proactive SMS Campaign webhook, and include the metadata used to create new variables. Send this test call to a test phone number. This test call creates the variables in Ada that are then available to use in Proactive SMS Campaign Answers. More on triggering Proactive SMS Campaigns with webhooks in the next section.

• Test Send to List of Customers - Manually enter or upload a CSV with test phone numbers and metadata content for variables. This test send creates the variables in Ada that are then available to use in Proactive SMS Campaign Answers. More on triggering Proactive SMS Campaigns by sending to a list of customers in the next section.

Confirm compliance

Prior to sending a Proactive SMS Campaign you must confirm that you are complying with all relevant laws and regulations in your region. This includes, but is not necessarily limited to:

• Obtaining customer consent to send a proactive SMS message.

• Ensuring SMS messages are only sent at permitted times.

  Scheduling is not available for Proactive SMS Campaigns.

  • Once you save a Campaign, the Proactive SMS Campaign API will immediately trigger the SMSwhen called.
  • Phone numbers on the uploaded CSV will automatically be sent the Proactive SMS Campaign content when you confirm the send.

  It is your responsibility to ensure you are only triggering Proactive SMS Campaigns during the permitted hours of the recipient’s region based on their area code.

To confirm compliance, click the checkbox, then click Save. You can now send your Proactive SMS Campaign to your customers.

Campaign triggers

Campaign triggers define the parameters in which the Proactive SMS Campaigns are sent to your customers.

Trigger via the Proactive SMS Campaign API

Use the Proactive SMS Campaign API to trigger your SMS Campaign to send.

With this API, you can use events from external systems to initiate real-time notifications, such as:

• Order updates
• Drip campaigns
• Travel updates
• Account notifications or alerts

Note that you can only trigger an SMS-based campaign for one recipient per API call. Use the Send to a list option in the dashboard to send SMS messages to multiple recipients at a time.

Setting up your API Call

To trigger a Proactive SMS Campaign to send, make POST calls to this endpoint, replacing {bothandle} with your AI Agent’s handle.

https://{bothandle}.ada.support/api/campaigns/sms/trigger

Payload Configuration

Here’s a payload example for the call:

{
  "campaign_key": "renew_subscriptions",
  "language": "en",
  "recipient": {
      "meta_fields": {
        "phone_number": "4165551234",
        "first_name": "Sam"
      }
    }
}

Request Body Parameters

Please use these fields for your payload. If it contains any additional fields, your AI Agent will ignore them:

Headers

You will need to generate an Ada API key to use as a token to authenticate your requests made to the Proactive Campaign API.

Use the API key in the format: Bearer <key>

Example: Bearer 2926a1304ce6b5ff29c1e7ed9b0bcee6

Responses

These are the responses that you may receive after your call was sent. To trouble shoot error responses, please first check the returned response.

Rate Limiting

The Proactive SMS Campaign API limits are the following:

• 30,000 proactive SMS sends/day

Send to a list of customers

Proactive SMS Campaigns can also be sent to a list of customer phone numbers by way of manually entering the phone numbers or uploading a CSV file.

To send to a list of customers by manually entering phone numbers:

1. Click Send to a list.

2. Click in the Campaign recipients field.

3. Manually enter the phone numbers and metadata to create or use variables.

   1. The first row contains the column headers. phone_number, followed by any variable names, each separated by commas.
   2. Additional rows contain the content. The phone number (including country code), and any variable content, each separated by commas.

   phone_number,first_name,last_name
   15551234567,Jane,Doe
   15557654321,John,Doe
   15559876543,Jimmy,Doe

4. Click in the What language should we send this Campaign in? field. Select the language for this Proactive SMS Campaign send. By default, it will be sent in English.

   A Proactive SMS Campaign can only be sent out in one language per send.

5. When you are ready to send, click Send to these customers.

6. Click Yes, send the Campaign to send the Campaign Answer to the provided phone numbers in real time.

To send to a list of customers via CSV upload:

1. Create a CSV of customer data.

   1. Column A must contain phone numbers with the header label phone_number. Each phone number is a new row.
   2. Include the area code. If there is no country code provided, Ada will assume it is a US or Canadian number and assign it the country code of +1.
   3. Additional columns contain metadata used to create Ada variables that can be used in Proactive SMS Campaign Answers.
   4. The header label is the name you want to give the variable in your Ada dashboard (e.g., flight_number or first_name). It is not case sensitive and cannot include spaces.

      Each unique variable is a new column.

   phone_number	first_name	last_name
   15551234567	Jane	Doe
   15557654321	John	Doe
   15559876543	Jimmy	Doe

2. Click Send to a list.

3. Click Upload a CSV.

4. Select the CSV file from the pop up window.

5. Click Upload.

6. Review the list of the phone numbers and metadata for each phone number.

7. Click in the What language should we send this Campaign in? field. Select the language for this Proactive SMS Campaign send. By default, it will be sent in English.

   A Proactive SMS Campaign can only be sent out in one language per send.

8. When you are ready to send, click Send to these customers.

9. Click Yes, send the Campaign to send the Campaign Answer to the provided phone numbers in real time.

Track your Campaign’s success

You can see data about your Campaign in two reports, which you can find by going to Measure > Reports on your Ada dashboard:

• Campaign Performance (SMS)
• Campaign Breakdown (SMS)

Campaign functionality also works with other features you can use to measure your bot’s success and run experiments on which approaches are the most effective. To ensure your Campaign is properly trackable, be aware of these technical limitations:

• An Event included in Proactive SMS Campaigns only works if the Event is tracked within the bot conversation. This includes Events that are tracked with the Event block, or other Event trackable block such as the Request block, Link block, handoff blocks, or action blocks.

  A Proactive SMS Campaign included in an Event that is tracked on your website using the Embed2 Javascript API will not work.

• A Goal, which is made up of Events, will only work if all of its Events are tracked in bot conversations.

• A/B Tests will work as long as the Event that the A/B Test is being measured against is tracked in a bot conversation with the Event block, or other Event trackable block such as the Request block, Link block, handoff blocks, or action blocks.