> This page is part of the [Customer.io documentation](https://docs-customerio.netlify.app). For the complete index, see [llms.txt](https://docs-customerio.netlify.app/llms.txt). > Last updated: May 13, 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](/journeys/transactional-api/) section to learn more about transactional concepts and how our transactional API works. ## Before you begin[](#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[](#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.}}`) or trigger data (`{{trigger.}}`). 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](/journeys/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[](#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}}`.](/using-liquid) using `{{trigger.}}`. ```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[](#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}}`.](/using-liquid) in your message. ## Examples and API parameters[](#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 but of limited use for in-app sends. If `true` and the `transactional_message_id` you pass doesn’t match an existing record, Customer.io creates an empty in-app record using that value as the *Trigger Name*. Because the in-app API doesn’t accept content in the request, the auto-created record has no layout for the SDK to render until you populate it in the UI. For a stable trigger name on in-app, [create the message in the UI](/journeys/transactional-in-app/) and assign a *Trigger Name* there. When `auto_create` is `true`, `transactional_message_id` must be a string. If the name already belongs to a record—even on a different channel—the request fails with `400`. * 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](/localization-getting-started/#supported-languages). * message\_data object An object containing the key-value pairs referenced using liquid in the format `{{trigger.}}` 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.