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

# Conversaciones

> Cómo se identifica una conversación y por qué la ventana de 24h decide qué puedes enviar.

Una conversación es el hilo de WhatsApp entre tu negocio y un contacto. Casi
todos los endpoints de envío y de acciones (`/conversation/*`) la reciben en el
cuerpo del request bajo el objeto `conversation`.

## Identificar una conversación

El objeto `conversation` acepta **uno** de cuatro identificadores. El resolver
evalúa en este orden: `uuid` → `whatsapp_user_id` → `username` → `phone`:
`whatsapp_user_id` busca por igualdad exacta y `username` por igualdad
case-insensitive (ignora mayúsculas); `phone` se normaliza a dígitos.
Cuando el contacto tiene BSUID, `phone` y
`whatsapp_user_id` identifican valores distintos (ver Note).

<ParamField body="uuid" type="string">
  El UUID de un `GET /conversations`. El camino más directo y estable (puede
  quedar obsoleto si dos conversaciones del mismo contacto se unifican — ver la
  nota de unificación más abajo).
</ParamField>

<ParamField body="whatsapp_user_id" type="string">
  El BSUID del contacto (identidad opaca de Meta). Resuelve por igualdad exacta
  contra el BSUID guardado; si no resuelve, el endpoint responde `404` sin caer a
  `phone`. Identificador recomendado de aquí en adelante.
</ParamField>

<ParamField body="username" type="string">
  Username público de WhatsApp del contacto, con o sin `@` inicial y sin
  distinguir mayúsculas. Resolución best-effort contra el último username
  observado por la plataforma (el usuario puede cambiar su handle); si varios
  contactos lo comparten, el endpoint responde `409` (`USERNAME_AMBIGUOUS`).
</ParamField>

<ParamField body="phone" type="string">
  Número en formato E.164 (`+5215512345678`). Se normaliza a dígitos antes del
  lookup. Útil cuando solo tienes el teléfono.
</ParamField>

```jsonc theme={null}
{ "conversation": { "phone": "+52 55 1234 5678" } }
// equivalente: { "conversation": { "uuid": "7b8a..." } }
```

<Warning>
  El teléfono puede estar **duplicado** entre contactos (números reciclados o
  identidades separadas que comparten número): en ese caso la API responde `409`
  (`PHONE_NUMBER_AMBIGUOUS`) en vez de adivinar — identifica la conversación por
  `whatsapp_user_id` o `uuid`. Además, `whatsapp_user_id` puede **cambiar** si el
  usuario re-registra su cuenta de WhatsApp (rotación de identidad del lado de
  Meta). Usa el `uuid` como clave estable en tu sistema y `whatsapp_user_id` como
  identificador de resolución preferente.
</Warning>

<Note>
  `phone` y `whatsapp_user_id` son identificadores **distintos**: `phone` es el
  teléfono (wa\_id sin `+`) y `whatsapp_user_id` es el BSUID del contacto. Coinciden
  solo mientras el contacto no tiene BSUID. En las respuestas, `whatsapp_user_id`
  devuelve el BSUID real cuando existe, con fallback al teléfono para que siempre
  haya un valor resoluble. Cuidado en el round-trip: si el contacto aún no tiene
  BSUID, este campo trae el teléfono; reenvíalo entonces como `phone`, no como
  `whatsapp_user_id` — el resolver matchea `whatsapp_user_id` por igualdad exacta y
  daría `404`.
</Note>

<Note>
  Cuando un mismo contacto quedó registrado dos veces por identidad (por ejemplo,
  primero solo con su teléfono y luego con su BSUID), las dos conversaciones se
  **unifican automáticamente** en una sola: todo el historial pasa a la
  sobreviviente. El `uuid` de la conversación absorbida deja de resolver y responde
  `404`; el teléfono y el BSUID migran a la sobreviviente. Si guardaste un `uuid` y
  empieza a dar `404`, vuelve a resolver la conversación por `phone` o
  `whatsapp_user_id`.
</Note>

## La ventana de 24h

Es el concepto central de WhatsApp y decide qué puedes enviar.

<Steps>
  <Step title="El contacto te escribe">
    WhatsApp abre una **ventana de 24 horas**. Cada nuevo mensaje del contacto
    reinicia el contador.
  </Step>

  <Step title="Ventana abierta">
    Puedes enviar mensajes libres: texto, media y quick replies.
  </Step>

  <Step title="Pasan 24h sin respuesta">
    La ventana se cierra. El único mensaje permitido es una **plantilla**
    aprobada por Meta.
  </Step>

  <Step title="Enviar una plantilla reabre la ventana">
    Vuelves a poder enviar mensajes libres.
  </Step>
</Steps>

<Warning>
  Enviar texto, media o quick reply con la ventana cerrada falla con
  `WINDOW_CLOSED` (422). Envía una plantilla primero para reabrirla.
</Warning>

## Consultar el estado de la ventana

Antes de enviar un mensaje libre, puedes verificar si la ventana está abierta
con `POST /conversation/status`:

```bash theme={null}
curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/status" \
  -H "Authorization: Bearer sk_1to1_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "conversation": { "phone": "+5215512345678" } }'
```

La respuesta incluye `window.status` (`open` o `closed`) y
`window.hours_remaining`, además del estado de asignación, buzón, tags e
`inbox_status` de la conversación. Úsalo para decidir entre un mensaje libre y
una plantilla.

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Enviar mensajes" icon="paper-plane" href="/es/messages">
    Texto, media, quick replies y plantillas.
  </Card>

  <Card title="Plantillas" icon="newspaper" href="/es/templates">
    Cómo enviar plantillas con la ventana de 24h cerrada.
  </Card>
</CardGroup>