接收事件

message.received

帳號觀察到一條訊息；用 data.message.direction 區分 inbound 同 outbound。

Payload by message type

Text

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:34:56Z",
  "data": {
    "conversation": { "id": "8613912345678", "type": "user" },
    "sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "wamid.HBgM",
      "text": "Hi - is my order shipped yet?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:34:55Z"
    },
    "event": { "kind": "message_received" }
  }
}

Image (with caption)

{
  "id": "evt_4a1c7b9e2f",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:35:02Z",
  "data": {
    "conversation": { "id": "8613912345678", "type": "user" },
    "sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "wamid.HBgN",
      "text": "Here's the unboxing photo",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:35:02Z",
      "attachments": [
        {
          "type": "image",
          "url": "https://unifyport-media.oss-cn-hongkong.aliyuncs.com/pro/1/whatsapp/10001/2a1f.jpg?Expires=1749384902&Signature=...",
          "mimetype": "image/jpeg"
        }
      ]
    },
    "event": { "kind": "message_received" }
  }
}

Voice / Audio

{
  "id": "evt_6b2d8c0f3a",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:35:20Z",
  "data": {
    "conversation": { "id": "8613912345678", "type": "user" },
    "sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "wamid.HBgO",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:35:20Z",
      "attachments": [
        {
          "type": "audio",
          "url": "https://unifyport-media.oss-cn-hongkong.aliyuncs.com/pro/1/whatsapp/10001/9c3e.ogg?Expires=1749384920&Signature=...",
          "mimetype": "audio/ogg; codecs=opus",
          "duration_ms": 8000
        }
      ]
    },
    "event": { "kind": "message_received" }
  }
}

Document (large file — url omitted)

{
  "id": "evt_7c3e9d1a4b",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:35:45Z",
  "data": {
    "conversation": { "id": "8613912345678", "type": "user" },
    "sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "wamid.HBgP",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:35:45Z",
      "attachments": [
        {
          "type": "document",
          "mimetype": "application/pdf",
          "title": "invoice-A1234.pdf",
          "metadata": { "is_big_file": true, "size": 87421133 }
        }
      ]
    },
    "event": { "kind": "message_received" }
  }
}

Location

{
  "id": "evt_8d4f0e2b5c",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:36:10Z",
  "data": {
    "conversation": { "id": "8613912345678", "type": "user" },
    "sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "wamid.HBgQ",
      "text": "Shibuya Scramble Square, 2-24-12 Shibuya, Tokyo",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:36:10Z",
      "location": {
        "longitude": 139.7020,
        "latitude": 35.6580
      }
    },
    "event": { "kind": "message_received" }
  }
}

Mentioned quoted reply

{
  "id": "evt_9e5a1f3c6d",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:36:30Z",
  "data": {
    "conversation": { "id": "120363041234567890@g.us", "type": "group" },
    "sender": { "id": "8613912345678@lid", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "CURRENT-MESSAGE-ID",
      "text": "@Alex I am replying to the earlier update.",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:36:29Z",
      "reply_token": "<opaque handle for replying to CURRENT-MESSAGE-ID>",
      "reply_to_message_id": "PARENT-MESSAGE-ID",
      "mentions": [
        { "id": "8613900001111@lid" }
      ]
    },
    "event": { "kind": "message_received" }
  }
}

Album item

{
  "id": "evt_a0f6b2d4e7",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:36:45Z",
  "data": {
    "conversation": { "id": "8613912345678", "type": "user" },
    "sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "ALBUM-CHILD-MESSAGE-2",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:36:45Z",
      "album": { "id": "ALBUM-PARENT-ID", "index": 2, "total": 3 },
      "attachments": [
        {
          "type": "image",
          "url": "https://unifyport-media.oss-cn-hongkong.aliyuncs.com/pro/1/whatsapp/10001/album-2.jpg?Expires=1749385000&Signature=...",
          "mimetype": "image/jpeg"
        }
      ]
    },
    "event": { "kind": "message_received" }
  }
}

Contact (Telegram)

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:37:00Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "3003",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:37:00Z",
      "contact": {
        "phone_number": "+8600000000000",
        "first_name": "Demo",
        "last_name": "User",
        "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Demo User\nEND:VCARD",
        "user_id": 4004
      }
    },
    "event": { "kind": "message_received" }
  }
}

備註

data.message 可以帶 id、text、direction、sent_at、reply_token、reply_to_message_id、contact、location、mentions、album 同 attachments。reply_to_message_id 係父訊息 id；reply_token 係回覆目前訊息嘅不透明句柄。
data.message.type 係內部歸一化欄位，唔會落客戶 Webhook。媒體類型由 attachments[].type 表達；位置固定用 location.longitude / latitude，mentions 係 {id} 物件陣列，專輯用 album.id / index / total。