WhatsApp Business 平台企業內部 API

已接收訊息通知

當您收到傳入訊息時，系統會向您在應用程式設定中設定的 Webhook 網址傳送通知。本文件會詳細介紹您可以接收的傳入訊息並提供相關範例。

通知物件

已接收訊息通知可包含以下物件：

當您收到包含媒體的訊息時，WhatsApp Business API 用戶端便會下載相關內容。下載媒體後，系統會向您的 Webhook 傳送一則通知。此通知包含的資訊可識別媒體物件，並讓您找出和擷取該物件。請使用包含媒體 id 的媒體端點來擷取媒體。

已接收訊息範例

文字訊息

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
      },
    "wa_id": "16315551234"
  }],
  "messages":[{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1518694235",
    "text": {
      "body": "Hello this is an answer"
    },
    "type": "text"
  }]
}

靜態地點訊息

{
  "contacts": [{
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
 "messages":[{
   "from":"16315551234",
   "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
   "location":{
      "address":"Main Street Beach, Santa Cruz, CA",
      "latitude":38.9806263495,
      "longitude":-131.9428612257,
      "name":"Main Street Beach",
      "url":"https://foursquare.com/v/4d7031d35b5df7744"},
   "timestamp":"1521497875",
   "type":"location"
 }]
}

聯絡人訊息

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "contacts": [{
      "addresses": [{
        "city": "Menlo Park",
        "country": "United States",
        "country_code": "us",
        "state": "CA",
        "street": "1 Hacker Way",
        "type": "WORK",
        "zip": "94025"
      }],
      "birthday": "2012-08-18",
      "emails": [{
        "email": "kfish@fb.com",
        "type": "WORK"
      }],
      "ims": [{
        "service": "AIM",
        "user_id": "kfish"
      }],
      "name": {
        "first_name": "Kerry",
        "formatted_name": "Kerry Fisher",
        "last_name": "Fisher"
      },
      "org": {
        "company": "Meta",
 	"department": "WhatsApp"
      },
      "phones": [{
        "phone": "+1 (940) 555-1234",
        "type": "CELL"
        },
        {
          "phone": "+1 (650) 555-1234",
          "type": "WORK",
          "wa_id": "16505551234"
      }],
      "urls": [{
        "url": "https://www.facebook.com",
        "type": "WORK"
      }]
    }],
    "from": "16505551234",
    "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
    "timestamp": "1537248012",
    "type": "contacts"
  }]
}

如果消費者用戶端使用的是 iPhone，則 contact_image 設定為空。

媒體訊息

包含圖片的訊息：

{
	"messages": [{
		"from": "16315551234",
		"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
		"image": {
			"file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
			"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
			"mime_type": "image/jpeg",
			"sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
			"caption": "Check out my new phone!",
			"status": "downloaded"
		},
		"timestamp": "1521497954",
		"type": "image"
	}]
}

由 2.49.1 版開始，媒體訊息 Webhooks 會包含已接收媒體的狀態和編號。

下載狀態

州／省說明

downloaded

已成功下載媒體

retriable

未下載媒體，但可以使用重試端點再次嘗試下載

undownloaded

未能下載媒體

如果是媒體訊息，caption 欄位為選用欄位。系統僅會在用戶設定說明文字時加入此欄位。

包含文件的訊息：

{
  "messages": [{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1522189546",
    "type": "document",
    "document": {
      "caption": "80skaraokesonglistartist",
			"file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33",
			"id": "fc233119-733f-49c-bcbd-b2f68f798e33",
			"mime_type": "application/pdf",
			"sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e",
			"status": "downloaded"
		}
	}]
}

語音訊息：

{
    "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "voice",
        "voice": {
            "file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
            "id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
            "mime_type": "audio/ogg; codecs=opus",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710",
            "status": "downloaded"
        }
  }]
}

包含貼圖的訊息：

{
  "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "sticker",
        "sticker": {
            "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
            "metadata": {
                "sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
                "sticker-pack-name" : "Happy New Year",
                "sticker-pack-publisher" : "Kerry Fisher",
                "emojis": ["🐥", "😃"],
                "ios-app-store-link" : "https://apps.apple.com/app/id3133333",
                "android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example",
                "is-first-party-sticker" : 0 | 1 # integer 
            },
            "mime_type": "image/webp",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
        }  
    }]
}

