Message notifications

Last update: 5 hours ago by Irais Aguirre

Integration summary
Delivery: WhatsApp → Concepto Móvil → POST to your webhook URL (the one you share with our Operations team), with a JSON body.
Format: Meta's value object without metadata or messaging_product (see Webhook).
Identify the user: from/recipient_id or, if missing, the BSUID.
Types on this page: text, audio, document, image, location, video, voice, sticker, contacts, reaction, unsupported, edit, revoke (type values), plus account-level error notifications

Messages, files, locations, and contacts your customer sends you. They all share the same general structure (contacts and messages), and the type field indicates the content type. Replies to interactive messages, shopping carts, and Flows replies are in Interactive replies.

General structure

Structure shared by every message notification.

Structure

Fields for General structure:

Name	Description	Type	Requirements
contacts	Array with the details of the contact who sent the message.	Array of objects	Required
messages	Array with the details of the message sent.	Array of objects	Required

Contacts object

Name	Description	Type	Requirements
profile	Object that contains the contact's details.	Object	Required
wa_id	The user's phone number (including country code). May be missing if the user has a username (see Usernames and BSUID).	String	Conditional
user_id	The user's BSUID. Always included.	String	Required
parent_user_id	Parent BSUID. Only included if the business has linked portfolios.	String	Optional

Messages object

Name	Description	Type	Requirements
from	Phone number (including country code) that sent the message. May be missing if the user has a username.	String	Conditional
from_user_id	BSUID of the user who sent the message. Always included.	String	Required
from_parent_user_id	The user's parent BSUID. Only included if the business has linked portfolios.	String	Optional
id	Message ID.	String	Required
timestamp	Date and time the message was sent.	String	Required
type	Depends on the message type. Possible values: text audio document image location video voice button (quick replies) contacts interactive order sticker reaction system unsupported edit (Coexistence only) revoke (Coexistence only)	String	Required
group_id	Identifier of the group the message belongs to. Only included when the message comes from a group.	String	Conditional
text	Object that contains the message text.	Object	Optional
audio	Object that contains the audio details.	Object	Optional
document	Object that contains the document details.	Object	Optional
image	Object that contains the image details.	Object	Optional
location	Object that contains the location details.	Object	Optional
video	Object that contains the video details.	Object	Optional
voice	Object that contains the voice message details.	Object	Optional
sticker	Object that contains the sticker details.	Object	Optional
interactive	Object that contains the interactive message details.	Object	Optional
button	Object that contains the quick reply text.	Object	Optional
context	Object that contains information related to the following cases: when a button notification is received when the customer replies quoting one of their own messages or a message sent by the business when the message was forwarded when the business sends a message that mentions one or more phone numbers and your customer replies quoting that message	Object	Sent in the following cases: when a button notification is received when the customer replies quoting one of their own messages or a message sent by the business when the message was forwarded when the business sends a message that mentions one or more phone numbers and your customer replies quoting that message
contacts	Array with the shared contact's details.	Array of objects	Required when a shared contact notification is received.
reaction	Object that contains the details of a reaction to a message.	Object	Optional
referral	Object with the click-to-WhatsApp ad details the user came from. When present, the `text.body` field is concatenated with `referral.source_url`.	Object	Optional

Profile object

Name	Description	Type	Requirements
name	Name of the contact who sent the message.	String	Required
username	Username. Only included if the user has one turned on.	String	Optional

Text

The type field is "text".

Structure

Fields for Text:

Name	Description	Type	Requirements
body	Message text.	String	Required.

Example

Complete Text example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "text",
            "text": {
                "body": "Hello, friend" 
            }
        }
    ] 
}

Note (Brazilian numbers): for numbers with the "55" prefix shorter than 13 digits, the platform inserts a "9" after the area code in contacts[0].wa_id and messages[0].from before delivering the notification.

Text from a user with a username

The user has a username and their phone number isn't available, so you only receive their BSUID and username.

