Skip to main content
GuidesAPI ReferenceSupport

Inbound Messaging Apps message

Inbound Messages are messages sent to you by users, on one of the channels you linked with your 8x8 account. Once this happens, 8x8 sends you this message to your webhook.

Requirements​

To use 8x8 inbound Messaging Apps capabilities, you need:

  • An account configured to use Messaging Apps product.
  • A webhook to indicate to us which URL 8x8 platform should forward the inbound messages addressed to you.

📘

You can configure your callback using Webhook Configuration API

Inbound message flow example​

  1. A user sends a message to your WhatsApp or Viber number
  2. 8x8 Platform receives the message on your behalf
  3. 8x8 Platform programmatically transmits the message to the callback URL configured for your webhook including all the information linked to the message.

Retry logic​

In case of connection error/timeout or HTTP response code 4XX or 5XX, there will be multiple retry attempts with progressive intervals: 1, 10, 30, 90 sec.

Webhook format​

📘

If you are still receiving webhooks in an older format, see the Webhook migration guide for help migrating your configuration.

Request body description

Parameter nameParameter typeDescription
versionintegerNew in v3. Version of the webhook payload format. Equals to 3 for this format.
namespacestringA generic namespace for incoming webhook.
Equal to ChatApps for inbound Messaging Apps message.
eventTypestringWebhook type.
Equals to inbound_message_received for inbound Messaging Apps message.
descriptionstringHuman-readable description of the incoming event
payloadobjectInbound message information, see below.

Payload object description

Parameter nameParameter typeDescription
umiduuidUnique message ID for the inbound message
subAccountIdstringId of the sub-account which owns the virtual number.
timestampstringUTC date and time when the message was received expressed in ISO 8601 format.
userobjectInformation about the user the message is associated with, see below.
recipientobjectRecipient information, see below
typestringInbound message type. Possible values:
- None
- Text
- Audio
- Video
- Image
- Location
- File
- Carousel
- List
- Buttons
- Template
- Interactive
contentobjectMessage content
replyToUmiduuidOptional context data, if this inbound message is referring to a previous inbound message (ex, quoted messages on WhatsApp).

User information object description

Parameter nameParameter typeDescription
msisdnstringChanged in v3. The user phone number expressed in E.164 international format. Left out for channels where users have no phone number (e.g. LINE).
channelUserIdstringChanged in v3. The user's id on the channel: the BSUID (business-scoped user id) for WhatsApp, or the Line user id for Line. Only included when the channel provides a real user id.
namestringThe WhatsApp user profile name
usernamestringNew in v3. The WhatsApp username

When a user field has no value, it is simply left out of the JSON.

Common object definitions​

Recipient information object description

Parameter nameParameter TypeDescription
channelstringChannel type, please see List of supported Messaging Apps channels for details.
channelIdstringChannel user identifier.

Content information object description

Parameter nameParameter typeDescription
textstringMessage text (for payload with type = Text)
urlstringThe URL of the media attachment (rich content) if any
payloadstringContent payload (for interactive messages)
locationobjectLocation object (for payload with type = Location)
interactiveobjectInteractive object (for payload with type = Interactive)

Location information object description

Parameter nameParameter typeDescription
latitudedecimalLatitude
longitudedecimalLongitude

Interactive information object description

Parameter nameParameter typeDescription
typestringType of the message. Possible values:
- button_reply
- list_reply
- nfmReply
- callPermissionReply
button_replyobjectButton reply object. Sent when a customer clicks a button.
list_replyobjectList reply object. Sent when a customer selects an item from a list.
nfmReplyobjectFlow reply object. Sent when a customer completes or submits a WhatsApp Flow. Contains flow response data in responseJson.
callPermissionReplyobjectCall permission reply object. Sent when a customer responds to a call permission request on WhatsApp. Contains the user's permission decision and related metadata.

Button reply information object description

Parameter nameParameter typeDescription
idstringUnique ID of a button.
titlestringTitle of a button.

List reply information object description

Parameter nameParameter typeDescription
idstringUnique ID of the selected list item
titlestringTitle of the selected list item.
descriptionstringDescription of the selected row.

NFM reply information object description

Parameter nameParameter typeDescription
responseJsonstringThe raw JSON string returned from the completed Flow, containing the user's submitted data (e.g., flow token, field values).

Call permission reply information object description

