> 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 onward.
{% endhint %}

## Overview

When you need to send personalized messages to specific users, you can integrate using FIRST LINE's PUSH API. This integration method 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 delivery system from scratch yourself. With just a few simple steps, you can start sending personalized messages to your users.

## API

```shell
curl -X POST "https://{API_HOST}/api/v1/message/push" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "contactable_type": "App\\LineContact",
    "contactable_id": 123,
    "type": "text",
    "message": "Hello, this is a notification sent by FIRST LINE.",
    "is_force": 0
  }'
```

### Response

It is returned in JSON format, and the HTTP status code 200 indicates success.

```json
{}
```

### JSON Request Body

<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 system identifier for the contact corresponding to each messaging channel, usually available in <strong>Contact API</strong> the social media-related data returned.</td></tr><tr><td>type</td><td><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 content defined according to different message types. For example, when <code>type</code> set to <code>text</code> when,<code>message</code> the content may 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 with an agent, sending messages via the API is disallowed by default. But if the value is set to 1, messages will be forced to send even if the conversation has already started.</td></tr></tbody></table>

{% hint style="warning" %}
Different messaging channels have different limitations for buttons, carousels, and proactive sending. Please first test successfully with text messages, then expand according to each message type and channel's supported capabilities.
{% endhint %}

## Message field message format

### Text message

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

### Button

| Attribute         | Description                                         |
| ----------------- | --------------------------------------------------- |
| explain\_text     | Body description                                    |
| options\[].label  | Text description of the button or option            |
| options\[].value  | Message value to send                               |
| options\[].type   | Option type (such as text, phonenumber, url)        |
| options\[].number | Phone number (exists only when type is phonenumber) |
| options\[].url    | URL to open (exists only when type is url)          |

```json
{
  "type": "button",
  "message": {
        "explain_text": "Body description",
        "options": [
            {
                "label": "Button text",
                "value": "Send message",
                "type": "text"
            },
            {
                "label": "Make a call",
                "type": "phonenumber",
                "number": "+886012345679"
            },
            {
                "label": "Open URL",
                "type": "url",
                "url": "https://www.firstline.cc/"
            }
        ]
    }
}
```

### Quick Reply

| Attribute        | 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 (exists only 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

Used to send carousel content that can be swiped left and right. Each carousel item includes an image, a brief description, and buttons.

<table><thead><tr><th width="268">Attribute</th><th>Description</th></tr></thead><tbody><tr><td>alt_text</td><td>Prompt 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>Text for the action button or link</td></tr><tr><td>columns[].actions[].value</td><td>Value of the action button or link</td></tr><tr><td>columns[].actions[].url</td><td>URL of the action button or link (exists only when type is url)</td></tr><tr><td>columns[].actions[].type</td><td>Type of the action button or link, e.g. url or text</td></tr><tr><td>columns[].actions[].label</td><td>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": "Omnichannel customer service system",
        "text": "Integrates multiple communication channels, including phone, LINE, Facebook, live chat, WhatsApp, etc., enabling 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**

<table><thead><tr><th width="320">Attribute</th><th>Description</th></tr></thead><tbody><tr><td>alt_text</td><td>Prompt 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 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>Button text</td></tr><tr><td>columns[].button.background_color</td><td>Background color of the button, in HEX color code</td></tr><tr><td>columns[].button.border_color</td><td>Border color of the button, in HEX color code</td></tr><tr><td>columns[].button.color</td><td>Text color of the button, in HEX color code</td></tr><tr><td>columns[].badge.text</td><td>Label text</td></tr><tr><td>columns[].badge.background_color</td><td>Background color of the label, in HEX color code</td></tr><tr><td>columns[].badge.border_color</td><td>Border color of the label, in HEX color code</td></tr><tr><td>columns[].badge.color</td><td>Text color of the label, in 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": "Register now",
                    "background_color": "#09091A",
                    "border_color": "#09091A",
                    "color": "#09091A"
                },
                "badge": {
                    "text": "SALE",
                    "background_color": "#eb4d4b",
                    "border_color": "#eb4d4b",
                    "color": "#FFFFFF"
                }
            }
        ]
    }
}
````