# 應用 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": "超愛！",
        }
      ]
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-tw.yoctol.ai/settings/json_api_messenger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.