> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt).
> Last updated: July 10, 2026

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

 New to transactional messaging?

Check out our [getting started](/messaging/send/transactional/api/) section to learn more about transactional concepts and how our transactional API works.

## 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](/integrations/data-in/connections/javascript/) or one of our [mobile SDKs](/integrations/sdk/) in your application so we can render in-app messages on your audience’s devices.
*   Get your [app API key](https://fly.customer.io/settings/api_credentials?keyType=app). 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 people?** Unsubscribed people 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](https://getpostman.com) or send a cURL request from your terminal to test your message.
    

 Did you just update a snippet?

If you just updated a [snippet](/messaging/liquid/snippets/) used in your messages, make sure you wait a couple of minutes before activating your workflow to ensure all updates appear in your delivered messages.

## Send a transactional in-app message

You’ll send your message using [our API](/integrations/api/app/#operation/sendInApp). 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](#create-a-transactional-in-app-message).
*   `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 [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}}`.](/journeys/liquid/using-liquid) using `{{trigger.<property_name>}}`.

```fallback
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 person’s attributes to resolve any [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}}`.](/journeys/liquid/using-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](/integrations/api/app/#operation/sendInApp) documentation for the full reference, including code samples in cURL and several languages.

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

*   auto\_create boolean
    
    Accepted for in-app sends, but of limited use. An auto-created record has no content or layout until you populate it in the UI, so we recommend [creating the in-app message in the UI](/journeys/send/transactional/in-app/) instead. Your `transactional_message_id` must be a new string.
    
*   identifiers 
    
    Required Identifies the person represented by your transactional message by one of, and only one of, `id`, `email`, or `cio_id`.
    
    *   id string
        
        Required The identifier for the person represented by the transactional message. **NOTE**: If your workspace identifies people by email, use the `email` identifier instead.
        
    
    *   email string
        
        Required The identifier for the person represented by the transactional message. Use this option if your workspace identifies people by email rather than by `id`.
        
    
    *   cio\_id string
        
        Required A unique, immutable identifier for a person, set by Customer.io when you add a person.
        
    
*   language string
    
    Overrides language preferences for the person you want to send your transactional message to. Use one of our [supported two- or four-letter language codes](/journeys/channels/localization/getting-started/#supported-languages).
    
*   message\_data object
    
    An object containing the key-value pairs referenced using liquid in the format `{{trigger.<property_name>}}` in your in-app message. These values populate the `properties` field in the message that the SDK delivers to your application.
    
    *   *Liquid Data\** any type
        
        Insert key-values that you want to reference in your message here.
        
*   send\_at integer
    
    A unix timestamp (seconds since epoch) determining when the message will be sent. The timestamp can be up to 90 days in the future. If this value is in the past, your message is sent immediately.
    
*   transactional\_message\_id 
    
    Required The transactional message template that you want to use for your message. You can call the template by its numerical ID or by the *Trigger Name* that you assigned to the template in the UI (case insensitive).
    
    integer
    
    The ID of the transactional message you want to send.
    
    string
    
    The name of trigger for the transactional message you want to send; you set the trigger name in the *Configure Settings* step when setting up your message. This is case insensitive.
    

*   *   [Before you begin](#before-you-begin)
    *   [Create a transactional in-app message](#create-a-transactional-in-app-message)
    *   [Send a transactional in-app message](#send-a-transactional-in-app-message)
    *   [Identify your recipient](#identify-your-recipient)
    *   [Examples and API parameters](#examples-and-api-parameters)

Copy page

Copy page [Download .md](/messaging/send/transactional/in-app.md)

Is this page helpful?

![](https://docs.customer.io/images/export-success.png) ![](https://docs.customer.io/images/export-failure.png)

# How can we make it better?

Close

Do you need help from Customer.io support?  No  
 Yes

What part of Customer.io do you need help with? 

How can we improve this page?

Email (optional):  Please provide a valid email address

 I am not a bot

 

We appreciate your feedback!

Our support team will contact you as soon as possible