Set up a transactional in-app message

Transactional in-app messages render in your application through the Customer.io SDK. Use them for time-sensitive, customer-initiated messages like order confirmations or two-factor codes that you want to deliver inside your product.

Before you begin

Before you can send transactional in-app messages, you need to:

• Enable in-app messaging in your workspace.
• Install either our JavaScript SDK or one of our mobile SDKs in your application so we can render in-app messages on your audience’s devices.
• Get your app API key. This is the bearer token that you’ll use when you call the transactional API.

Unlike emails or push notifications, you cannot send a transactional in-app message without a template—the message body comes from the template you reference, and the SDK renders it in your application.

Create a transactional in-app message

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. These fields help your team members understand what kind of message this is (like “Order Confirmation” or “Account Alert”). You can also use the Name to trigger your message when you send it using our API.

3. Click Next: Add Content and select In-app to create your message. You can personalize it using attributes ({{customer.<attribute>}}) or trigger data ({{trigger.<data-object-property>}}).

4. Configure your message settings.

   • Send to unsubscribed profiles? Unsubscribed profiles probably still want to receive your important transactional messages.
   • Protect sensitive data by disabling message retention? This setting prevents Customer.io from retaining your message content in delivery history and associated API calls.
   • Queue messages as drafts? This setting generates a draft for every message you trigger rather than sending them automatically.
   • Set a Trigger Name: A friendly name for your message that you can use instead of the transactional_message_id when you send.

5. To complete the setup, call the API and trigger a message. You can use an HTTP client like Postman ↗ or send a cURL request from your terminal to test your message.

Send a transactional in-app message

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

• transactional_message_id: the numeric ID or trigger name for the in-app 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/in_app \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d '
{
  "transactional_message_id": "order_confirmation",
  "identifiers": {
    "id": "user_123"
  },
  "message_data": {
    "order_id": "ORD-5678",
    "tracking_url": "https://track.example.com/5678"
  }
}
'

Identify your recipient

You’ll include an identifiers object in your request to specify the person you want to send your message to. There’s no to field on in-app sends; we route the message to the identified person’s devices via the SDK.

The identifiers object accepts one of id, email, or cio_id. We use the identified profile’s attributes to resolve any liquid in your message.

Examples and API parameters

Below is a basic transactional in-app payload. The message body comes from the template you reference; you only pass transactional_message_id, identifiers, and any message_data you want to populate the template with. See our REST API documentation for the full reference, including code samples in cURL and several languages.

{
  "transactional_message_id": "order_confirmation",
  "identifiers": {
    "id": "user_123"
  },
  "message_data": {
    "order_id": "ORD-5678",
    "tracking_url": "https://track.example.com/5678"
  }
}