Skip to main content

​
What it is

YCloud delivers inbound WhatsApp messages to your webhook endpoint. After you accept an event, you can mark the message as read or show a temporary typing indicator while your application prepares a reply.

​
Before you begin

  • Configure a webhook endpoint for whatsapp.inbound_message.received.
  • Validate the YCloud-Signature header before processing events.
  • Store the inbound message id.
  • Connect the business phone number that received the message.

​
How it works

  1. Receive and authenticate the webhook event.
  2. Deduplicate the event by event id.
  3. Extract the inbound message id and content.
  4. Optionally mark the message as read.
  5. Show a typing indicator only when a reply is being prepared.
  6. Send the reply with the WhatsApp Messages API.
Marking one message as read also marks earlier messages in the conversation as read. A typing indicator disappears when you reply or after 25 seconds, whichever happens first.

​
Request

​
Mark a message as read

POST /whatsapp/inboundMessages/{id}/markAsRead

​
Show a typing indicator

POST /whatsapp/inboundMessages/{id}/typing
This operation also marks the message as read.

​
Response

A successful request returns HTTP 200 with no response body.
The response confirms that the action was accepted. It does not send a reply to the WhatsApp user.

​
Processing guidance

  • Acknowledge the webhook before starting slow AI or business processing.
  • Preserve message order per conversation where your use case depends on it.
  • Handle every supported inbound type explicitly and retain unsupported payloads for investigation.
  • Use the message context when replying to a specific inbound message.

​
Limits and troubleshooting

  • Do not show a typing indicator unless a response will follow.
  • Use the inbound message ID, not the webhook event ID, in the action path.
  • Make webhook handling idempotent because delivery can be retried.
  • If an action fails, log the YCloud requestId without logging message contents or credentials.

Inbound payload examples

Inspect text, media, interactive, commerce, and system message payloads.

Mark as read API

Inspect the complete endpoint contract.