Parameter nameParameter typeDescription
responsestringThe user's response to the call permission request. Possible values:
- accept - User granted call permission
- reject - User denied call permission
isPermanentbooleanIndicates whether the permission is permanent. false for temporary permissions (7 days), true for permanent permissions.
expirationTimestampstringUTC date and time when the temporary call permission expires, expressed in ISO 8601 format. Only present when isPermanent is false.
responseSourcestringThe source of the permission. Always user_action - indicates the user explicitly approved or rejected the permission. Note: Automatic permissions (e.g., when a WhatsApp user initiates the call) do not trigger this webhook.

❗️

If the request you receive has a different structure from described in this document, please contact our support to activate the latest format for your account.

Sample payloads​

Inbound message — WhatsApp​

A WhatsApp text message showing all the v3 user fields: the BSUID in channelUserId, the profile name, and the new username.

Inbound WhatsApp message webhook body (v3) — all user fields present
{
  "version": 3,
  "namespace": "ChatApps",
  "eventType": "inbound_message_received",
  "description": "ChatApps inbound message",
  "payload": {
    "umid": <UNIQUE_MESSAGE_ID>,
    "subAccountId": <SUBACCOUNT_ID>,
    "timestamp": "2026-06-09T10:13:20.00Z",
    "user": {
      "msisdn": <USER_PHONE_NUMBER>,
      "channelUserId": <WHATSAPP_BSUID>,
      "name": <WHATSAPP_USER_PROFILE_NAME>,
      "username": <WHATSAPP_USERNAME>
    },
    "recipient": {
      "channel": "whatsapp",
      "channelId": <CHANNEL_ID>
    },
    "type": "Text",
    "content": {
      "text": "WhatsApp inbound message"
    }
  }
}
Inbound message — Viber, msisdn-only​

For msisdn-based channels (Viber, RCS, SMS) the user object contains only msisdn: v3 no longer fabricates a channelUserId from the phone number the way v2 did.

Inbound Viber message webhook body (v3) — msisdn-only user object
{
  "version": 3,
  "namespace": "ChatApps",
  "eventType": "inbound_message_received",
  "description": "ChatApps inbound message",
  "payload": {
    "umid": <UNIQUE_MESSAGE_ID>,
    "subAccountId": <SUBACCOUNT_ID>,
    "timestamp": "2026-07-03T01:14:03.00Z",
    "user": {
      "msisdn": <USER_PHONE_NUMBER>
    },
    "recipient": {
      "channel": "viber",
      "channelId": <CHANNEL_ID>
    },
    "type": "Text",
    "content": {
      "text": "Viber inbound message"
    }
  }
}
WhatsApp Flow response​

Sent when a customer completes or submits a WhatsApp Flow. The message arrives as an Interactive type with an nfmReply object carrying the user's submitted data in responseJson.

Inbound message webhook body — WhatsApp Flow response (nfmReply, v3)
{
  "version": 3,
  "namespace": "ChatApps",
  "eventType": "inbound_message_received",
  "description": "ChatApps inbound message",
  "payload": {
    "umid": <UNIQUE_MESSAGE_ID>,
    "subAccountId": <SUBACCOUNT_ID>,
    "timestamp": "2026-03-19T22:51:55.00Z",
    "user": {
      "msisdn": <USER_PHONE_NUMBER>,
      "channelUserId": <WHATSAPP_BSUID>
    },
    "recipient": {
      "channel": "whatsapp",
      "channelId": <CHANNEL_ID>
    },
    "type": "Interactive",
    "content": {
      "interactive": {
        "type": "nfmReply",
        "nfmReply": {
          "responseJson": "{\"flow_token\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
        }
      }
    }
  }
}
Call permission reply​

Sent when a customer responds to a call permission request on WhatsApp. The message arrives as an Interactive type with a callPermissionReply object containing the user's decision and, for temporary permissions, the expiration time.

Inbound message webhook body — call permission reply (callPermissionReply, v3)
{
  "version": 3,
  "namespace": "ChatApps",
  "eventType": "inbound_message_received",
  "description": "ChatApps inbound message",
  "payload": {
    "umid": <UNIQUE_MESSAGE_ID>,
    "subAccountId": <SUBACCOUNT_ID>,
    "timestamp": "2026-01-22T22:51:55.00Z",
    "user": {
      "msisdn": <USER_PHONE_NUMBER>,
      "channelUserId": <WHATSAPP_BSUID>
    },
    "recipient": {
      "channel": "whatsapp",
      "channelId": <CHANNEL_ID>
    },
    "type": "Interactive",
    "content": {
      "interactive": {
        "type": "callPermissionReply",
        "callPermissionReply": {
          "response": "accept",
          "isPermanent": false,
          "expirationTimestamp": "2026-01-23T06:51:55.00Z",
          "responseSource": "user_action"
        }
      }
    }
  }
}