> This page is for version Scripted.
> For other versions, use one of these documentation indexes:
> - Generative (default): https://developers.ada.cx/generative/llms.txt
> - Scripted: https://developers.ada.cx/scripted/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.ada.cx/_mcp/server.

# Start text conversations using Proactive SMS Campaigns

## Overview\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FDB63SF6FZ2AX2Z0NH5917WY]

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

### Requirements\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FDB6406Y0RF21JK7BJGTC370]

To use Proactive SMS Campaigns you need to have:

* Ada’s SMS channel

* A Twilio account

#### About Twilio accounts\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FX5WGYFX0PACHZY1M32ZN39X]

* 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](https://www.twilio.com/sms/pricing/us) 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](https://www.twilio.com/en-us/guidelines/sms) at Twilio's documentation.

## Create a new Proactive SMS Campaign\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FDB647NKZBT7Z5TA9YW8FTRJ]

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\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FTRVVQFZ6XCXG1F20X9MHARP]

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

### Campaign content\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FTRW42ZMQEB1DZEKJ3VVRH7R]

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\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FTRW4BJSY382P0J9SBHGBCHE]

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.

  > **Info**
  >
  > 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\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FTRW37R8F6GC8QW86TT5QKRM]

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

#### Trigger via the Proactive SMS Campaign API\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FTRW3GC4ADCENNFRR9B1NWPB]

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](https://docs.ada.cx/docs/scripted/build-and-maintain-your-bot/create-conversations/start-text-conversations-using-proactive-campaigns-for-sms/#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FTRW3TPRGGSN4P4W7VW5EEBE) 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:

<table>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Required
      </th>

      <th>
        Type
      </th>

      <th>
        Details
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `campaign_key`
      </td>

      <td>
        Yes
      </td>

      <td>
        String
      </td>

      <td>
        Copy the campaign_key from your Ada dashboard, under Build > Campaigns, in the Campaign Key column.
      </td>
    </tr>

    <tr>
      <td>
        `language`
      </td>

      <td>
        No
      </td>

      <td>
        String
      </td>

      <td>
        Type an ISO 639-1 language code as the value. For example, “en” for English. Defaults to the bot’s default language if not specified.
      </td>
    </tr>

    <tr>
      <td>
        `recipient`
      </td>

      <td>
        Yes
      </td>

      <td>
        Object
      </td>

      <td>
        Object 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.
      </td>
    </tr>

    <tr>
      <td>
        **Recipient Object**




        `meta_fields`
      </td>

      <td>
        Yes
      </td>

      <td>
        Object
      </td>

      <td>
        Use 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.
      </td>
    </tr>

    <tr>
      <td>
        **Meta_Fields Object**




        `phone_number`
      </td>

      <td>
        Yes
      </td>

      <td>
        String
      </td>

      <td>
        Include the recipient’s phone number as a meta field. The SMS message will be sent to this number.
      </td>
    </tr>

    <tr>
      <td>
        **Meta_Fields Object**




        `first_name`
      </td>

      <td>
        No
      </td>

      <td>
        String
      </td>

      <td>
        Optionally, you can include things like the user's first name as a meta field.
      </td>
    </tr>
  </tbody>
</table>

##### Headers

You will need to generate an [Ada API key](https://ada.docs.buildwithfern.com/reference/introduction/authentication) 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.

<table>
  <thead>
    <tr>
      <th>
         Response Code 
      </th>

      <th>
        Details
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `200`
      </td>

      <td>
        Success
      </td>
    </tr>

    <tr>
      <td>
        `400`
      </td>

      <td>
        Invalid request, body or headers
      </td>
    </tr>

    <tr>
      <td>
        `500`
      </td>

      <td>
        Server error
      </td>
    </tr>
  </tbody>
</table>

> **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\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FTRW3TPRGGSN4P4W7VW5EEBE]

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

   > **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\[#UUID-72f12e60-0ba7-c18d-9864-3fc1d82eef92_id_4411541727635_id_h_01FX5WGFECCZDSTMA0RB08MJP0]

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)](/scripted/docs/measure-success/analyze-chat-data/view-detailed-reports-on-your-bot-s-performance#UUID-3849f727-cc9c-a7ce-b260-13c626030fa9_sidebar-idm43340873765590_body)
* [Campaign Breakdown (SMS)](/scripted/docs/measure-success/analyze-chat-data/view-detailed-reports-on-your-bot-s-performance#UUID-3849f727-cc9c-a7ce-b260-13c626030fa9_sidebar-idm43340873761248_body)

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](/scripted/docs/measure-success/plan-and-collect-feedback/create-and-track-chatter-actions) 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](/scripted/docs/measure-success/plan-and-collect-feedback/set-goals-to-measure-your-bot-s-impact), which is made up of Events, will only work if all of its
  Events are tracked in bot conversations.

* [A/B Tests](/scripted/docs/measure-success/plan-and-collect-feedback/run-an-a-b-test) 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 [](<mailto:help@ada.support%20%E2%80%9CHelp Docs inquiry%E2%80%9D>).