30

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:

• Set up your Twilio account 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.

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 person in your Sample data who has a phone attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines..

   Selecting a representative sample person 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 people? Unsubscribed people 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.

The to parameter: sending your message

When you send a transactional SMS or WhatsApp message, you must pass the to parameter in your request so we know who to send the message to.

This value can be either a phone number in E.164 format (e.g., +15551234567) or a customer attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. in liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}. syntax, like {{customer.phone}}.

Examples and API parameters

Below are examples of transactional SMS messages. We’ve provided a basic payload and examples for cURL, our Node.JS SDK, and our Python SDK.

We’ve also provided a list of parameters for transactional SMS payloads. Your payload changes based on whether you reference a transactional_message_id (a template) or not. See our REST API documentation for more information.

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

const { APIClient, SendSMSRequest } = require("customerio-node");
const api = new APIClient('app-key');

const request = new SendSMSRequest({
  transactional_message_id: "confirmation_code",
  identifiers: {
    id: "123456"
  },
  message_data: {
    confirmation_code: "123456",
    account_name: "Jane Doe"
  },
});

api.sendSMS(request)
  .then(res => console.log(res))
  .catch(err => console.log(err.statusCode, err.message))

from customerio import APIClient, SendSMSRequest, CustomerIOException
client = APIClient("your API key")

request = SendSMSRequest(
  transactional_message_id="confirmation_code",
  identifiers={
    "id": "123456"
  },
  message_data={
    "confirmation_code": "123456",
    "account_name": "Jane Doe"
  }
)

try:
  api.send_sms(request)
except CustomerIOException as e:
  print("error: ", e)

import "github.com/customerio/go-customerio"

client := customerio.NewAPIClient("");

request := customerio.SendSmsRequest{
  TransactionalMessageID: "sms_test",
  Identifiers: map[string]string{
    "id": "123456",
  },
}

body, err := client.SendSms(context.Background(), &request)
if err != nil {
  fmt.Println(err)
}

fmt.Println(body)

require "customerio"

client = Customerio::APIClient.new("")

request = Customerio::SendSmsRequest.new(
  transactional_message_id: "sms_test",
  identifiers: {
    id: "123456",
  },
)

begin
  response = client.send_sms(request)
  puts response
rescue Customerio::InvalidResponse => e
  puts e.message, e.code, e.response
end

curl --request POST \
  --url https://api.customer.io/v1/send/sms \
  --header 'Authorization: Bearer <YOUR-APP-API-KEY>' \
  --header 'content-type: application/json' \
  --data '{
    "transactional_message_id": "confirmation_code",
    "identifiers": {
        "id": "123456"
    },
    "message_data": {
        "confirmation_code": "123456",
        "account_name": "Jane Doe"
    }
}'