Set up a transactional SMS or WhatsApp message

Transactional SMS or WhatsApp messages are text messages that your audience implicitly opts-into, like order confirmations, password reset codes, or account verification messages. You can send transactional SMS messages programmatically through Customer.io.

Before you begin

Before you can send transactional SMS messages, you need to:

• Connect an SMS provider and enable SMS in your workspace.
• Get your app API key. This is the bearer token that you’ll use when you call the transactional API to trigger a message.

We also recommend that you use different phone numbers for transactional and marketing SMS messages. This helps maintain deliverability and ensures your critical transactional messages aren’t affected by marketing message reputation.

Create a transactional SMS

Unlike transactional emails and push notifications, you cannot send a transactional SMS or WhatsApp message without a template. You must use a transactional_message_id when you send an SMS and you cannot override the body or image URL of your message at send time. This is true no matter which SMS provider delivers your messages.

How you write the message depends on your provider. With Twilio, you draft the message in the transactional composer, following the steps below. With other providers, you choose the SMS channel and link a message you’ve built in Design Studio—the trigger, settings, and API call work the same way.

1. Go to the Transactional page and click Send your first message or Create message—depending on whether there are already transactional messages in your workspace.

2. Give your message a Name and a Description and then click Next: Add Content. The name and description help your team members understand what kind of message this is (like “Two-Factor Authentication” or “Password Reset Code”).

   

3. Select SMS and click Add Content.

4. Draft your message. If you see an error in the upper-right when you try to write your message, it’s likely that you need to select a profile in your Sample data who has a phone attribute.

   Selecting a representative sample profile also helps you personalize your message. You can personalize messages using attributes ({{customer.<attribute>}}) or data from your transactional message’s message_data key ( in the format {{trigger.<data-object-property>}}).

   

5. When you’re done writing your message, click Save Changes and then click Next: Configure Settings.

6. Configure your message settings. In general, we recommend that you use our defaults and that you Set a trigger name so that it’s easier to send your message later.

   • Send to unsubscribed profiles? Unsubscribed profiles probably still want to receive your important transactional messages like order confirmations and password resets.

   • Enable link tracking? By default, we’ll track clicks on links in your transactional SMS messages. Disable this setting if you don’t use our link shortening feature or tracked links (which are longer than normal links) will likely exceed the 160 character limit for SMS messages.

   • Protect sensitive data by disabling message retention? This setting prevents Customer.io from retaining your message content. You might want to do this to conceal sensitive messages, like password reset codes or verification tokens.

   • Queue messages as drafts? This setting generates a draft for every message you trigger rather than sending them automatically. You can review these messages under the Drafts tab and decide whether to send or delete them.

   • Set a Trigger Name: This is a friendly name for your message that you can use instead of the transactional_message_id when you send your message. It may help make your integration more human-readable if you use triggers that represent the kinds of messages you send—like password_reset or order_confirmation.

   

7. Now you’re ready to send your message. You can adapt the code sample on the Send Message screen to your code—wherever you intend to trigger transactional messages—or use our API directly.

(Optional) Even if you don’t want to wire up your integration completely, we recommend that you call our API and send a test message to make sure that your message works the way you expect. You can even use an HTTP client like Postman ↗ or send a cURL request from your terminal to test your message and complete the setup process.

Send a transactional SMS message

You’ll send your message using our API. To send a transactional SMS message, you need:

• transactional_message_id: the numeric ID or trigger name for the SMS message you created.
• identifiers: an object containing a unique identifier for the recipient. This tells us who to send the message to.
• message_data (optional): values you want to populate in the message using liquid using {{trigger.<property_name>}}.

curl -X POST https://api.customer.io/v1/send/sms \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d '
{
  "transactional_message_id": "confirmation_code",
  "identifiers": {
    "id": "123456"
  },
  "message_data": {
    "confirmation_code": "123456"
  }
}
'

Identify your recipient

When you send a transactional message, you need to give us a phone number to send the message to and the identifiers of the profile you want to attribute the message to. This is because phone numbers aren’t unique identifiers for profiles in Customer.io.

You can set your audience’s phone number (typically using liquid) when you set up your message. You can override or set this value when you send your message using the to parameter. This parameter can be either a phone number in E.164 format (e.g. +15551234567) or a customer attribute in liquid syntax, like {{customer.phone}}.

You’ll also include an identifiers object in your request to specify the person you want to attribute the message to. The identifiers object accepts one of id, email, or cio_id.

{
  "transactional_message_id": "confirmation_code",
  "to": "+15551234567",
  "identifiers": {
    "id": "123456"
  },
  "message_data": {
    "confirmation_code": "123456"
  }
}

Examples and API parameters

Below is a basic transactional SMS payload, followed by the full list of parameters. Your payload changes based on whether you reference a transactional_message_id (a template) or not. See our REST API documentation for the full reference, including code samples in cURL and several languages.

{
  "transactional_message_id": "confirmation_code",
  "identifiers": {
    "id": "123456"
  },
  "message_data": {
    "confirmation_code": "123456",
    "account_name": "Jane Doe"
  }
}