Skip to main content

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.

note

When chatters unsubscribe from receiving text messages they will receive a confirmation message. This message is configurable in Twilio. You can also view and manage unsubscribed chatters in Twilio.

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.

    important

    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
tip

Your bot handle can be found in the upper left corner of your dashboard, above the left navigation bar.

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:

FieldRequiredTypeDetails
campaign_keyYesStringCopy the campaign_key from your Ada dashboard, under Build > Campaigns, in the Campaign Key column.
languageNoStringType an ISO 639-1 language code as the value. For example, “en” for English. Defaults to the bot’s default language if not specified.
recipientYesObjectObject containing the phone number for the recipient, and any metadata fields that you want to use in the interaction (more details below). There can only be 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.
Recipient Object meta_fieldsYesObjectUse these fields to bring in data from another system. You can use this information to personalize the SMS interaction for your chatter. For example, you might want to include a chatter’s name, email address, or an order number. You must include a phone number as a meta field, as in the example at the top of this page.
Meta_Fields Object phone_numberYesStringInclude the recipient’s phone number as a meta field. The SMS message will be sent to this number.
Meta_Fields Object first_nameNoStringOptionally, you can include things like the user's first name as a meta field.
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.

Response Code Details
200Success
400Invalid request, body or headers
500Server error
note

A 200 response means that Ada has triggered the campaign and sent the messages to Twilio/SunCo. It does not account for any issues that might impact the messages once they leave the Ada system.

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.

    note

    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_numberfirst_namelast_name
      15551234567JaneDoe
      15557654321JohnDoe
      15559876543JimmyDoe

  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.

    note

    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.

note

You can send up to 10,000 proactive SMS sends every day via CSV upload.

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 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.

Have any questions? Contact your Ada team, or email us at .