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

# Gestionar mensajes entrantes de WhatsApp

> Reciba mensajes entrantes, márquelos como leídos y muestre un indicador de escritura.

## Qué es

YCloud entrega los mensajes entrantes de WhatsApp a su endpoint de webhook. Después de aceptar un evento, puede marcar el mensaje como leído o mostrar un indicador temporal de escritura mientras su aplicación prepara una respuesta.

## Antes de comenzar

* Configure un endpoint de webhook para `whatsapp.inbound_message.received`.
* Valide el encabezado `YCloud-Signature` antes de procesar los eventos.
* Almacene el `id` del mensaje entrante.
* Conecte el número de teléfono comercial que recibió el mensaje.

## Cómo funciona

1. Reciba y autentique el evento de webhook.
2. Deduplique el evento mediante el `id` del evento.
3. Extraiga el `id` y el contenido del mensaje entrante.
4. Opcionalmente, marque el mensaje como leído.
5. Muestre un indicador de escritura solo cuando se esté preparando una respuesta.
6. Envíe la respuesta con la API de mensajes de WhatsApp.

Marcar un mensaje como leído también marca como leídos los mensajes anteriores de la conversación. El indicador de escritura desaparece cuando responde o tras 25 segundos, lo que ocurra primero.

## Solicitud

### Marcar un mensaje como leído

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

### Mostrar un indicador de escritura

`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 operación también marca el mensaje como leído.

## Respuesta

Una solicitud exitosa devuelve HTTP `200` sin cuerpo de respuesta.

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

La respuesta confirma que la acción fue aceptada. No envía una respuesta al usuario de WhatsApp.

## Guía de procesamiento

* Confirme la recepción del webhook antes de iniciar procesos lentos de IA o de negocio.
* Preserve el orden de los mensajes por conversación si su caso de uso depende de ello.
* Gestione explícitamente cada `type` entrante admitido y conserve las
  cargas útiles no admitidas para su investigación.
* Utilice el contexto del mensaje cuando responda a un mensaje entrante específico.

## Límites y resolución de problemas

* No muestre un indicador de escritura a menos que vaya a enviar una respuesta.
* Utilice el ID del mensaje entrante, no el ID del evento de webhook, en la ruta de la acción.
* Haga que el procesamiento de webhooks sea idempotente, ya que la entrega puede reintentarse.
* Si una acción falla, registre el `requestId` de YCloud sin registrar el
  contenido del mensaje ni las credenciales.

<CardGroup cols={2}>
  <Card title="Ejemplos de cargas útiles entrantes" icon="inbox" href="/es/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples">
    Inspeccione cargas útiles de mensajes de texto, multimedia, interactivos, de comercio y del sistema.
  </Card>

  <Card title="API para marcar como leído" icon="check-double" href="/api-reference/whatsapp-inbound-messages/mark-message-as-read">
    Inspeccione el contrato completo del endpoint.
  </Card>
</CardGroup>


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