Skip to main content
Endpoint · GET /conversation (detalle) y GET /conversation/messages (hilo)
Endpoints de solo consulta: devuelven información y no modifican nada. No se mandan dentro del array actions — se llaman directo.
Son las dos lecturas que dan contexto antes de operar sobre una conversación. GET /conversation responde en qué estado está (ventana de 24h, buzón, empleado AI, etiquetas) y quién es el contacto; GET /conversation/messages responde qué se dijo, en qué orden y quién lo dijo. Con lo primero decides qué acción es válida (por ejemplo, si la ventana está cerrada solo puedes enviar una plantilla); con lo segundo redactas el mensaje con el historial a la vista. Ambos identifican la conversación con la misma referencia que el resto de la API, pero pasada por query params en vez del cuerpo: exactamente uno de phone, username, whatsapp_user_id o uuid, más channel.

​
Detalle de la conversación

Parámetros
  • phone — teléfono en formato E.164. Se normaliza a dígitos antes del lookup.
  • username — username público de WhatsApp. Se normaliza (quita el @ inicial, ignora mayúsculas).
  • whatsapp_user_id — BSUID del contacto (identidad opaca de Meta). Igualdad exacta, sin normalizar.
  • uuid — UUID interno de 1TO1 AI, si ya lo tienes guardado.
  • channel — clave pública del canal (obligatorio en todo request). Lístalas con GET /channels. No distingue mayúsculas/minúsculas. Fija el canal objetivo; en las vías por contacto restringe la resolución a ese canal, y con uuid el resolver lo ignora pero el contrato igual lo exige.
Exactamente uno de phone, username, whatsapp_user_id o uuid debe venir: cero o dos identificadores responden 400 (INVALID_REQUEST).

​
Respuesta

window_open es el campo que decide qué puedes enviar: si es false, el único mensaje permitido es una plantilla aprobada. window_expires_at viene en null cuando el contacto nunca escribió (la ventana nunca se abrió), e inbox_status es pending o resolved. mailbox y ai_employee son null cuando la conversación no tiene buzón o empleado AI asignado. is_tester marca si la conversación se creó desde el módulo de pruebas.
En contact_info, whatsapp_user_id devuelve el BSUID real cuando existe, con fallback al teléfono mientras Meta no migre. Si el valor que recibes es el teléfono, reenvíalo como phone y no como whatsapp_user_id — el resolver matchea BSUIDs por igualdad exacta y daría 404.
Errores
  • 400 INVALID_REQUEST — la referencia trae cero o dos identificadores, o falta channel.
  • 404 CONVERSATION_NOT_FOUND — la conversación no existe o pertenece a otro negocio. CHANNEL_NOT_FOUND — la clave de canal no existe.
  • 409 PHONE_NUMBER_AMBIGUOUS / USERNAME_AMBIGUOUS — varios contactos comparten ese teléfono o ese username. Identifica por whatsapp_user_id o uuid.

​
Ejemplo

Una lectura pura: consulta el estado y no cambia nada de la conversación.
Si la respuesta trae "window_open": false, la acción que corresponde es enviar una plantilla; si trae true, puedes mandar texto, media o una respuesta rápida.

​
Hilo de mensajes y eventos

Devuelve los mensajes y los eventos del historial. Se identifica con la misma referencia, así que no hace falta conocer ningún uuid. Parámetros
  • phone / username / whatsapp_user_id / uuid — la referencia de la conversación, con la misma regla: exactamente uno.
  • channel — clave pública del canal (obligatorio).
  • cursor — cursor opaco devuelto por la página anterior en next_cursor (hasta 512 caracteres). No reutilices cursores entre endpoints distintos.
  • limit — items por página. Por defecto 50, máximo 100.
El hilo se pagina hacia atrás en el tiempo: la primera llamada trae los items más recientes y next_cursor avanza hacia los más antiguos. has_more en true significa que quedan items más antiguos por leer. El orden dentro de la página es cronológico y no es configurable (no hay parámetro order).

​
Respuesta

Cada item responde cuatro preguntas: quién habló (direction y author), qué pasó (event), con qué contenido (content_type y body) y cuándo (sent_at).
  • type — message o event. Discrimina la unión: los SDKs auto-generados lo exponen como tagged union.
  • direction — contact (lo envió la persona del otro lado) o business (salió de tu negocio).
  • author.type — customer, human, ai_employee, api_token, mass_campaign o system. author.name puede ser null.
  • event — en los message: message_received o message_sent. En los event: context_note, contact_name_updated, contact_phone_updated, contact_email_updated, scheduled_cancel o conversion.
  • content_type — en los message: text, image, audio, video, document, location, sticker, contacts, template, interactive o reaction. Siempre null en los event.
  • status — en los message: pending, sent, delivered, read o failed. Siempre null en los event.
  • sent_at — reloj de negocio del item y clave de orden del hilo. Siempre presente.
Errores
  • 400 INVALID_REQUEST — referencia inválida. INVALID_CURSOR — cursor corrupto o no emitido por este endpoint.
  • 404 CONVERSATION_NOT_FOUND / CHANNEL_NOT_FOUND.
  • 409 PHONE_NUMBER_AMBIGUOUS / USERNAME_AMBIGUOUS.

​
Ejemplo

También es una lectura: recorrer el hilo completo no altera la conversación ni marca nada como leído.
Página siguiente (items más antiguos), con el next_cursor de la respuesta anterior:
Con el estado y el historial en mano, la escritura va por las acciones: Enviar mensaje para responder y Cambiar estado de la conversación para marcarla como resuelta o pendiente. El contexto completo de la referencia y de la ventana de 24h está en Conversaciones.