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
- A user sends a message to your WhatsApp or Viber number
- 8x8 Platform receives the message on your behalf
- 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
Request body description
| Parameter name | Parameter type | Description |
|---|---|---|
| namespace | string | A generic namespace for incoming webhook. Equal to ChatApps for inbound Messaging Apps message. |
| eventType | string | Webhook type. Equals to inbound_message_received for inbound Messaging Apps message. |
| description | string | Human-readable description of the incoming event |
| payload | object | Inbound message information, see below. |
Payload object description
| Parameter name | Parameter type | Description |
|---|---|---|
| umid | uuid | Unique message ID for the inbound message |
| subAccountId | string | Id of the sub-account which owns the virtual number. |
| timestamp | string | UTC date and time when the message was received expressed in ISO 8601 format. |
| user | object | Information about the user the message is associated with. |
| recipient | object | Recipient information, see below |
| type | string | Inbound message type. Possible values: - None- Text- Audio- Video- Image- Location- File- Carousel- List- Buttons- Template- Interactive
|
| content | object | Message content |
| replyToUmid | uuid | Optional context data, if this inbound message is referring to a previous inbound message (ex, quoted messages on WhatsApp). |
User information object description
| Parameter name | Parameter type | Description |
|---|---|---|
| msisdn | string | Phone number expressed in E.164 international format. |
| channelUserId | string | Id of the user in the channel |
| name | string | User's name in the channel. For example, username of the WhatsApp user |
Recipient information object description
| Parameter name | Parameter Type | Description |
|---|---|---|
| channel | string | Channel type, please see List of supported Messaging Apps channels for details. |
| channelId | string | Channel user identifier. |
Content information object description
| Parameter name | Parameter type | Description |
|---|---|---|
| text | string | Message text (for payload with type = Text) |
| url | string | The URL of the media attachment (rich content) if any |
| payload | string | Content payload (for interactive messages) |
| location | object | Location object (for payload with type = Location) |
| interactive | object | Interactive object (for payload with type = Interactive) |
Location information object description
| Parameter name | Parameter type | Description |
|---|---|---|
| latitude | decimal | Latitude |
| longitude | decimal | Longitude |
Interactive information object description
| Parameter name | Parameter type | Description |
|---|---|---|
| type | string | Type of the message. Possible values: - button_reply- list_reply- nfmReply- callPermissionReply
|
| button_reply | object | Button reply object. Sent when a customer clicks a button. |
| list_reply | object | List reply object. Sent when a customer selects an item from a list. |
| nfmReply | object | Flow reply object. Sent when a customer completes or submits a WhatsApp Flow. Contains flow response data in responseJson. |
| callPermissionReply | object | Call 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 name | Parameter type | Description |
|---|---|---|
| id | string | Unique ID of a button. |
| title | string | Title of a button. |
List reply information object description
| Parameter name | Parameter type | Description |
|---|---|---|
| id | string | Unique ID of the selected list item |
| title | string | Title of the selected list item. |
| description | string | Description of the selected row. |
NFM reply information object description
| Parameter name | Parameter type | Description |
|---|---|---|
| responseJson | string | The 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 name | Parameter type | Description |
|---|---|---|
| response | string | The user's response to the call permission request. Possible values: - accept - User granted call permission- reject - User denied call permission |
| isPermanent | boolean | Indicates whether the permission is permanent. false for temporary permissions (7 days), true for permanent permissions. |
| expirationTimestamp | string | UTC date and time when the temporary call permission expires, expressed in ISO 8601 format. Only present when isPermanent is false. |
| responseSource | string | The 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 Messaging Apps inbound message
{
"namespace":"ChatApps",
"eventType":"inbound_message_received",
"description":"ChatApps inbound message",
"payload":{
"umid":"9e09ac86-bd74-5465-851d-1eb5a5fdbb9a",
"subAccountId":"SubAccount-1",
"timestamp":"2016-01-01T14:34:56.017Z",
"user":{
"msisdn":"+12025550023",
"channelUserId":"12025550023"
},
"recipient":{
"channel":"whatsapp",
"channelId":"269a57f4-3522-eb11-8278-00155d9f27ac"
},
"type":"Text",
"content":{
"text":"Test message"
},
"replyToUmid":"777a57f4-bd74-eb11-851d-00155d9fer55"
}
}
Sample Messaging Apps inbound message (Flow Response)
{
"namespace":"ChatApps",
"eventType":"inbound_message_received",
"description":"ChatApps inbound message",
"payload":{
"umid":"2b1e044d-6fce-4a11-8962-b39900a755c1",
"subAccountId":"SubAccount-1",
"timestamp":"2018-03-19T22:51:55.00Z",
"user":{
"msisdn":"+12025550023",
"channelUserId":"12025550023"
},
"recipient":{
"channel":"whatsapp",
"channelId":"4b2ba2df-deb0-4c29-8ba5-a266672daf49"
},
"type":"Interactive",
"content":{
"interactive":{
"type":"nfmReply",
"nfmReply":{
"responseJson":"{\"flow_token\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
}
}
}
}
}
Sample Messaging Apps inbound message (Call Permission Reply)
{
"namespace":"ChatApps",
"eventType":"inbound_message_received",
"description":"ChatApps inbound message",
"payload":{
"umid":"2b1e044d-6fce-4a11-8962-b39900a755c1",
"subAccountId":"SubAccount-1",
"timestamp":"2026-01-22T22:51:55.00Z",
"user":{
"msisdn":"+12025550023",
"channelUserId":"12025550023"
},
"recipient":{
"channel":"whatsapp",
"channelId":"4b2ba2df-deb0-4c29-8ba5-a266672daf49"
},
"type":"Interactive",
"content":{
"interactive":{
"type":"callPermissionReply",
"callPermissionReply":{
"response":"accept",
"isPermanent":false,
"expirationTimestamp":"2026-01-23T06:51:55.00Z",
"responseSource":"user_action"
}
}
}
}
}
Source: https://developer.8x8.com/connect/docs/inbound-chatapps-message · 8x8 CPaaS Developer Docs. Synced for support deflection.
Please sign in to leave a comment.
0 Comments