Send API 參考資料

Send API 是用於向用戶傳送訊息的主要 API,包括文字、附件、範本、傳送者動作等。

建立

建立訊息並傳送給您的顧客或對您 Facebook 專頁感興趣的用戶。

準備工作

您將需要:

  • 由可在專頁上執行 MESSAGE 任務的用戶所要求獲取的專頁存取憑證
  • pages_messaging 權限
  • 訊息傳送對象必須已在最近 24 小時內向您的專頁傳送訊息,或者同意在標準 24 小時訊息期限以外接收來自您專頁的訊息

限制

  • 訊息標籤無法用於傳送推廣內容

請注意,如果是使用 recipient.user_ref recipient.phone_number 傳送的訊息,傳送 API 不會在回應中加入 recipient_id 來識別訊息傳送對象。

要求範例

如要傳送訊息給用戶,請向 /PAGE-ID/messsages 端點傳送 POST 要求,其中包含已設定的 messaging_typerecipient 參數,以及訊息內容。

我們已設定特定格式以便閱讀。

以下範例是對用戶訊息的回覆,其中專頁傳送的是純文字訊息。

curl -X POST "https://graph.facebook.com/v21.0/{PAGE_ID}/messages" \
      -d "recipient={'id':'{PSID}'}" \
      -d "messaging_type=RESPONSE" \
      -d "message={'text':'hello, world'}" \
      -d "access_token={PAGE_ACCESS_TOKEN}"

成功的話,應用程式將會收到以下 JSON 回應:

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
} 

參數

參數說明

message

物件

專頁傳送的訊息類型。使用此參數時必須設定 textattachement 其一。

  • attachment 物件:網址預覽,用於傳送帶有媒體的訊息和結構化訊息。必須設定 textattachment 其一。

    • type:附件類型,可以是 audiofileimagetemplatevideo。檔案大小上限為 25 MB
    • payload:內含範本內容檔案內容的物件
  • metadata:要在 message_echo Webhook 中傳遞的額外資料字串。上限為 1000 個字元

  • quick_replies:要在訊息中傳送的快速回覆陣列
  • text:只包含文字的訊息。格式必須為 UTF-8,上限為 2000 個字元。

messaging_type

列舉

必要項目

所傳送訊息的類型

  • RESPONSE:這類訊息是用來回覆已收到的訊息,包括在 24 小時標準訊息期間內所傳送的推廣和非推廣訊息。舉例來說,如有用戶要求確認預約或想了解最新動態,您便可使用這個標籤來回覆。
  • UPDATE:這類訊息為主動傳送,並非用來回覆已收到的訊息。包括在 24 小時標準訊息期間內所傳送的推廣和非推廣訊息。
  • MESSAGE_TAG:這類訊息為非推廣訊息,且是在 24 小時標準訊息期間過後使用訊息標籤所傳送。這類訊息必須符合標籤的允許使用案例。

notification_type

列舉

用戶收到的推送通知類型

  • NO_PUSH:無通知
  • REGULAR(預設):用戶收到訊息時發出聲音或震動
  • SILENT_PUSH:僅傳送螢幕通知

recipient

物件

必要項目

您專頁所傳送訊息的接收者

  • id:專頁範圍用戶編號,用於傳送訊息以回應您專頁在過去 24 小時內所收到的訊息,或適用於已同意在標準 24 小時訊息期限以外接收您專頁訊息的用戶
  • user_ref:用戶參考資料,用於傳送訊息以回應選框附加程式或顧客洽談附加程式
  • comment_id:留言編號,用於以私人回覆形式傳送訊息,以回應您專頁帖子上的訪客留言
  • post_id:專頁帖子編號,用於以私人回覆形式傳送訊息,以回應您專頁上的訪客帖子

sender_action

列舉

訊息視窗中顯示的操作圖示,表示專頁對專頁從用戶處收到的訊息所採取的操作。

  • typing_on:在專頁準備回應時顯示打字泡泡
  • typing_off:不顯示打字泡泡
  • mark_seen:為已由專頁讀取的訊息顯示已讀圖示

只可與 recipient 參數一併傳送。不可與 message 參數一併傳送,必須作為個別要求傳送。

tag

列舉

