Receiving Events

message.received

An inbound message arrived on the account.

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",
      "type": "text",
      "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",
      "type": "image",
      "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",
      "type": "audio",
      "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",
      "type": "document",
      "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",
      "type": "location",
      "text": "Shibuya Scramble Square, 2-24-12 Shibuya, Tokyo",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:36:10Z"
    },
    "event": { "kind": "message_received" }
  }
}

Ghi chú

data.conversation is the chat, data.sender is who sent it, and data.message holds the content — id, type, text, direction (inbound here), and sent_at. Telegram adds conversation.title, sender.username, and an account block; field availability varies by provider.
data.message.type is one of text / image / video / audio / document / sticker / location / contact (or unknown). Media types (image / video / audio / document / sticker) carry data.message.attachments[]; video and audio add duration_ms, document adds the file title, and oversized files set attachments[].metadata.is_big_file with the url omitted. location and contact have no attachment — the detail sits in data.message.text (contact is a vCard).