> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/products/crm-automation/communication-channels/sending-messages-via-smartico-rest-api.md).

# Sending Messages via Smartico REST API

You can send personalized communications to your end-users — including **Inbox messages, Emails, SMS, Push Notifications, Viber, Telegram, or WhatsApp** — using the **Smartico REST API**.

***

## General Information

Full documentation about the Smartico REST API can be found in the **Back Office**, under **Tools → Data management → Rest API**.

To make an API call, you will need a **private authorization key**, which you can copy directly from the **Back Office** under **Tools → Data management → Rest API** (or request from your **Success Manager** if your Back Office user role lacks permission to access API documentation).

### Example API Request

```
curl --request POST \
--url 'https://apis.smartico.ai/api/external/events/v2' \
--header 'Authorization: your-private-auth-key' \
--header 'Content-Type: application/json'
```

{% hint style="info" %}
Note that the endpoint and private-auth key depend on your environment, and can be found in the BackOffice in the REST API section
{% endhint %}

### Example JSON Body

```json
[
    {
        // unique UUID of the request
        "eid": "96b60b08-25f0-4129-b363-ef0d4db780ef",     
        // UTC timestamp of the request
        "event_date": 1680106470149,                          
        // brand ID in your system
        "ext_brand_id": "your-external-brand-id",             
        // user ID in your system
        "user_ext_id": "id-of-the-user-your-system",          
        // event type
        "event_type": "core_personal_message",                
        "payload": {
            "title": "Title of the message",
            "short_message": "Short message content",
            "rich_message": "<b>some rich message</b>",
            "icon": "https://mycdn.com/image.png",
            // channel type: inbox-api, email-api, sms-api, push-api, viber-api, whatsapp-api, telegram-api
            "channel": "email-api"                               
        }
    }
]
```

{% hint style="info" %}
Note that all the parameters in the payload are fully defined by you.

You can pass as many parameters as you want, and name them according to your requirements.

All these parameters later can be used in the communication templates explained below.
{% endhint %}

### Batching and Request Limits

You can send multiple message events in a single API call by passing a JSON array of event objects.

* **Batch size:** Up to several thousand events per request (subject to the maximum request payload size of 10 MB).
* **Rate limit:** Up to 6,000 requests per minute per label.
* **Response format:** The API returns an HTTP 200 response with a JSON summary of processed events and any validation errors.

You can specify the **channel** parameter in the payload to define where the message should be delivered — for example:

* `"channel": "inbox-api"`
* `"channel": "email-api"`
* `"channel": "sms-api"`
* `"channel": "push-api"`
* `"channel": "viber-api"`
* `"channel": "whatsapp-api"`
* `"channel": "telegram-api"`

## Setting Up Templates and Journeys

Before sending messages, you must create corresponding **Journey** and **Message Templates** in the **Smartico Back Office**.

### **1. Create a Message Template**

Create a message template for your chosen channel (Inbox, Email, etc.).\
Ensure the tag names used in the template use the dot-notation prefix `{{event.<field_name>}}` to match the exact keys sent in the API request payload (for example, `{{event.title}}`, `{{event.short_message}}`, `{{event.rich_message}}`, and `{{event.icon}}`). Hyphenated tags (such as `{{event-title}}`) or tags missing the `event.` prefix will not be replaced.\
You can include your own styles and HTML in the rich message area — this will serve as a base layout for all API-sent messages.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2FhvNxCZwgHToBu549wLWP%2Fr2-029-shot-1-4c173685-7cded6.png?alt=media" alt=""><figcaption><p>Inbox template for messages sent over the API: 1 — Title takes {{event.title}}; 2 — Body takes {{event.short_message}}; 3 — Rich body (HTML) holds {{event.rich_message}}</p></figcaption></figure></div>

### **2. Configure the Journey**

The Journey should be triggered by the **“Core: send personal message”** trigger.\
Set the **channel** field (e.g., `inbox-api`, `email-api`, etc.) under **“Core: personal message channel”** as shown below.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-56596b142235ed83967eaae73f11b68834f1d0fa%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>

Set the **Entry mode** to **“Every time conditions are met, run few at the same time”** and set **Max. campaign duration** to **1** **Minutes**.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2FiJEvObn6dWK59v7PgDWj%2Fr2-028-crop-3-cac25ba9-97dc46.png?alt=media" alt=""><figcaption></figcaption></figure></div>

### **3. Build the Journey Flow**

Design a Journey flow using the template created earlier.\
This flow will determine how and when messages are delivered via your chosen communication channel.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2FHdp8o49necUCszqpRXSB%2Fr2-030-shot-4-46bf5008-42557d.png?alt=media" alt=""><figcaption><p>Journey for messages over the API: 1 — the campaign start; 2 — the Inbox step connected directly to it</p></figcaption></figure></div>

## Summary

By following these steps, you can use the **Smartico REST API** to send various types of messages — including **Inbox messages, Emails, SMS, Push Notifications, Viber, Telegram, and WhatsApp** — with complete control over content, personalization, and delivery timing through the **Back Office Journeys**.

Note that following this example, you can trigger not just communication, but also cover more cases, for example, you can build campaigns and trigger over the API:

* Give a manual [gamification mission](/welcome/products/gamification-basics/missions.md)
* Calculate the [dynamic bonus](/welcome/products/general-concepts/dynamic-rewards.md) by calling the API
* Give [points, gems, or diamonds](/welcome/products/gamification-basics/points.md)
* Give [mini-games](/welcome/products/mini-games.md)

***

### Related Articles

* [Sending personal messages from Back Office](/welcome/products/crm-automation/communication-channels/sending-personal-messages-from-back-office.md) — How operators can send one-off personal messages directly from a player's user profile in the Back Office.
* [Tags, properties, and event data in the communication resources](/welcome/products/crm-automation/communication-channels/tags-properties-and-event-data-in-the-communication-resources.md) — Comprehensive guide on using state, event, label, and campaign tags in templates.

***

## Frequently Asked Questions (FAQ)

### Q: Where do I find the Private Authorization Key in the Back Office?

**A:** Go to **Tools → Data management → Rest API** in the Back Office. Your private key and environment endpoint are displayed in the **Server-to-server integration** section. If you do not see this section, ask your Back Office administrator to grant you the REST API documentation permission, or contact your Success Manager.

### Q: The API call returned HTTP 200, but the player never received the message. Why?

**A:** The REST API call only emits the message event; delivery is handled by your active Journey. Check the following:

1. Ensure a **Real-time Journey** with trigger **“Core: send personal message”** is set to **Active**.
2. Verify that the **“Core: personal message channel”** condition in the Journey matches the exact channel string passed in your API payload (for example, `email-api` matching `email-api`).
3. Verify that the user has an active contact method or device token for the channel (such as a verified email address, phone number, or active push notification token).
4. Verify that the message template assigned to the Journey activity is **Active** and not archived.

### Q: Why do event tags appear as literal text or blank in delivered messages?

**A:** Ensure template tags use the dot-notation format `{{event.<field_name>}}` matching the exact JSON key in the API payload. Hyphenated tags (like `{{event-title}}`) or tags missing the `event.` prefix (like `{{title}}`) will not be replaced. Also confirm that the communication activity is connected directly to the Journey trigger node.

### Q: Can I pass custom parameters in the payload that are not in the standard example?

**A:** Yes. You can include any custom key-value pairs inside the payload object. In your communication template, reference them using `{{event.<field_name>}}` matching your custom JSON key.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/products/crm-automation/communication-channels/sending-messages-via-smartico-rest-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.