# PUSH API 發送訊息

{% hint style="success" %}
此 API 為版本 v.3.00.00 後提供。
{% endhint %}

## 概述

當你需要向特定的用戶發送個性化的訊息時，你可以利用 FIRST LINE 的 PUSH API 來進行整合。這種整合方式可以讓您更有效地傳達訊息。

此外，使用 PUSH API 也可以幫助你節省時間和資源，因為您不需要自己從頭開始建立訊息傳遞系統。只需簡單的幾步操作，就可以開始發送個性化的訊息給你的用戶。

## API 

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

### Response

回傳為 JSON 格式，而 HTTP status 為代碼 200，表示發送成功。

```html
{}
```

### URL Parameters

<table><thead><tr><th width="251">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>contactable_type</td><td><p>管道類型包括以下選項：</p><ul><li><strong>即時聊天</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>微信</strong>：<code>App\WechatContact</code></li></ul></td></tr><tr><td>contactable_id</td><td>為對應各訊息管道的聯絡人系統識別編號，通常可於 <strong>Contact API</strong> 回傳的社群媒體相關資料中取得。</td></tr><tr><td>type</td><td><p></p><p>訊息類型分為以下幾種：</p><ul><li><strong>text</strong>：文字</li><li><strong>carousel</strong>：輪播</li><li><strong>image_carousel</strong>：圖片輪播</li><li><strong>button</strong>：按鈕</li><li><strong>quickreply</strong>：快速回覆</li></ul></td></tr><tr><td>message</td><td><code>message</code> 資訊是根據不同的訊息類型所定義的內容。舉例來說，當 <code>type</code> 設定為 <code>text</code> 時，<code>message</code> 的內容可能會是 '嗨！你好嗎！'。</td></tr><tr><td>is_force</td><td>當交談處於某些特定狀態，如客戶正與專員對話時，預設是不允許透過API發送訊息的。但若設定值為 1，即表示將強制發送訊息，即便交談已經開始。</td></tr></tbody></table>

## Message 欄位訊息格式

### 文字訊息 Text

```json
{
  "type": "text",
  "message": "要傳送的文字訊息"
}
```

### 按鈕 Button

| 屬性                | 介紹                              |
| ----------------- | ------------------------------- |
| explain\_text     | 內文描述                            |
| options\[].label  | 按鈕或選項的文字描述                      |
| options\[].value  | 要發送的訊息值                         |
| options\[].type   | 選項的類型（如 text、phonenumber、url）   |
| options\[].number | 電話號碼(僅在 type 為 phonenumber 時存在) |
| options\[].url    | 需要開啟的網址(僅在 type 為 url 時存在)      |

```json
{
  "type": "button",
  "message": {
        "explain_text": "內文描述",
        "options": [
            {
                "label": "按鈕文字",
                "value": "發送訊息",
                "type": "text"
            },
            {
                "label": "撥打電話",
                "type": "phonenumber",
                "number": "+886012345679"
            },
            {
                "label": "開啟網址",
                "type": "url",
                "url": "https://www.firstline.cc/"
            }
        ]
    }
}
```

### 快速回覆 Quick Reply

| 屬性               | 介紹                                  |
| ---------------- | ----------------------------------- |
| explain\_text    | 內文訊息，文字欄位                           |
| options\[].label | 選項的標籤                               |
| options\[].value | 選項的值                                |
| options\[].type  | 選項的類型，例如：url 或 text                 |
| options\[].url   | 當選項類型為url時，該選項對應的網址 (僅在type為url時存在) |

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

### 輪播訊息 C**arousel**

用於發送可左右滑動的輪播內容。每一個輪播項目均包含圖片、簡短的描述與按鈕。

<table><thead><tr><th width="268">屬性</th><th>介紹</th></tr></thead><tbody><tr><td>alt_text</td><td>提示消息或當消息格式不受支援時發送</td></tr><tr><td>columns[].image_url</td><td>背景圖片的URL地址</td></tr><tr><td>columns[].title</td><td>標題</td></tr><tr><td>columns[].text</td><td>文本描述</td></tr><tr><td>columns[].actions[].text</td><td>操作按鈕或連結的文本</td></tr><tr><td>columns[].actions[].value</td><td>操作按鈕或連結的值</td></tr><tr><td>columns[].actions[].url</td><td>操作按鈕或連結的URL (僅在type為url時存在)</td></tr><tr><td>columns[].actions[].type</td><td>操作按鈕或連結的類型，例如：url 或 text</td></tr><tr><td>columns[].actions[].label</td><td>操作按鈕或連結的標籤 (如果存在)</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": "全方位客服系統",
        "text": "整合多種溝通管道，包括電話、LINE、Facebook、即時聊天、WhatsApp等，讓您能高效地提供客戶支援和銷售服務。",
        "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 客服系統"
          },
          {
            "label": null,
            "value": "其他",
            "type": "text",
            "url": null,
            "text": "其他"
          }
        ]
      },
    ]
}

```

### **圖片輪播 Image Carousel**&#x20;

<table><thead><tr><th width="320">屬性</th><th>介紹</th></tr></thead><tbody><tr><td>alt_text</td><td>提示消息或當消息格式不受支援時發送</td></tr><tr><td>columns[].image_url</td><td>背景圖片的URL地址</td></tr><tr><td>columns[].action.type</td><td>操作的類型（可能為null），例如：url 或 text</td></tr><tr><td>columns[].action.url</td><td>操作的URL地址（可能為null）</td></tr><tr><td>columns[].action.value</td><td>操作的值（可能為null）</td></tr><tr><td>columns[].button.text</td><td>按鈕的文本</td></tr><tr><td>columns[].button.background_color</td><td>按鈕的背景顏色，為 HEX 顏色代碼</td></tr><tr><td>columns[].button.border_color</td><td>按鈕的邊框顏色，為 HEX 顏色代碼</td></tr><tr><td>columns[].button.color</td><td>按鈕的文字顏色，為 HEX 顏色代碼</td></tr><tr><td>columns[].badge.text</td><td>標籤的文本</td></tr><tr><td>columns[].badge.background_color</td><td>標籤的背景顏色，為 HEX 顏色代碼</td></tr><tr><td>columns[].badge.border_color</td><td>標籤的邊框顏色，為 HEX 顏色代碼</td></tr><tr><td>columns[].badge.color</td><td>標籤的文字顏色，為 HEX 顏色代碼</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": "立即註冊",
                    "background_color": "#09091A",
                    "border_color": "#09091A",
                    "color": "#09091A"
                },
                "badge": {
                    "text": "SALE",
                    "background_color": "#eb4d4b",
                    "border_color": "#eb4d4b",
                    "color": "#FFFFFF"
                }
            }
        ]
    }
}
```