/m2m/v1. Usa Authorization: Bearer <API_KEY>. La credencial fija el negocio; no se admite cambiarlo mediante parámetros. Las claves y autorizaciones OAuth existentes no reciben permisos nuevos automáticamente: un administrador debe concederlos. Las mismas operaciones están disponibles como herramientas MCP cuando el servicio MCP está habilitado.
Endpoints y herramientas MCP
Buscar una conversación
GET /conversations?contactQuery=Maria&channel=whatsapp&owner=OPERATOR_ID&limit=50
contactQuery usa la búsqueda de contactos del panel (2–200 caracteres). channel: all, whatsapp, instagram, messenger o webchat. owner: all o el ID de 24 caracteres de un operador activo del negocio; las credenciales de máquina no admiten mine. Consulta operadores con /conversations/assignable-operators y el permiso conversations:assignment:read.
Pasa nextCursor como cursor mientras hasMore sea verdadero, conservando todos los filtros. La lista es dinámica: mensajes nuevos pueden mover conversaciones entre páginas. Elimina duplicados por conversationId al combinar páginas. Los filtros también afectan los contadores. Un cursor o filtro inválido devuelve 400; un operador externo o inactivo, 404.
Gestionar seguimientos
Busca oportunidades de venta para obtenerleadId y conversationId. La lista admite estado, modo, lead, conversación y dueAfter; devuelve 50 por defecto, máximo 200. Continúa con nextCursor mientras hasMore sea verdadero.
messageDraft o dueAt; dueAt:null elimina la fecha. Descartar/cancelar acepta feedbackReason opcional. Enviar acepta messageText opcional y reutiliza la identidad durable del envío. Una ejecución activa o completada puede devolver 409. No crees otro seguimiento para reintentar un envío.
El envío devuelve 202 con followUp y reply. Consulta reply.requestEventId mediante /message-requests/{requestEventId}/status, con messages:read. crmStatusUpdateFailed:true significa que el envío fue aceptado pero falló la actualización del CRM: verifica el recibo antes de reintentar. Aceptado no significa entregado. Los envíos manuales heredan la pausa de respuestas configurada para el negocio.
Configurar automatización
Consulta/crm/follow-up-settings antes de modificarlo. PATCH admite followUpMode (off, draft, auto), followUpLevel (light, balanced, proactive), followUpInstructions (máximo 2.000 caracteres) y quietHours (start/end, valores HH:mm distintos en la zona horaria del negocio). Solo cambian los campos enviados; se requiere al menos uno.
auto puede producir envíos futuros, incluidos seguimientos existentes elegibles. Cambia la automatización solo por instrucción explícita. Crear o editar un seguimiento no modifica esta configuración. Se mantienen las reglas existentes de elegibilidad y horario del CRM.
Completar trabajo de la bandeja
Marcar como leído, resolver respuesta pendiente, resolver revisión y resolver derivación son operaciones diferentes. Crear una revisión admitereasonCode (other por defecto), note y assignedOperatorId opcionales. Motivos: ai_response_issue, knowledge_gap, policy_compliance, guest_experience, booking_payment, other. Las notas admiten 2.000 caracteres. Una revisión o derivación ya abierta devuelve 409. Para asignar se requiere operatorId; usa null para quitar la asignación. Resolver admite resolutionNote opcional.
Se conservan las actualizaciones en tiempo real del panel y se registra la credencial como actor. Resolver respuesta pendiente no cierra una derivación ni una revisión.
Iniciar una conversación de WhatsApp
Consulta/conversations/start/whatsapp-template-status?channelId=CHANNEL_ID. Lee el estado guardado sin crear ni actualizar plantillas en el proveedor. not_prepared indica que falta prepararla desde el panel. Iniciar requiere una plantilla preparada y aprobada, un canal disponible, consentimiento del destinatario y ausencia de opt-out.
Envía POST /conversations/start con una cabecera Idempotency-Key estable:
en_US y es_MX. contactName es opcional; messageText admite 1.024 caracteres. Repite una clave únicamente con los mismos datos. Las claves se delimitan por negocio y conversación destino; datos incompatibles devuelven 409. Los intentos antiguos del panel sin huella de solicitud conservan su comportamiento de reintento. La respuesta incluye conversationId, replyId y requestEventId. El 202 significa en cola, no entregado. Verifica un intento fallido antes de iniciar otro envío.
Reservas y mensajes a huéspedes
GET /reservations consulta registros sincronizados, no disponibilidad en tiempo real. Filtra por integrationId, reservationId o estado; ordena por booked_at o check_in_date, ascendente o descendente. Las páginas admiten 20 registros. Continúa con nextCursor mientras hasNext sea verdadero, manteniendo filtros y orden. Recibos e intentos usan la misma paginación de 20 registros. La consulta por conversación devuelve hasta cinco reservas con la asociación existente por teléfono del huésped.
Las lecturas de disponibilidad de configuración y eventos muestran integraciones, remitentes y ajustes. Las escrituras admiten una integración Cloudbeds por solicitud. Configura un evento con {"enabled":false} o el remitente con {"channelId":"CHANNEL_ID"}. Eventos: booking_confirmed, pre_checkin, post_checkout_review. El remitente debe ser un canal WhatsApp disponible del mismo negocio. Integraciones externas o no compatibles devuelven 404; remitentes inválidos o no disponibles, 400/404. Se respetan las restricciones globales existentes.
Activar un evento cambia mensajes futuros; no envía inmediatamente ni garantiza entrega. Los resultados would_send, deferred, skipped, invalid, duplicate y error son diagnósticos, no recibos de entrega. Los contadores existentes denominados sent tampoco prueban entrega del proveedor. No se exponen creación/cancelación de reservas, disponibilidad en vivo, campañas masivas ni cambios de eventos para todo el negocio.