diff --git a/source/images/proactive-sms-api-flow.png b/source/images/proactive-sms-api-flow.png new file mode 100644 index 00000000000..2bbbeab19ff Binary files /dev/null and b/source/images/proactive-sms-api-flow.png differ diff --git a/source/includes/proactive_sms_api.md.erb b/source/includes/proactive_sms_api.md.erb new file mode 100644 index 00000000000..fe497f03fb5 --- /dev/null +++ b/source/includes/proactive_sms_api.md.erb @@ -0,0 +1,111 @@ +# Proactive SMS API + +The Proactive SMS feature allows you to start personalized two-way conversations using Short Message Service (SMS) messages. These automated interactions are based on campaigns designed in the Ada dashboard, which you can trigger using the Proactive SMS API. With this API, you can use events from external systems to initiate real-time notifications, such as: + +* Order updates for e-commerce customers +* Drip campaigns managed through a marketing automation platform +* Travel updates such as flight status changes +* Account notifications or alerts for fintech platforms +* Alerts to software as a service (SaaS) account holders, such as overage warnings, onboarding reminders, or upsell offers + +**Example** + +<%= image_tag "images/proactive-sms-api-flow.png" %> + +When you send the request to trigger a campaign, you’ll include the phone number of your recipient, along with any metadata that you want to use to personalize your interaction with the chatter. Each piece of metadata becomes a variable that you can use throughout a conversation, by including it in the answers within your campaign. + + + +## Getting started + +To use the Proactive SMS API you need to: + +* be an Ada Engage or Ada CX client, with an Ada bot Owner or Administrator account +* create a new Proactive SMS Campaign (learn how in our [Resource Center](https://adasupporthelp.zendesk.com/hc/en-us/articles/4411541727635-Proactive-SMS-Campaigns)) +* have a SunCo account, and a Twilio account configured with a phone number +* obtain an API token for authentication + + + +### Authentication + +To connect with the Proactive SMS API, you need an access token that you’ll include in the header of your requests. + +1. In the Ada dashboard, go to **Settings > Integrations > API Integrations > Proactive SMS API**. +2. Click **Configure**. +3. Copy the API Access Token. Keep it in a safe place, as you won’t be able to access it again. + +If you misplace your token, click the **Generate a new Access Token** button to get a new one. When you do this, it invalidates the previous token. + +## Proactive SMS API Reference + + + +### Trigger an SMS Campaign + +`POST /campaigns/sms/trigger/` + +Connect to the host with the following address and base path, where {bot-name} is the name of your bot: + +`https://{bot-name}.ada.support/api/campaigns/sms/trigger` + +You can also copy this address directly from your dashboard, in the **Campaign Triggers** section of your SMS campaign. + + +``` +## Trigger an SMS Campaign +curl -X "POST" "https://my-bot.ada.support/api/campaigns/sms/trigger" \ + -H 'Authorization: Bearer 2926a1304ce6b5ff29c1e7ed9b0bcee6' \ + -H 'Content-Type: application/json' \ + -d $'{ + "campaign_key": "renew_subscriptions", + "language": "en", + "recipient": { + "meta_fields": { + "phone_number": "4165551234", + "first_name": "Sam" + } + } +} +``` + +### Response + +A 200 - OK 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. + +### Header Parameters + +Use these parameters in the header. + +|Parameter|Description|Required?|Type| +|:----|:----|:----|:----| +| Authorization | Use the access token you generated above, in the format: `Bearer `.
**Example**
`Bearer 2926a1304ce6b5ff29c1e7ed9b0bcee6`|Yes| string| + + +### Body Parameters + +Use these parameters in the body of your request. + +|Parameter|Description|Required?|Type| +|:----|:----|:----|:----| +|campaign_key|Copy the campaign_key from your Ada dashboard, under **Build > Campaigns**, in the **Campaign Key** column.|Yes|string| +|language|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.|string| +|recipient|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.
**Example**
`"recipient": { "meta_fields": { "phone_number": "4165551234", "first_name": "Sam" } }`|Yes|object| +|meta_fields|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 (more details below).
**Example**
`"recipient": { "meta_fields": { "phone_number": "4165551234", "first_name": "Sam", "last_name": "Zhang", "email": "sam.zhang@example.com", "latest_order": "12345" } }`|Yes|string| +|phone_number|Include the recipient’s phone number as a meta field. The SMS message will be sent to this number.
**Example**
`"recipient": { "meta_fields": { "phone_number": "4165551234", "first_name": "Sam" } }`|Yes|string| + +## Status messages + +|Code|Meaning| +|:----|:----| +|200 - OK|Ada has triggered the campaign and sent the messages to Twilio/SunCo. A 200 status reflects that specific action, and cannot account for any issues that might impact the messages once they leave the Ada system.| +|400 - Bad request|There’s something wrong with the query. Check your request and try again.| +|500 - Internal server error|There was an issue on the server.| + + +## Proactive SMS API Changelog + + +|Date|Description| +|--- |--- | +|2022.04.01|Initial version.| diff --git a/source/index.html.md.erb b/source/index.html.md.erb index 91c6344285c..c57e5c89847 100644 --- a/source/index.html.md.erb +++ b/source/index.html.md.erb @@ -7,6 +7,7 @@ includes: - ios.md.erb - android.md.erb - reactnative.md.erb + - proactive_sms_api.md.erb - data_api.md.erb - data_compliance_api.md.erb - questions.md.erb