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

# Gerenciar mensagens recebidas do WhatsApp

> Receba mensagens recebidas, marque-as como lidas e exiba um indicador de digitação.

## O que é

A YCloud entrega mensagens recebidas do WhatsApp no seu endpoint de Webhook. Depois de aceitar um evento, você pode marcar a mensagem como lida ou exibir um indicador temporário de digitação enquanto sua aplicação prepara uma resposta.

## Antes de começar

* Configure um endpoint de Webhook para `whatsapp.inbound_message.received`.
* Valide o cabeçalho `YCloud-Signature` antes de processar eventos.
* Armazene o `id` da mensagem recebida.
* Conecte o número de telefone comercial que recebeu a mensagem.

## Como funciona

1. Receba e autentique o evento de Webhook.
2. Elimine eventos duplicados pelo `id` do evento.
3. Extraia o `id` e o conteúdo da mensagem recebida.
4. Opcionalmente, marque a mensagem como lida.
5. Exiba um indicador de digitação somente quando uma resposta estiver sendo preparada.
6. Envie a resposta com a WhatsApp Messages API.

Marcar uma mensagem como lida também marca as mensagens anteriores da conversa como lidas. O indicador de digitação desaparece quando você responde ou após 25 segundos, o que ocorrer primeiro.

## Requisição

### Marcar uma mensagem como lida

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

### Exibir um indicador de digitação

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

Esta operação também marca a mensagem como lida.

## Resposta

Uma requisição bem-sucedida retorna HTTP `200` sem corpo de resposta.

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

A resposta confirma que a ação foi aceita. Ela não envia uma resposta ao usuário do WhatsApp.

## Orientações de processamento

* Confirme o recebimento do Webhook antes de iniciar processamentos lentos de IA ou de negócios.
* Preserve a ordem das mensagens por conversa caso seu caso de uso dependa disso.
* Trate explicitamente cada `type` recebido suportado e retenha payloads
  não suportados para investigação.
* Use o contexto da mensagem ao responder a uma mensagem recebida específica.

## Limites e solução de problemas

* Não exiba um indicador de digitação a menos que uma resposta seja enviada em seguida.
* Use o ID da mensagem recebida, não o ID do evento de Webhook, no caminho da ação.
* Torne o processamento de Webhook idempotente, pois a entrega pode ser tentada novamente.
* Se uma ação falhar, registre o `requestId` da YCloud sem registrar os conteúdos
  das mensagens ou credenciais.

<CardGroup cols={2}>
  <Card title="Exemplos de payloads recebidos" icon="inbox" href="/pt/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples">
    Inspecione payloads de mensagens de texto, mídia, interativas, de comércio e de sistema.
  </Card>

  <Card title="API de marcação como lida" icon="check-double" href="/api-reference/whatsapp-inbound-messages/mark-message-as-read">
    Inspecione o contrato completo do endpoint.
  </Card>
</CardGroup>


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