登入開始免費試用
easyCoexistence 官方 API

Instagram messaging_referral Webhook:ig.me 連結與廣告推薦

Instagram 的 messaging_referral Webhook 欄位會在已與專業帳戶有對話的用戶開啟帶有 ref 參數的 ig.me 連結時,通知應用程式。事件中有一個頂層 referral 物件:ref 為參數值;source 為 SHORTLINKS;type 為 OPEN_THREAD。新對話中的 ref 則會改在 messages 或 messaging_postbacks 事件內送達。

easyCoexistence 會為每個已連接的 Instagram 帳戶訂閱 comments、messages 與 mentions,因此新對話首則訊息中的 ref,以及 Click-to-Direct 廣告的推薦,都會在轉發的 DM 內送達你的 HTTPS 端點,並以該帳戶的密鑰簽署。

2,083

ig.me ref 參數最多可容納的字元數,只可使用英文字母、數字、連字號、底線與等號。

OPEN_THREAD

ig.me 連結的推薦類型;Click-to-Direct 廣告的推薦同樣使用此類型,但 source 為 ADS。

24 hours

應用程式在現有對話中收到推薦後可作出回覆的時限,此舉會重設標準時間窗口。

7 days

點擊 Click-to-Direct 廣告後發出首則訊息,所開啟時間窗口的長度。

Instagram Web

根據 Meta 的 ig.me 指南,不支援 ig.me 連結的平台。

messaging_referral 何時觸發?

當用戶已與專業帳戶有對話,並開啟帶有 ref 參數的 ig.me 連結時觸發。Instagram 會開啟現有對話串,Meta 會自行發送推薦,不附帶訊息。推薦會在哪裡送達,取決於對話串及用戶的操作:

Existing threadmessaging_referral: a referral object beside sender, with no message.
New thread, ice breaker tappedmessaging_postbacks: postback.referral beside title and payload.
New thread, message typedmessages: message.referral beside mid.
Click-to-Direct admessages: message.referral with source ADS, ad_id and ads_context_data.

推薦通知是什麼樣子?

一則訊息事件,其 referral 物件與 sender、recipient 及 timestamp 並列,前後不附帶 message 或 postback。Meta 的 ig.me 指南列出推薦的值,與其他 Instagram 訊息事件位於同一結構內:

A messaging_referral notification
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "referral": {
            "ref": "<REF_PARAMETER_VALUE>",
            "source": "SHORTLINKS",
            "type": "OPEN_THREAD"
          }
        }
      ]
    }
  ]
}

referral 的各欄位分別代表什麼?

以下為 Meta 為 ig.me 推薦所記載的欄位,由外至內排列:

  • sender.id:開啟連結之用戶的 Instagram 範圍 ID。recipient.id 與 entry[].id:專業帳戶。
  • referral.ref:連結中 ref 參數的值,與連結所攜帶的內容一致。
  • referral.source:Meta 的 ig.me 範例中為 SHORTLINKS。Meta 的 Instagram 訊息指南中有一個表格拼寫為 SHORTLINK,其範例頁面則顯示佔位符。
  • referral.type:OPEN_THREAD,Meta 用於 ig.me 推薦。
  • timestamp:事件觸發的時間,Meta 範例中以毫秒計。

如何建立帶有 ref 的 ig.me 連結?

格式為 https://ig.me/<USERNAME>?ref=<VALUE>,其中 USERNAME 為專業帳戶的用戶名稱,見 Meta 的 Instagram Login 指南;其 Instagram 訊息指南則寫作 https://ig.me/m/<USERNAME>。ref 最多可達 2,083 個字元,只可使用英文字母、數字、連字號、底線與等號。Meta 建議用 ref 追蹤渠道、把用戶與另一應用程式的工作階段連繫,或引導至特定內容,並建議為新對話設置各自附有 ref 的 ice breaker。

廣告推薦在哪裡送達?

在 messages 事件中送達。用戶點擊開啟 Instagram Direct 的廣告並發送訊息後,會產生一則 messages 事件,其 message.referral 包含廣告的 ref(如有設定)、ad_id、source ADS、type OPEN_THREAD,以及 ads_context_data,當中有廣告標題,以及用戶點擊的 photo_url 或 video_url。Meta 的 Instagram 頁面只記載 ig.me 連結的 messaging_referral。

A Click-to-Direct ad referral, inside messages
"message": {
  "mid": "<MESSAGE_ID>",
  "referral": {
    "ref": "<AD_REF_IF_SET>",
    "ad_id": "<AD_ID>",
    "source": "ADS",
    "type": "OPEN_THREAD",
    "ads_context_data": {
      "ad_title": "<AD_TITLE>",
      "photo_url": "<IMAGE_URL_CLICKED>",
      "video_url": "<THUMBNAIL_URL_FOR_THE_AD_VIDEO>"
    }
  }
}

推薦會開啟訊息時間窗口嗎?

在現有對話中會。Meta 的 ig.me 指南指出,推薦會重設 24 小時的標準訊息時間窗口,因此應用程式可於事件發生後 24 小時內回覆。點擊 Click-to-Direct 廣告後發出的首則訊息,可開啟由該則訊息起計最長 7 天的時間窗口。回覆時使用 POST /<IG_ID>/messages,並將 recipient.id 設為事件的 sender.id。

easyCoexistence 會轉發推薦嗎?

會轉發附於訊息的推薦。每個已連接的 Instagram 帳戶都會訂閱 comments、messages 與 mentions,因此新對話首則訊息中的 ref,以及 Click-to-Direct 廣告的推薦,都會以 message.referral 形式,於轉發的 DM 內送達你的端點。messaging_referral(用於現有對話串)與 messaging_postbacks(用於 ice breaker 點擊)則是獨立欄位,由 Meta 傳送給已訂閱它們的應用程式。

常見錯誤

  • 在新對話中等待 messaging_referral。新對話中的 ref 會按用戶是輸入還是點擊 ice breaker,而在 messages 或 messaging_postbacks 中送達。
  • 在 ref 中使用其他字元。Meta 只接受英文字母、數字、連字號、底線與等號,最多 2,083 個字元。
  • 將 source 與單一完整字串作比對。Meta 的範例中,ig.me 為 SHORTLINKS,廣告為 ADS,但其中一個表格寫作 SHORTLINK,因此應按推薦所在位置及 ref 進行判斷。
  • 在 Instagram Web 上測試連結。Meta 不支援在 Instagram Web 上使用 ig.me 連結,請在 Instagram 應用程式中開啟。
使用 EasyCoexistence 完成這項設定

send_social_dm 會在 24 小時時間窗口內回覆。每個連接每月 US$ 9 至 US$ 0.75,連接越多越便宜,首 3 天免費。

常見問題

referral.source 在 Instagram 推薦中包含什麼?

Meta 的 ig.me 範例為 SHORTLINKS,廣告的 Click-to-Direct 推薦則為 ADS,不過 Meta 的 Instagram 訊息指南中有一個表格寫作 SHORTLINK。應按推薦所在位置及 ref 進行判斷,而非依賴單一的完整字串。

ig.me 的 ref 參數最長可以多長?

最多 2,083 個字元,只可使用英文字母、數字、連字號、底線與等號。

ig.me 的 ref 在 Instagram 新對話中於何處送達?

用戶輸入首則訊息時在 messages 送達,點擊 ice breaker 時則在 messaging_postbacks 送達。messaging_referral 只涵蓋現有對話串。

ig.me 連結能否在 Instagram Web 上運作?

不能。Meta 的 ig.me 指南指出,Instagram Web 不支援此類連結。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期