# Trigger inbox messages from your backend

You can send inbox messages in response to user activity directly from your backend. While we call this a *transactional* message, it’s not a transactional message in the traditional, legal sense—it’s a message that you send to your audience that they can access at their leisure.

## How it works[](#how-it-works)

You can leverage our transactional messaging feature to send inbox messages immediately from your backend without triggering a campaign or broadcast. This gives you a way to send one-to-one messages using Customer.io without having your message-sending logic inside Customer.io.

## Setup process[](#setup-process)

1.  **[Set up a message template](#1-set-up-a-message)**: This represents the “template” for the message you want to send. You’ll also use [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) to personalize the message for the recipient.
2.  **Set up your backend to trigger your inbox message**: This is where you’ll send the message payload to Customer.io. You’ll reference the template to make sure that you send the correct message.

### 1\. Set up a message[](#1-set-up-a-message)

When you set up a message, you’re essentially determining the *id* or *name* of the message you want to send. You’ll use one of these values to send and populate your message when you’re ready to send it.

1.  Go to the **Transactional** page and click **Create Message**.
    
2.  Give your message a *Name* and a *Description*, then click **Next: Add Content**. The name and description help your team members understand what kind of message this is (like “Order Update”).
    
3.  Select **Inbox** as the message type and click **Add Content**.
    
    [![The inbox message type selection screen with the inbox message type selected](https://docs.customer.io/images/inbox-content.png)](#3c5395496b6eb2d00967b0ac744565ec-lightbox)
    
4.  Define your message settings:
    
    *   **Type**: Provides a way to differentiate messages in your inbox. For example, if a message type is `rich`, that might tell your inbox client to display a rich message with support for images, etc.
    *   **Expiration**: The time between when the message is sent and when it should expire. Messages only expire if they’re sent but not delivered. By default, messages expire after 60 days.
    *   **Topics**: These are the topics that the message belongs to, used to filter the inbox (when you call `analytics.inbox('topic1', 'topic2')`). You can let your audience filter on topics when they open the inbox.
        
        [![The inbox message settings screen with the message settings filled in](https://docs.customer.io/images/inbox-message.png)](#bf49584b3c7088f0b198a5f9671d34e2-lightbox)
        
5.  In the JSON area, set the `title` and `body` of your message: these are the two “message” fields you’ll send with your message. You can send other fields in the payload when you trigger the message, but these are the two fields that represent the message itself.
    
    You can use [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) to include dynamic content from your trigger data. Use `{{customer.<attribute_name>}}` to include customer attributes and `{{trigger.<attribute_name>}}` to include data from your payload—these are values you can set when you send a transactional message.
    
    For example, your message might look like this:
    
    ```json
    {
     "title": "Order #{{trigger.order_number}} has shipped!",
     "body": "You can track your order for {{trigger.order_number}} here: {{trigger.tracking_url}}",
    }
    ```
    
6.  When you’re done, save your message and click **Next: Configure Settings**.
    
7.  Update your message settings. We recommend that you use the default settings, but you should **Set a trigger name** so that it’s easier to send your message later. By default, you’ll trigger a message using the `transactional_message_id`, which is the last number in the URL of your message; the trigger name makes this more human readable.
    
    [![The inbox message settings screen with the message settings filled in. The trigger name is set to example_message.](https://docs.customer.io/images/inbox-message-settings.png)](#87a9be50589a8a66231464c1b8251664-lightbox)
    
8.  Click **Next: Send Message**.
    

Now you’re ready to send your message! You’ll need to [update your backend to trigger your message](/#2-set-up-your-backend). We also recommend that you [test your message](#test-your-message) to make sure it displays the way you expect it to.

#### Using Liquid in messages[](#using-liquid-in-messages)

You can use [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) to include dynamic content from your trigger data. Use `{{customer.<attribute_name>}}` to include customer attributes and `{{trigger.<attribute_name>}}` to include data from your payload—these are values you can set when you send a transactional message.

*   Customer [attributesA 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.](/journeys/attributes/): these are attributes that are already set on your audience. For example, `{{customer.first_name}}` corresponds to the `first_name` attribute on your customer’s profile.
*   Trigger data: data sent in the `message_data` object when you trigger an inbox message. For example `{{trigger.order_number}}` corresponds to `message_data.order_number` in your payload.

Your `trigger` data comes from the `message_data` object in your transactional message payload.

#### Message types[](#message-types)

The message type gives you a way to categorize messages that you want to show in your inbox. You might do this if you want to let users filter the messages they see.

If you don’t want to filter messages by type, and you don’t want to assign “types” to your messages, leave this field empty.

If you send a message with a type that isn’t specified in the `analytics.inbox()` parameter, the message won’t appear to the user.

### 2\. Set up your backend to trigger inbox messages[](#2-set-up-your-backend-to-trigger-inbox-messages)

You’ll trigger inbox messages using our `inbox_message` API. You send calls to this endpoint using one of our App API-based libraries ([Node.js](/integrations/api/track/nodejs/), [Python](/integrations/api/track/python/), [Ruby](/integrations/api/track/ruby/), [Go](/integrations/api/track/go/)) or by sending requests directly to `POST https://api.customer.io/v1/send/inbox_message`.

Triggering an inbox message is fairly similar to the way you send events to Customer.io. But, where events *can* trigger campaigns or get used in other capacities, the `inbox_message` endpoint explicitly triggers a message for the end user. The following examples show how to trigger an inbox message using the libraries listed above. See our [API documentation](/integrations/api/app/#operation/sendInboxMessage) for more information on the `inbox_message` endpoint.

*   `transactional_message_id`: The `transactional_message_id` is the ID of your transactional message. You can find this in the URL of your transactional message or in the code sample in the **Overview** tab for your transactional message.
*   `identifiers`: The `identifiers` are the identifiers for the recipient. You can use the `id`, `email`, or `cio_id` identifier.
*   `message_data`: The `message_data` is the data you want to include in your message. You can use [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) to include dynamic content from your trigger data.

Below are examples showing how to trigger an inbox message using our SDKs.

 Node.js

#### Node.js[](#Node.js)

```javascript
const { APIClient } = require("customerio-node");

const client = new APIClient("YOUR_APP_API_KEY");

const request = {
  transactional_message_id: "order_shipped",
  identifiers: {
    id: "user_123"
  },
  message_data: {
    order_id: "ORD-5678",
    tracking_url: "https://track.example.com/5678",
    product_name: "Blue Widget"
  }
};

client.sendInboxMessage(request)
  .then(res => console.log(res))
  .catch(err => console.log(err.statusCode, err.message));
```

 Python

#### Python[](#Python)

```python
from customerio import APIClient

client = APIClient("YOUR_APP_API_KEY")

request = {
  "transactional_message_id": "order_shipped",
  "identifiers": {
    "id": "user_123"
  },
  "message_data": {
    "order_id": "ORD-5678",
    "tracking_url": "https://track.example.com/5678",
    "product_name": "Blue Widget"
  }
}

response = client.send_inbox_message(request)
print(response)
```

 Ruby

#### Ruby[](#Ruby)

```ruby
require "customerio"

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

request = {
  transactional_message_id: "order_shipped",
  identifiers: {
    id: "user_123"
  },
  message_data: {
    order_id: "ORD-5678",
    tracking_url: "https://track.example.com/5678",
    product_name: "Blue Widget"
  }
}

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

 Go

#### Go[](#Go)

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

client := customerio.NewAPIClient("YOUR_APP_API_KEY")

request := customerio.SendInboxMessageRequest{
  TransactionalMessageID: "order_shipped",
  Identifiers: map[string]string{
    "id": "user_123",
  },
  MessageData: map[string]interface{}{
    "order_id": "ORD-5678",
    "tracking_url": "https://track.example.com/5678",
    "product_name": "Blue Widget",
  },
}

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

fmt.Println(body)
```

 cURL

#### cURL[](#cURL)

```bash
curl --request POST \
  --url https://api.customer.io/v1/send/inbox_message \
  --header 'Authorization: Bearer YOUR_APP_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "transactional_message_id": "order_shipped",
    "identifiers": {
      "id": "user_123"
    },
    "message_data": {
      "order_id": "ORD-5678",
      "tracking_url": "https://track.example.com/5678",
      "product_name": "Blue Widget"
    }
  }'
```