{
    "contacts": [
        {
            "profile": {
                "name": "test user name",
                "username": "@testusername"
            },
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "messages": [
        {
            "id": "ABGGFlA5Fpa",
            "timestamp": "1504902988",
            "from_user_id": "US.13491208655302741918",
            "type": "text",
            "text": {
                "body": "this is a text message"
            }
        }
    ]
}

The user has a username and their phone number is available, so you receive every field.

{
    "contacts": [
        {
            "profile": {
                "name": "test user name",
                "username": "@testusername"
            },
            "wa_id": "16315551181",
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "messages": [
        {
            "id": "ABGGFlA5Fpa",
            "timestamp": "1504902988",
            "from": "16315551181",
            "from_user_id": "US.13491208655302741918",
            "type": "text",
            "text": {
                "body": "this is a text message"
            }
        }
    ]
}

Audio

The type field is "audio".

Structure

Fields for Audio:

Name	Description	Type	Requirements
id	File ID.	String	Required.
mime_type	File type.	String	Required.
sha256	File checksum.	String	Required.

Example

Complete Audio example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "audio",
            "audio": {
                "id": "6b6f751e-5757-4652-bf51-fb4ce7445533", 
                "mime_type": "audio/mpeg",
                "sha256": "693cddca479f19817d300d743849e1a69f045b97f65c08339c2f9d9e0c16cb6f"
            }
        }
    ] 
}

Document

The type field is "document".

Structure

Fields for Document:

Name	Description	Type	Requirements
id	File ID.	String	Required.
mime_type	File type.	String	Required.
sha256	File checksum.	String	Required.
caption	Text that accompanies the document.	String	Optional.
filename	File name on the sender's device.	String	Required.

Example

Complete Document example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "document",
            "document": {
                "caption": "smppdoc.pdf", 
                "filename": "smppdoc.pdf",
                "id": "a26072ab-a20e-4c2b-9595-929a92fb3f9e",
                "mime_type": "application/pdf",
                "sha256":
"c29f4d7461ddca08fd58db1f716610a2b3f36f9c0f2620bf4f5ea9b698f0912b"
            }
        }
    ] 
}

Image

The type field is "image".

Structure

Fields for Image:

Name	Description	Type	Requirements
id	File ID.	String	Required.
mime_type	File type.	String	Required.
sha256	File checksum.	String	Required.
caption	Text that accompanies the image.	String	Optional.

Example

Complete Image example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "image",
            "image": {
                "id": "647b9f5d-89fb-43fc-9708-49b067d49766",
                "mime_type": "image/jpeg",
                "sha256": "1b78676c0af68ec66b71b7b09803e68d698db7891c7b0820b24a35c82535b06c"
            }
        }
    ] 
}

Location

The type field is "location".

Structure

Fields for Location:

Name	Description	Type	Requirements
address	Address.	String	Optional.
latitude	Latitude.	Number	Required.
longitude	Longitude.	Number	Required.
name	Location name.	String	Optional.
url	URL of the website the user got the location information from.	String	Optional.

Example

Complete Location example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "location",
            "location": {
                "latitude": 19.5386,
                "longitude": -99.15124 
            }
        }
    ] 
}

Video

The type field is "video".

Structure

Fields for Video:

Name	Description	Type	Requirements
id	File ID.	String	Required.
mime_type	File type.	String	Required.
sha256	File checksum.	String	Required.
caption	Text or title the user gives to the file they send.	String	Optional. Present only if the user writes one.

Example

Complete Video example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "video",
            "video": {
                "id": "a2936494-0747-462a-9381-5e5d6672ce33",
                "mime_type": "video/mp4",
                "sha256":
"ca5c888f78787f62efe3b382a8b243556dbb982f0e2c585adfd8d0b4808d5d99"
            }
        }
    ] 
}

Voice message

The type field is "voice".

Structure

Fields for Voice message:

Name	Description	Type	Requirements
id	File ID.	String	Required
mime_type	File type.	String	Required
sha256	File checksum.	String	Required
caption	Text or title the user gives to the file they send.	String	Optional. Present only if the user writes one.

Example

Complete Voice message example:

