WhaBuzzdocs
Menu

Start

OverviewGetting startedAuthentication

Guides

TenantsNumbersMessagesMediaTemplatesWebhooksIdempotencyRate limits and pacingRetentionMigrating from Plivo or WATI

API reference

Interactive referenceConventions

Webhook events

OverviewWhaBuzz events

Reference

ErrorsPricingChangelog
Event catalogue

Inbound text

A customer typed a message. data.message.text.body is the text. Replies carry context.id, the wamid of the message being replied to; forwarded messages carry context.forwarded; messages that start fro

A customer typed a message. data.message.text.body is the text. Replies carry context.id, the wamid of the message being replied to; forwarded messages carry context.forwarded; messages that start from a click-to-WhatsApp ad carry referral with the ad identifiers.

Event type: message.inbound. Fixture payloads are the WhaBuzz Demo tenant's real ids with a fictional customer number; id, tenant_id and created_at in envelopes are illustrative.

#Plain text

What Meta POSTs to WhaBuzz (fixtures/meta/text.json):

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "26059971920328384",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "14692311132",
              "phone_number_id": "1013622581841046"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "from_user_id": "US.13491208655302741918",
                "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB01AA=",
                "timestamp": "1760591523",
                "type": "text",
                "text": {
                  "body": "Hi, is the 7am batch open tomorrow?"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
json

What your endpoint receives, as the body of a signed POST. raw is abbreviated here; on the wire it is the full body above.

{
  "id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
  "type": "message.inbound",
  "api_version": "2026-10-16",
  "created_at": "2025-10-16T05:12:03.481Z",
  "tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046",
  "display_phone_number": "14692311132",
  "wamid": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB01AA=",
  "wa_id": "16505551234",
  "user_id": "US.13491208655302741918",
  "dedupe_key": "msg:wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB01AA=",
  "data": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "14692311132",
      "phone_number_id": "1013622581841046"
    },
    "contacts": [
      {
        "profile": {
          "name": "Kerry Fisher"
        },
        "wa_id": "16505551234",
        "user_id": "US.13491208655302741918"
      }
    ],
    "message": {
      "from": "16505551234",
      "from_user_id": "US.13491208655302741918",
      "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB01AA=",
      "timestamp": "1760591523",
      "type": "text",
      "text": {
        "body": "Hi, is the 7am batch open tomorrow?"
      }
    }
  },
  "raw": {
    "…": "the complete Meta POST body, byte for byte, as shown above"
  },
  "raw_path": "entry[0].changes[0].value.messages[0]"
}
json

#A reply to an earlier message (context)

What Meta POSTs to WhaBuzz (fixtures/meta/text_reply_context.json):

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "26059971920328384",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "14692311132",
              "phone_number_id": "1013622581841046"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "from_user_id": "US.13491208655302741918",
                "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB02AA=",
                "timestamp": "1760591523",
                "type": "text",
                "context": {
                  "from": "14692311132",
                  "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB90AA="
                },
                "text": {
                  "body": "Yes, book me in"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
json

What your endpoint receives, as the body of a signed POST. raw is abbreviated here; on the wire it is the full body above.

{
  "id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
  "type": "message.inbound",
  "api_version": "2026-10-16",
  "created_at": "2025-10-16T05:12:03.481Z",
  "tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046",
  "display_phone_number": "14692311132",
  "wamid": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB02AA=",
  "wa_id": "16505551234",
  "user_id": "US.13491208655302741918",
  "dedupe_key": "msg:wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB02AA=",
  "data": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "14692311132",
      "phone_number_id": "1013622581841046"
    },
    "contacts": [
      {
        "profile": {
          "name": "Kerry Fisher"
        },
        "wa_id": "16505551234",
        "user_id": "US.13491208655302741918"
      }
    ],
    "message": {
      "from": "16505551234",
      "from_user_id": "US.13491208655302741918",
      "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB02AA=",
      "timestamp": "1760591523",
      "type": "text",
      "context": {
        "from": "14692311132",
        "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB90AA="
      },
      "text": {
        "body": "Yes, book me in"
      }
    }
  },
  "raw": {
    "…": "the complete Meta POST body, byte for byte, as shown above"
  },
  "raw_path": "entry[0].changes[0].value.messages[0]"
}
json

#Forwarded text (context.forwarded)

