> For the complete documentation index, see [llms.txt](https://docs-tw.yoctol.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-tw.yoctol.ai/settings/json_api_messenger.md).

# 應用 API 元件 - Messenger

### **功能簡介**

**JSON API** 是一個進階元件，提供您強大的自由度與功能。透過 JSON API，您將可以連結機器人與您的伺服器後端，完成高度彈性的回應與額外功能。

您可以發送多種不同 HTTP 請求方法，讓機器人解析您的伺服器回應並回覆訊息。

具體而言，您將可以執行：

1. 創建動態訊息
2. 執行 postbacks
3. 取得並設定使用者參數（即將到來）
4. 轉向其他節點（即將到來）

### **回傳參考**

我們將解析您回傳的 JSON，以此為根據發送訊息給您的顧客。更多訊息請參考 [Messenger API 文件](https://developers.facebook.com/docs/messenger-platform/reference/send-api/)。

#### **發送文字**

以下回應將發送文字訊息。

```
{
  "messages": [
    { "text": "歡迎使用最聰明的聊天機器人平台 —— YOCTOL.AI" },
    { "text": "您打算創建怎樣的機器人呢？" }
  ]
}
```

#### 發送圖片

目前圖片格式支援 JPG、PNG、GIF，以下回應將發送圖片訊息。

```
{
  "messages": [
    {
      "attachment": {
        "type": "image",
        "payload": {
          "url": "https://yoctol.ai/images/logo.svg"
        }
      }
    }
  ]
}
```

您也可以發送既有的 Facebook 貼文圖片，這樣就不用重新上傳囉！

```
{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_type": "image",
              "url": "https://www.facebook.com/Yoctol/photos/2200581453590553",
              "buttons": [
                {
                  "title": "前往 Yoctol!",
                  "type": "web_url",
                  "url": "https://www.yoctol.com/"
                }
              ]
            }
          ]
        }
      },
      "quick_replies": [
        {
          "content_type": "text",
          "title": "我也想加入優拓！",
          "payload": <TEXT PAYLOAD>
        }
      ]
    }
  ]
}
```

#### 發送影片

以下回應將發送影片檔案。目前 Messenger 僅支援 25MB 以下的 MP4。

```
{
  "messages": [
    {
      "attachment": {
        "type": "video",
        "payload": {
          "url": "https://ytstatic.blob.core.windows.net/yoctol-ai-website/landing-page.mp4"
        }
      }
    }
  ]
}
```

當然，您也可以使用既有的 Facebook 貼文影片來發送！

```
{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_type": "video",
              "url": "https://www.facebook.com/Yoctol/videos/1733376656977704/",
              "buttons": [
                {
                  "title": "來看看 Yoctol",
                  "type": "web_url",
                  "url": "https://www.yoctol.com/"
                }
              ]
            }
          ]
        }
      },
      "quick_replies": [
        {
          "content_type": "text",
          "title": "That's cool!",
          "payload": <TEXT PAYLOAD>
        }
      ]
    }
  ]
}
```

#### 發送語音

以下回應將發送語音檔案；目前 Messenger 僅支援 25MB 以下的 MP3、OCG、WAV 語音檔。

```
{
  "messages": [
    {
      "attachment": {
        "type": "audio",
        "payload": {
          "url": "https://ccrma.stanford.edu/~jos/mp3/bachfugue.mp3"
        }
      }
    }
  ]
}
```

#### 發送檔案

以下回應將發送檔案。目前 Messenger 僅支援 25MB 以下的檔案，不分檔案類型。

```
{
  "messages": [
    {
      "attachment": {
        "type": "file",
        "payload": {
          "url": "http://www.africau.edu/images/default/sample.pdf"
        }
      }
    }
  ]
}
```

#### 發送圖文模組

以下回應將發送圖文模組。請注意圖文模組中的每一個項目都包含圖片、描述、與按鈕。

```
{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "generic",
          "image_aspect_ratio": "square",
          "elements": [
            {
              "title": "Yoctol Image 1",
              "image_url": "https://www.yoctol.com/images/amazingBrain.png",
              "subtitle": "Size: M",
              "buttons": [
                {
                  "type": "web_url",
                  "url": "https://www.yoctol.com",
                  "title": "View Item"
                }
              ]
            },
            {
              "title": "Yoctol Image 2",
              "image_url": "https://www.yoctol.com/images/amazingBrain.png",
              "subtitle": "Size: L",
              "default_action": {
                "type": "web_url",
                "url": "https://www.yoctol.com",
              },
              "buttons": [
                {
                  "type": "web_url",
                  "url": "https://www.yoctol.com",
                  "title": "View Item"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}
```

#### 發送清單範本

以下回應將發送清單範本，更多設定請參考 [Messenger 清單範本](https://developers.facebook.com/docs/messenger-platform/send-messages/template/list/)。

```
{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "list",
          "top_element_style": "large",
          "elements": [
            {
              "title": "Yoctol List Image 1",
              "image_url": "https://www.yoctol.com/images/amazingBrain.png",
              "subtitle": "Size: M",
              "buttons": [
                {
                  "type": "web_url",
                  "url": "https://www.yoctol.com",
                  "title": "查看商品"
                }
              ]
            },
            {
              "title": "Yoctol List Image 2",
              "image_url": "https://www.yoctol.com/images/amazingBrain.png",
              "subtitle": "Size: L",
              "default_action": {
                "type": "web_url",
                "url": "https://www.yoctol.com",
              },
              "buttons": [
                {
                  "type": "web_url",
                  "url": "https://www.yoctol.com",
                  "title": "查看商品"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}
```

#### 按鈕

以下回應將發送按鈕。您可以設定各個按鈕的動作，例如打開網站。更多關於按鈕的用法，請參考 [Messenger 按鈕](https://developers.facebook.com/docs/messenger-platform/send-messages/buttons)。

```
{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "button",
          "text": "您好",
          "buttons": [
            {
              "type": "web_url",
              "url": "https://www.yoctol.com",
              "title": "打開網站"
            }
          ]
        }
      }
    }
  ]
}
```

另外您也可以傳送特殊按鈕，例如撥打電話、分享。

```
{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "generic",
          "elements": [
            {
              "title": "想知道更多嗎？",
              "image_url": "https://www.yoctol.com/images/amazingBrain.png",
              "subtitle": "可以和我們直接聯絡！若覺得我們的服務很棒，請不吝分享給大家！",
              "buttons": [
                {
                  "type": "phone_number",
                  "phone_number": "+886223222168",
                  "title": "打給客服"
                },
                {
                  "type": "element_share"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}
```

#### 快速回覆

以下回應將發送快速回覆。

```
{
  "messages": [
    {
      "text": "請問你喜歡剛才提供的餐點嗎?",
      "quick_replies": [
        {
          "title": "超愛！",
        }
      ]
    }
  ]
}
```