> For the complete documentation index, see [llms.txt](https://en.help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.help.firstline.cc/developer/api/advanced/send-message/push-message.md).

# Send Message via PUSH API

{% hint style="success" %}
This API is available from version v.3.00.00 onwards.
{% endhint %}

## Overview

When you need to send personalized messages to specific users, you can integrate using FIRST LINE's PUSH API. This integration allows you to deliver messages more effectively.

In addition, using the PUSH API can help you save time and resources because you don't need to build a messaging system from scratch. With just a few simple steps, you can start sending personalized messages to your users.

## API 

```shell
curl -X POST
    -H "Content-Type: application/json"
    https://{API_HOST}/api/v1/message/push
```

### Response

The response is in JSON format, and an HTTP status code of 200 indicates that the send was successful.

```html
{}
```

### URL Parameters

<table><thead><tr><th width="251">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>contactable_type</td><td><p>Channel types include the following options:</p><ul><li><strong>Live chat</strong>:<code>App\LivechatContact</code></li><li><strong>LINE OA</strong>:<code>App\LineContact</code></li><li><strong>Facebook Messenger</strong>:<code>App\FbContact</code></li><li><strong>Instagram</strong>:<code>App\IgContact</code></li><li><strong>Telegram</strong>:<code>App\TelegramContact</code></li><li><strong>Viber</strong>:<code>App\ViberContact</code></li><li><strong>WeChat</strong>:<code>App\WechatContact</code></li></ul></td></tr><tr><td>contactable_id</td><td>The identifier in the contact system corresponding to each messaging channel, usually obtainable from <strong>Contact API</strong> the returned social media related data.</td></tr><tr><td>type</td><td><p></p><p>Message types are divided into the following:</p><ul><li><strong>text</strong>: text</li><li><strong>carousel</strong>: carousel</li><li><strong>image_carousel</strong>: image carousel</li><li><strong>button</strong>: button</li><li><strong>quickreply</strong>: quick reply</li></ul></td></tr><tr><td>message</td><td><code>message</code> The information is defined according to different message types. For example, when <code>type</code> is set to <code>text</code> ,<code>message</code> the content might be 'Hi! How are you!'.</td></tr><tr><td>is_force</td><td>When a conversation is in certain states, such as when the customer is talking to an agent, sending messages via the API is not allowed by default. But if the value is set to 1, it forces the message to be sent even if the conversation has already started.</td></tr></tbody></table>

## Message field formats

### Text message

```json
{
  "type": "text",
  "message": "The text message to send"
}
```

### Button

| Property          | Description                                           |
| ----------------- | ----------------------------------------------------- |
| explain\_text     | Body description                                      |
| options\[].label  | The text label of the button or option                |
| options\[].value  | The message value to send                             |
| options\[].type   | The type of the option (e.g., text, phonenumber, url) |
| options\[].number | Phone number (only present when type is phonenumber)  |
| options\[].url    | URL to open (only present when type is url)           |

```json
{
  "type": "button",
  "message": {
        "explain_text": "Body description",
        "options": [
            {
                "label": "Button text",
                "value": "Message to send",
                "type": "text"
            },
            {
                "label": "Call phone",
                "type": "phonenumber",
                "number": "+886012345679"
            },
            {
                "label": "Open URL",
                "type": "url",
                "url": "https://www.firstline.cc/"
            }
        ]
    }
}
```

### Quick Reply

| Property         | Description                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| explain\_text    | Body message, text field                                                                           |
| options\[].label | Option label                                                                                       |
| options\[].value | Option value                                                                                       |
| options\[].type  | Option type, e.g.: url or text                                                                     |
| options\[].url   | When the option type is url, the corresponding URL for that option (only present when type is url) |

```json
{
  "type": "quickreply",
  "message": {
        "explain_text": "Body message",
        "options": [
            {
                "label": "#001",
                "value": "001",
                "type": "url",
                "url": "https://www.firstline.cc/"
            },
            {
                "label": "#002",
                "value": "002",
                "type": "text"
            },
            {
                "label": "#003",
                "value": "003",
                "type": "text"
            }
        ]
    }
}
```

### Carousel message**arousel**

Used to send horizontally scrollable carousel content. Each carousel item contains an image, a short description, and buttons.

<table><thead><tr><th width="268">Property</th><th>Description</th></tr></thead><tbody><tr><td>alt_text</td><td>Fallback message or sent when the message format is not supported</td></tr><tr><td>columns[].image_url</td><td>URL address of the background image</td></tr><tr><td>columns[].title</td><td>Title</td></tr><tr><td>columns[].text</td><td>Text description</td></tr><tr><td>columns[].actions[].text</td><td>The text of the action button or link</td></tr><tr><td>columns[].actions[].value</td><td>The value of the action button or link</td></tr><tr><td>columns[].actions[].url</td><td>The URL of the action button or link (only present when type is url)</td></tr><tr><td>columns[].actions[].type</td><td>The type of the action button or link, e.g.: url or text</td></tr><tr><td>columns[].actions[].label</td><td>The label of the action button or link (if present)</td></tr></tbody></table>

```json
{
  "type": "carousel",
  "message": {
    "alt_text": "Message format not supported.",
    "columns": [
      {
        "image_url": "https://www.firstline.cc/assets/images/illustration/header.png",
        "title": "All-in-one customer service system",
        "text": "Integrates multiple communication channels, including phone, LINE, Facebook, live chat, WhatsApp, etc., allowing you to efficiently provide customer support and sales services.",
        "actions": [
          {
            "text": "Nike",
            "value": "Nike",
            "url": "https://www.firstline.cc/",
            "type": "url"
          },
          {
            "label": null,
            "value": null,
            "type": "url",
            "url": "https://www.firstline.cc/",
            "text": "FIRST LINE customer service system"
          },
          {
            "label": null,
            "value": "Other",
            "type": "text",
            "url": null,
            "text": "Other"
          }
        ]
      },
    ]
}

```

### **Image Carousel**&#x20;

<table><thead><tr><th width="320">Property</th><th>Description</th></tr></thead><tbody><tr><td>alt_text</td><td>Fallback message or sent when the message format is not supported</td></tr><tr><td>columns[].image_url</td><td>URL address of the background image</td></tr><tr><td>columns[].action.type</td><td>Type of the action (may be null), e.g.: url or text</td></tr><tr><td>columns[].action.url</td><td>URL address of the action (may be null)</td></tr><tr><td>columns[].action.value</td><td>Value of the action (may be null)</td></tr><tr><td>columns[].button.text</td><td>Text of the button</td></tr><tr><td>columns[].button.background_color</td><td>Button background color, as a HEX color code</td></tr><tr><td>columns[].button.border_color</td><td>Button border color, as a HEX color code</td></tr><tr><td>columns[].button.color</td><td>Button text color, as a HEX color code</td></tr><tr><td>columns[].badge.text</td><td>Badge text</td></tr><tr><td>columns[].badge.background_color</td><td>Badge background color, as a HEX color code</td></tr><tr><td>columns[].badge.border_color</td><td>Badge border color, as a HEX color code</td></tr><tr><td>columns[].badge.color</td><td>Badge text color, as a HEX color code</td></tr></tbody></table>

```json
{
    "type": "image_carousel",
    "message": {
        "alt_text": "Message format not supported.",
        "columns": [
            {
                "image_url": "https://www.firstline.cc/assets/images/illustration/header.png",
                "action": {
                    "type": null,
                    "url": null,
                    "value": null
                },
                "button": {
                    "text": "Sign up now",
                    "background_color": "#09091A",
                    "border_color": "#09091A",
                    "color": "#09091A"
                },
                "badge": {
                    "text": "SALE",
                    "background_color": "#eb4d4b",
                    "border_color": "#eb4d4b",
                    "color": "#FFFFFF"
                }
            }
        ]
    }
}
```