What Meta POSTs to WhaBuzz (fixtures/meta/text_forwarded.json):

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "26059971920328384",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "14692311132",
              "phone_number_id": "1013622581841046"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "from_user_id": "US.13491208655302741918",
                "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB03AA=",
                "timestamp": "1760591523",
                "type": "text",
                "context": {
                  "forwarded": true,
                  "frequently_forwarded": true
                },
                "text": {
                  "body": "Forwarded many times"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
json

What your endpoint receives, as the body of a signed POST. raw is abbreviated here; on the wire it is the full body above.

{
  "id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
  "type": "message.inbound",
  "api_version": "2026-10-16",
  "created_at": "2025-10-16T05:12:03.481Z",
  "tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046",
  "display_phone_number": "14692311132",
  "wamid": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB03AA=",
  "wa_id": "16505551234",
  "user_id": "US.13491208655302741918",
  "dedupe_key": "msg:wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB03AA=",
  "data": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "14692311132",
      "phone_number_id": "1013622581841046"
    },
    "contacts": [
      {
        "profile": {
          "name": "Kerry Fisher"
        },
        "wa_id": "16505551234",
        "user_id": "US.13491208655302741918"
      }
    ],
    "message": {
      "from": "16505551234",
      "from_user_id": "US.13491208655302741918",
      "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB03AA=",
      "timestamp": "1760591523",
      "type": "text",
      "context": {
        "forwarded": true,
        "frequently_forwarded": true
      },
      "text": {
        "body": "Forwarded many times"
      }
    }
  },
  "raw": {
    "…": "the complete Meta POST body, byte for byte, as shown above"
  },
  "raw_path": "entry[0].changes[0].value.messages[0]"
}
json

#From a click-to-WhatsApp ad (referral)

What Meta POSTs to WhaBuzz (fixtures/meta/text_referral_ctwa.json):

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "26059971920328384",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "14692311132",
              "phone_number_id": "1013622581841046"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "from_user_id": "US.13491208655302741918",
                "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB04AA=",
                "timestamp": "1760591523",
                "type": "text",
                "text": {
                  "body": "I saw your ad"
                },
                "referral": {
                  "source_url": "https://fb.me/3cr4Wqqkv",
                  "source_id": "120214567890123456",
                  "source_type": "ad",
                  "body": "Book a free trial",
                  "headline": "Trial class",
                  "media_type": "image",
                  "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/ad.jpg",
                  "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
                  "welcome_message": {
                    "text": "Hi! Tap send to ask about the trial."
                  }
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
json

What your endpoint receives, as the body of a signed POST. raw is abbreviated here; on the wire it is the full body above.

{
  "id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
  "type": "message.inbound",
  "api_version": "2026-10-16",
  "created_at": "2025-10-16T05:12:03.481Z",
  "tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046",
  "display_phone_number": "14692311132",
  "wamid": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB04AA=",
  "wa_id": "16505551234",
  "user_id": "US.13491208655302741918",
  "dedupe_key": "msg:wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB04AA=",
  "data": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "14692311132",
      "phone_number_id": "1013622581841046"
    },
    "contacts": [
      {
        "profile": {
          "name": "Kerry Fisher"
        },
        "wa_id": "16505551234",
        "user_id": "US.13491208655302741918"
      }
    ],
    "message": {
      "from": "16505551234",
      "from_user_id": "US.13491208655302741918",
      "id": "wamid.HBgLMTY1MDU1NTEyMzQVAgASGBQzQUY5QTdGNkU0RTFGMkI3QzFB04AA=",
      "timestamp": "1760591523",
      "type": "text",
      "text": {
        "body": "I saw your ad"
      },
      "referral": {
        "source_url": "https://fb.me/3cr4Wqqkv",
        "source_id": "120214567890123456",
        "source_type": "ad",
        "body": "Book a free trial",
        "headline": "Trial class",
        "media_type": "image",
        "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/ad.jpg",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
        "welcome_message": {
          "text": "Hi! Tap send to ask about the trial."
        }
      }
    }
  },
  "raw": {
    "…": "the complete Meta POST body, byte for byte, as shown above"
  },
  "raw_path": "entry[0].changes[0].value.messages[0]"
}
json

This page as Markdown: /events/inbound-text.md. All docs in one file: /llms-full.txt.