使您的專頁能夠在標準 24 小時訊息期間以外向用戶傳送訊息的標籤。

  • ACCOUNT_UPDATE:將您傳送給顧客的訊息標註為對其應用程式或帳戶的非定期更新。查看所有允許的使用方式。

    不適用於 Instagram 訊息 API。

  • CONFIRMED_EVENT_UPDATE:將您傳送給顧客的訊息標註為即將舉行的活動之提醒,或顧客已登記的進行中活動的更新。查看所有允許的使用方式。

    不適用於 Instagram 訊息 API。

  • CUSTOMER_FEEDBACK:將您傳送給顧客的訊息標註為顧客意見問卷調查 。顧客意見問卷調查必須在收到顧客最後一則訊息的 7 天內傳送。查看所有允許的使用方式。

    不適用於 Instagram 訊息 API。

  • HUMAN_AGENTInstagram 訊息 API 的必要項目。在傳送給用戶的訊息中加入這個標籤後,系統即會允許真人服務人員回覆該用戶的訊息。您可在收到用戶訊息的 7 天內傳送訊息。真人服務人員支援服務用於處理無法在標準訊息期間內解決的問題。查看所有允許的使用方式。
    • 應用程式需透過開發人員應用程式管理中心申請 Human Agent 權限。前往應用程式管理中心 -> 應用程式審查 -> 權限和功能 -> 真人服務人員。應用程式如曾獲准使用測試版 Human Agent 權限,則無需再次申請存取權。

    標準存取權限或開發模式中尚未能使用 Human Agent 權限。使用真人服務人員標籤之前,您需要完成應用程式審查流程。在應用程式審查申請提交期間,請提供清晰的說明和演示,說明您打算如何在體驗中運用真人服務人員標籤。

  • POST_PURCHASE_UPDATE:將您傳送給顧客的訊息標註為顧客最近購買項目的更新。查看所有允許的使用方式。

    不適用於 Instagram 訊息 API。

訊息標籤使用方式

下表列出每種訊息標籤的訊息類型。

訊息標籤使用方式

ACCOUNT_UPDATE

允許使用方式

  • 申請狀態變更通知,例如信用卡或職位申請狀態變更
  • 可疑活動通知,例如欺詐警示

不適用的使用方式(非盡列)

  • 推廣內容,包括但不限於交易、推廣活動、優惠券和折扣;重複出現的內容,例如結單已準備就緒、帳單到期、新工作機會
  • 提示用戶參與跟 Messenger 上過往互動無關的任何問卷調查、投票活動或評論

不適用於 Instagram 訊息 API。

CONFIRMED_EVENT_UPDATE

允許使用方式

  • 提醒用戶已安排的課程、會面或活動即將開始
  • 確認用戶已預約或參加已接受邀請的活動或會面
  • 通知用戶交通或旅程安排,例如抵達、取消、行李延誤或其他旅行狀態變更

不適用的使用方式(非盡列)

  • 推廣內容,包括但不限於促銷特價、優惠、優惠券和折扣
  • 用戶未登記的活動相關內容(如提醒購買活動門票、交叉銷售其他活動,以及巡迴活動行程表等)
  • 與過往活動相關的訊息
  • 提示用戶參與跟 Messenger 上過往互動無關的任何問卷調查、投票活動或評論

不適用於 Instagram 訊息 API。

CUSTOMER_FEEDBACK

允許使用方式

  • 購物支援意見問卷調查
  • 活動意見問卷調查
  • 商品評論

不適用的使用方式(非盡列)

  • 此標籤只能與顧客意見範本一起使用。禁止以任何其他形式使用,否則無效。

不適用於 Instagram 訊息 API。

HUMAN_AGENT

允許使用方式

  • 真人服務人員會為無法在 24 小時標準訊息時限內解決的問題提供支援,例如解決正常營業時間以外的問題或需要 24 小時以上才能解決的問題

不適用的使用方式(非盡列)

  • 自動訊息
  • 內容與用戶查詢無關

Instagram 訊息 API 必要項目。

POST_PURCHASE_UPDATE

允許使用方式

  • 交易確認,例如帳單或收據
  • 送貨服務狀態更新,例如產品運送中、已出貨、已送達或延遲
  • 狀態更新,通知用戶須就已提交訂單採取行動,例如信用卡遭拒絕、缺貨項目或需要用戶採取行動的其他訂單更新

不適用的使用方式(非盡列)

  • 推廣內容,包括但不限於促銷特價、推廣活動、優惠券和折扣
  • 交叉銷售、追加銷售或服務的訊息
  • 提示用戶參與跟 Messenger 上過往互動無關的任何問卷調查、投票活動或評論

不適用於 Instagram 訊息 API。

讀取

您無法在此端點上執行此操作。

如要取得您專頁參與的對話資訊,請瀏覽專頁對話參考資料

更新

您無法在此端點上執行此操作。

刪除

您無法在此端點上執行此操作。

另請參閱

開發人員支援