WhatsApp 發訊廣告帶來的訊息

{
   "messages":[{
      "from":"12345678",
      "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "image":{
         "id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
         "mime_type":"image/jpeg",
         "sha256":"29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db"
         "caption": "Check out my product!",
      },
      "timestamp":"1521497954",
      "type":"image",
      "referral" : {
        "headline": "Our new product",
        "body" : "This is a great product",
        "source_type": "<SOURCE_TYPE>",
        "source_id": "<SOURCE_ID>",
        "source_url": "<SOURCE_URL>", //for the moment, this will always be a Facebook owned domain
        "video": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45",
        "ctwa_clid": "<CTWA_CLID>",
      }     
    }
  }]
}

請在此處進一步了解 referral 屬性。

範例：不支援的訊息

您可能會收到 unknown 回調通知。以下這個範例屬於從顧客處收到的不支援訊息類型。

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
  "messages": [{
		"errors": [{
			"code": 501,
			"details": "Message type is not currently supported",
			"title": "Unknown message type"
		}],
		"from": "16315551234",
		"id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
		"timestamp": "1531933468",
		"type": "unknown"
	}]
}

轉寄訊息

您可以查看收到的訊息是否已被轉寄或經常被轉寄。這是轉寄訊息的通知：

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sOGh7pv13wVJ",
    "text": {
      "body": "Party at Dotty's tonight!"
    },
    "timestamp": "1593068329",
    "type": "text"
  }]
}

這是經常被轉寄訊息的通知：

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "frequently_forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl",
    "timestamp": "1593068225",
    "type": "video",
    "video": {
      "id": "e144be57-12b1-4035-a520-703fcc87ef45",
    "mime_type": "video/mp4",
    "sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9"
    }
  }]
}

已啟用安全通知

如果 show_security_notifications 參數在應用程式設定中設為 true，所有傳入訊息通知均會包含下列關於用戶身分的訊息（位於 identity 物件內）：

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
   "messages": [{
        "from": "16315553601",
        "id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
        "identity": {
            "acknowledged": true,
            "created_timestamp": 1602532300000,
            "hash": "Sjvjlx8G6Z0="
        },
        "text": {
            "body": "Hi from new number 3601"
        },
        "timestamp": "1602532300",
        "type": "text"
    }]
}

透過點擊快速回覆按鈕傳送的訊息

當客戶點擊快速回覆按鈕時，系統便會傳送回應。以下是回調格式範例。請注意：客戶可能不會點擊按鈕，而是會回覆互動訊息或只是向您傳送訊息。請確保您亦能夠支援這類情況。如需更多資訊，請參閱 Webhooks 文件。
{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16505551234"
        }
    ],
    "messages": [
        {
            "button": {
                "payload": "No-Button-Payload",
                "text": "No"
            },
            "context": {
                "from": "16315558007",
                "id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
            },
            "from": "16505551234",
            "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
            "timestamp": "1591210827",
            "type": "button"
        }
    ]
    # If there are any errors, an errors field (array) will be present        
    "errors": [ { ... } ]
}

對已傳送訊息的傳入回覆

用戶可以回覆 WhatsApp 中的特定訊息。為了讓企業了解訊息回覆的背景，我們加入了 context 物件。此 context 物件會提供顧客所回覆訊息的 id、原來訊息傳送者的 WhatsApp 編號，以及顧客可能提及的任何產品之編號。

回覆訊息載有更多資訊。

範例：顧客回覆了您的訊息

以下是回覆您先前傳送的訊息之已接收訊息範例。如需更多資訊，請參閱下方的 context 物件部分。

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
   "messages":[{
      "context":{
         "from":"16315558011",
         "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf"
         },
      "from":"16315551234",
      "id":"gBGGFlA5FpafAgkOuJbRq54qwbM",
      "text":{"body":"Yes, count me in!"},
      "timestamp":"1521499915",
      "type":"text"
  }]
}

如果是媒體訊息，text 欄位為選填欄位。如有這個欄位，則 text 的值為已傳送媒體的說明文字；如果回應為文字訊息，則此值為回應的正文。

