Nexiom ConnectDocs
Dashboard

whatsapp.message.received

A customer sent a WhatsApp message to one of your numbers.

When it fires

A customer sent a message to one of your project's WhatsApp numbers: text, media, a location, contacts, a button tap, a list choice, a reaction, or another message type. It fires once per message.

A message with a file fires once the file is stored, so the file's status is ready and you can download it at once. If WhatsApp no longer has the file, or it can't be downloaded after retries for up to 24 hours, the event fires with the status unavailable instead. Every received message fires the event.

Event fields

data.idstring

Message ID, starting with msg_. Use it to retrieve, mark as read, or reply to the message.

data.senderstring

The customer, in E.164 format, or WhatsApp's user ID for the customer when WhatsApp doesn't share their number.

data.recipientstring

Your number that received the message, in E.164 format.

data.typestring

The message's content is in the field of the same name.

One of"text""image""video""audio""document""sticker""location""contacts""interactive""button""reaction""unsupported"

data.reply_tostring or null

ID of the message the customer replied to, or null. Also null when that message was deleted after 30 days. A reaction names its message in reaction.message_id instead.

data.contactobject

The customer's WhatsApp profile: name, or null when WhatsApp didn't share it.

data.occurred_atstring

ISO 8601 time the customer sent the message, as reported by WhatsApp.

data.referralobject

Only on a message sent from a Click-to-WhatsApp ad or post: the ad or post the customer came from.

The content field, such as data.text or data.image, has the same shape as in the message object. Files are described, never linked: download them with Get message media.

Handle this event

Store the message, then act on it: answer the customer, route the conversation, or record the button or list choice. A received message opens the customer service window for 24 hours from data.occurred_at, so you can reply with any message type, quoting it with reply_to.

Message content is personal data. Reading it later with the API needs a key with whatsapp.full_access, and Nexiom Connect keeps it, and its files, for 30 days: download what you need to keep.

Verify the signature before reading the payload. Delivery is at least once: deduplicate by the envelope id. Messages can arrive out of order; sort them by data.occurred_at.

Nexiom Connect
Open dashboard