{
    "contacts": [
        {
            "profile": {
                "name": "John Smith" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "voice",
            "voice": {
                "id": "e091fa61-d8dc-41c4-967b-e6a163ba21c2",
                "mime_type": "audio/ogg; codecs=opus", 
                "sha256":
"acd78d57200637690bcca16239dd452fc4e5bb8b817c85b58452abfe28ab8f2e"
            }
        }
    ] 
}

Sticker

The type field is "sticker".

Structure

Fields for Sticker:

Name	Description	Type	Requirements
id	File ID.	String	Required.
mime_type	File type.	String	Required.
sha256	File checksum.	String	Required.
animated	Whether the sticker is animated.	Boolean	Required.

Example

Complete Sticker example:

{
    "contacts": [
        {
            "profile": {
                "name": "John Smith" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "wamid.HBgNNTIxNTUyMDc3NzA1OBUCABIYFDNBMDRDRTJDODlFQ0Q5Mzc5RkUzAA==",
            "timestamp": "1617061836",
            "type": "sticker",
            "sticker": {
                "id": "647b9f5d-89fb-43fc-9708-49b067d49766",
                "mime_type": "image/webp",
                "sha256": "mCZ/7a6sZ6TMa14YokRCSfultjY6aQEVE5Z11TpjsP8=",
                "animated": false
            }
        }
    ] 
}

Reaction

The type field is "reaction". The user reacted with an emoji to a previously sent message.

Structure

Fields for Reaction:

Name	Description	Type	Requirements
message_id	Identifier of the reacted message. Matches the internal id returned by the send API.	String	Required
emoji	Emoji the user reacted with.	String	Required

Referral

referral object, present when the message comes from a click-to-WhatsApp ad. When present, the message's text.body field is concatenated with a space and the value of referral.source_url.

Structure

Fields for Referral:

Name	Description	Type	Requirements
source_url	Ad URL.	String	Required
source_id	Ad identifier.	String	Optional
source_type	Source type (e.g. "ad", "post").	String	Optional
headline	Ad headline.	String	Optional
body	Ad body.	String	Optional
image	Ad image.	String	Optional

Shared contact

The type field is "contacts".

Structure

Fields for Shared contact:

Name	Description	Type	Requirements
from	Sender's phone number (with country code).	String	Required.
type	The value must be "contacts".	String	Required
contacts	Array with the shared contact's details.	Array of objects	Required.

Shared contacts object

Name	Description	Type	Requirements
birthday	Contact's date of birth.	String	Optional.
addresses	Contact's addresses.	Array of objects	Optional.
emails	Contact's email addresses.	Array of objects	Optional.
name	Contact's name.	Object	Required.
org	Contact's company.	Object	Optional.
phones	Contact's phone numbers.	Array of objects	Optional.
urls	Contact's URLs.	Array of objects	Optional.

Addresses object

Name	Description	Type	Requirements
city	City.	String	Optional.
country	Country.	String	Optional.
country_code	ISO country code.	String	Optional.
state	State.	String	Optional.
street	Street.	String	Optional.
type	Possible values: WORK, HOME.	String	Optional.
zip	ZIP code.	String	Optional.

Emails object

Name	Description	Type	Requirements
email	Contact's email address.	String	Optional.
type	Possible values: WORK.	String	Optional.

Name object

Name	Description	Type	Requirements
first_name	Contact's first name.	String	Required if middle_name and last_name are empty.
middle_name	Contact's middle name.	String	Required if first_name and last_name are empty.
last_name	Contact's last name.	String	Required if middle_name and first_name are empty.
formatted_name	Full name.	String	Required.
prefix	Name prefix (e.g. "Dr.", "Mr.").	String	Optional.
suffix	Name suffix (e.g. "Jr.", "III").	String	Optional.

Org object

Name	Description	Type	Requirements
company	Company name.	String	Required
department	Department.	String	Optional
title	Job title.	String	Optional

Phones object

Name	Description	Type	Requirements
phone	Contact's phone number.	String	Required.
type	Possible values: WORK, HOME.	String	Required.
wa_id	Contact's WhatsApp ID (number with country code).	String	Optional.

Urls object

Name	Description	Type	Requirements
url	Contact's URL.	String	Required.
type	Possible values: WORK.	String	Required.

Example

Complete Shared contact example:

{
    "contacts": [
        {
            "profile": {
                "name": "John Smith" 
            },
            "wa_id": "5215500000001" 
        }
    ], 
    "messages": [
        {
            "from": "5215500000001",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "type": "contacts",
            "contacts": [
                {
                    "addresses": [],
                    "contact_image": "/9j/4AAQSkZJRgABAQEAZABkAAD",
                    "emails": [
                        {
                            "email": "test@mail.com",
                            "type": "Other"
                        }
                    ],
                    "ims": [],
                    "name": {
                        "first_name": "John", 
                        "formatted_name": "John Smith", 
                        "last_name": "Smith"
                    },
                    "org": {},
                    "phones": [
                        {
                            "phone": "+1 (000) 111-1111",
                            "type": "Mobile"
                        }
                    ],
                    "urls": [
                        {
                            "type": "PROFILE",
                            "url": "http://www.google.com/profiles/1012231243417990451811"
                        }
                    ]
                }
            ]
        }
    ]
}

Unsupported message

The type field is "unsupported". Sent when the user sends a message type Cloud API doesn't support, or in a few other cases (for example, the first message from a user whose business was onboarded with the WhatsApp Business app). The message includes an errors array and an unsupported object.

Structure

Fields for Unsupported message:

Unsupported object

Name	Description	Type	Requirements
type	Type of unsupported message. Possible values: button edit errors gif group_invite hsm image interactive keep_in_chat link_preview list location media_placeholder order pin poll_creation poll_update product reaction	String	Required

Errors object

Name	Description	Type	Requirements
code	Error code. Possible values: 131051: the message type is not supported. 131060: the message is currently unavailable.	Number	Required
title	Error title.	String	Required
message	Error message. Same value as `title`.	String	Optional
error_data.details	Human-readable description of the error.	String	Optional

Example

Complete Unsupported message example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor"
            },
            "wa_id": "5215500000001",
            "user_id": "US.13491208655302741918"
        }
    ],
    "messages": [
        {
            "from": "5215500000001",
            "from_user_id": "US.13491208655302741918",
            "id": "ABGHUhVUByKUHwIKPrA13J63aX1gRA",
            "timestamp": "1617061836",
            "errors": [
                {
                    "code": 131051,
                    "title": "Message type unknown",
                    "message": "Message type unknown",
                    "error_data": {
                        "details": "Message type is currently not supported."
                    }
                }
            ],
            "type": "unsupported",
            "unsupported": {
                "type": "poll_update"
            }
        }
    ]
}

