> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle WhatsApp inbound messages

> Receive inbound messages, mark them as read, and show a typing indicator.

## 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`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  https://api.ycloud.com/v2/whatsapp/inboundMessages/INBOUND_MESSAGE_ID/markAsRead \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

### Show a typing indicator

`POST /whatsapp/inboundMessages/{id}/typing`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  https://api.ycloud.com/v2/whatsapp/inboundMessages/INBOUND_MESSAGE_ID/typing \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

This operation also marks the message as read.

## Response

A successful request returns HTTP `200` with no response body.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

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.

<CardGroup cols={2}>
  <Card title="Inbound payload examples" icon="inbox" href="/en/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples">
    Inspect text, media, interactive, commerce, and system message payloads.
  </Card>

  <Card title="Mark as read API" icon="check-double" href="/api-reference/whatsapp-inbound-messages/mark-message-as-read">
    Inspect the complete endpoint contract.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.