範例：顧客回覆了清單訊息

{
   "messages": [ {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
          "type": "list_reply",
          "list_reply": {
            "title": "row-title-content-here",
            "id": "unique-row-identifier-here",
            "description": "row-description-content-here"
          }
      }
   }

範例：顧客回覆了回覆按鈕訊息

{
  "messages": [ 
    {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "unique-button-identifier",
          "title": "button-text"
        }
      } # end interactive node
    } # end message item
  ] # end messages array
}

範例：顧客詢問有關特定產品的資訊

{
  "contacts": [
    {
      "profile": {
        "name": "customer-name"
      },
      "wa_id": "customer-whatsapp-ID"
    }
  ],
  "messages": [
    {
      "from": "customer-whatsapp-ID",
      "id": "message-ID",
      "text": {
        "body": "Can I get this in another color?"
      },
      "context": {
        "referred_product": {
          "catalog_id": "catalog-ID",
          "product_retailer_id": "product-ID"
        }
      },
      "timestamp": "message-received-timestamp",
      "type": "text"
    }
  ]
}

範例：顧客在收到多商品或單一商品訊息後下了訂單

{
   "messages": [ {
      "from": "customer-whatsapp-id",
      "group_id": "group-id",
      "id": "message-ID",
      "timestamp": "message-timestamp",
      "type": "order"
      "order": {
         "catalog_id": "catalog_id",
         "product_items": [
            {
            "product_retailer_id":"product-ID",
            "quantity":"number-of-items",
            "item_price":"unitary-price-of-item",
            "currency":"price-currency"
            },
                 ...
         ],
         "text":"text-message-sent-along-with-the-order"
      }
   }
}

傳入系統訊息

當發生特定事件時，系統會產生系統訊息。

範例：用戶更改了其號碼

如果 notify_user_change_number 參數在應用程式設定中設為 true，則當用戶更改其手機號碼時，您會收到傳入系統訊息。

{
    "messages": [
        {
            "from": "16315558889",
            "id": "ABGGFjFVWIifAzNzeXMtMTYzMTU1NTg4ODlAcy53aGF0c2FwcC5uZXQtMTU3NDA4MDEwMjIxMy1jaGFuZ2U",
            "system": {
                "body": "‎User A changed from ‎+1 (631) 555-8889 to ‎+1 (631) 555-8890‎",
                "new_wa_id": "16315558890",
                "type": "user_changed_number"
            },
            "timestamp": "1574080102",
            "type": "system"
        }
    ]
}

範例：用戶可能有變

如果 show_security_notifications 參數在應用程式設定中設為 true，則當正在與您對話的用戶可能在 WhatsApp 上有變時，您會收到傳入系統訊息。

在使用 identity 端點確認此通知之前，向此用戶傳送的所有傳出訊息都會被攔截，但您將繼續如常接收傳入訊息。

{
    "messages": [
        {
            "from": "16315553601",
            "id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ",
            "system": {
  		"body": "Test security code change",
                "identity": "Rc/eg9Rl0JA=",
                "type": "user_identity_changed",
                "user": "16315553601"
            },
            "timestamp": "1602535356",
            "type": "system"
        }
    ]
}

系統訊息類型

系統訊息類型說明

user_changed_number

用戶的手機號碼已更改

user_identity_changed

用戶可能在 WhatsApp 上有變

於訊息中提及用戶

如果您傳送的訊息直接提及了特定 WhatsApp 編號，並且用戶回覆了該訊息，則您會在 context 物件和 mentions 陣列中看到被提及的編號。由於訊息中可提及多個手機號碼，因此即使只提及了一個手機號碼，mentions 欄位也會是手機號碼陣列。

範例：顧客回覆訊息

以下是顧客回覆訊息的範例，其中提及了電話號碼。context 物件包含原始訊息中提及的手機號碼。text 物件的回覆再次提及了相同的手機號碼。

{   
  "messages": [{
    "context": {
      "from": "16315555544",
      "id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
      "mentions": [
        "16315551000",
        "16315551099"
      ]
    },
    "from": "16315551234 ",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1504902988",
    "text": {
      "body": "@16315551000 and @16315551099 are mentioned"
    },
    "type": "text"
  }]
}