Edited message

The type field is "edit". Sent when the user edits a message they previously sent (text, or media with a caption), within 15 minutes of sending it. The edit object contains the ID of the original message and the new content.

Note: the edit notification is only available for businesses that use the WhatsApp Business app (Coexistence).

Structure

Fields for Edited message:

Edit object

Name	Description	Type	Requirements
original_message_id	ID of the original message that was edited.	String	Required
message	The edited content. Includes its own `type` and the matching type-specific object (for example `text` or `image`), and an optional `context`.	Object	Required

Example

Complete Edited message example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor"
            },
            "wa_id": "5215500000001",
            "user_id": "US.13491208655302741918"
        }
    ],
    "messages": [
        {
            "from": "5215500000001",
            "from_user_id": "US.13491208655302741918",
            "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
            "timestamp": "1749854575",
            "type": "edit",
            "edit": {
                "original_message_id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA=",
                "message": {
                    "context": {
                        "id": "M0"
                    },
                    "type": "image",
                    "image": {
                        "caption": "Updated image caption",
                        "mime_type": "image/jpeg",
                        "sha256": "a1b2c3d4e5f6...",
                        "id": "1234567890"
                    }
                }
            }
        }
    ]
}

Deleted message

The type field is "revoke". Sent when the user deletes a message they previously sent, within two days of sending it. The revoke object contains the ID of the deleted message.

Note: the revoke notification is only available for businesses that use the WhatsApp Business app (Coexistence).

Structure

Fields for Deleted message:

Revoke object

Name	Description	Type	Requirements
original_message_id	ID of the original message that was deleted.	String	Required

Example

Complete Deleted message example:

{
    "contacts": [
        {
            "profile": {
                "name": "Héctor"
            },
            "wa_id": "5215500000001",
            "user_id": "US.13491208655302741918"
        }
    ],
    "messages": [
        {
            "from": "5215500000001",
            "from_user_id": "US.13491208655302741918",
            "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
            "timestamp": "1749854575",
            "type": "revoke",
            "revoke": {
                "original_message_id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA="
            }
        }
    ]
}

Error notification

Account-, app-, or system-level error that prevented a request from being processed. It arrives in an errors array at the top level of the notification, without the contacts or messages arrays.

Structure

Fields for Error notification:

Errors object

Name	Description	Type	Requirements
code	Error code. For details, see Error codes.	Number	Required
title	Error title.	String	Required
message	Error message. Same value as `title`.	String	Optional
error_data.details	Human-readable description of the error.	String	Optional
href	Link to the error-code documentation.	String	Optional

Example

Complete Error notification example:

{
    "errors": [
        {
            "code": 130429,
            "title": "Rate limit hit",
            "message": "Rate limit hit",
            "error_data": {
                "details": "Message failed to send because there were too many messages sent from this phone number in a short period of time"
            },
            "href": "https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes"
        }
    ]
}