API REST de Cuenta y Client API: autenticación, tokens y endpoints principales

La API REST Universal de Waclis Inbox permite integrar programáticamente cualquier backend corporativo, ERP, CRM o aplicación móvil con tu operación omnicanal. Mediante peticiones HTTPS en formato JSON, puedes administrar contactos, conversaciones, mensajes, tarjetas Kanban y tareas, o conectar un canal propio mediante una bandeja de tipo Canal API.

Qué puedes hacer

• Autenticar llamadas backend enviando tu Token de acceso personal en la cabecera HTTP api_access_token.
• Crear una bandeja Canal API en Ajustes > Entradas > + Añadir bandeja de entrada > API para integrar aplicaciones móviles o portales propios.
• Operar recursos de cuenta con la Application API (/api/v1/accounts/{account_id}/...) sobre /contacts, /conversations, /messages, /kanban_items y /tasks.
• Construir chats para clientes finales con la Client API (/public/api/v1/inboxes/{inbox_identifier}/...) sin exponer tokens administrativos.
• Manejar paginación y códigos HTTP (200, 401, 404, 422, 429) con control de errores estándar.

Cuándo conviene usarla

• Notificaciones y mensajes transaccionales: Cuando un sistema externo debe iniciar o responder una conversación automáticamente.
• Sincronización de clientes (CRM / ERP): Para dar de alta o actualizar fichas en /api/v1/accounts/{account_id}/contacts junto con sus atributos personalizados.
• Gestión programática de ventas y tareas: Para crear oportunidades en /kanban_items o recordatorios en /tasks desde un sistema comercial.
• Chat nativo en tu propia app: Cuando usas un Canal API y la Client API (/public/api/v1/inboxes/{inbox_identifier}/...) dentro de tu aplicación móvil o web.

Disponibilidad por plan

• Plan Estándar: Incluye Token de acceso, Application API (/api/v1/accounts/{account_id}/...), Client API (/public/api/v1/inboxes/...) y creación de bandejas Canal API.
• Plan Premium: Añade operación programática de bots de agentes, automatizaciones avanzadas y embudos comerciales.
• Plan Evolución: Incorpora conectividad mediante Servidor MCP y capacidades avanzadas de auditoría y gobierno.

Requisitos previos

1. Cuenta activa en Waclis Inbox con permisos acordes al endpoint (Administrador o Agente).
2. Identificador numérico account_id, visible en la URL del navegador (la URL de tu cuenta en el navegador).
3. Peticiones sobre HTTPS con cabecera Content-Type: application/json; charset=utf-8.

Cómo funciona en Waclis Inbox paso a paso

Parte 1: Obtener el Token de acceso personal

1. Haz clic en tu avatar abajo a la izquierda y abre Ajustes de perfil.
2. Desplázate hasta la sección Token de acceso.
3. Pulsa Copiar para obtener la clave (o regénérala si necesitas rotar credenciales).
4. En tus llamadas a /api/v1/accounts/{account_id}/..., envía la cabecera api_access_token: TU_TOKEN.

Parte 2: Crear una bandeja de tipo Canal API

1. Ve a Ajustes > Entradas y haz clic en + Añadir bandeja de entrada.
2. Selecciona el ícono API (Canal API).
3. Define el Nombre del canal y la URL del webhook donde recibirás las respuestas de los agentes.
4. Asigna los agentes con permiso y finaliza la creación.
5. Copia el inbox_identifier en la configuración de la bandeja si utilizarás la Client API.

Opciones y configuraciones disponibles

Resumen de las dos familias de endpoints y los códigos HTTP principales:

Alternativas y cuándo elegir cada una

Cómo se combina con otras funciones

• Webhooks salientes: Escuchas eventos en tiempo real por Webhook y llamas a la API REST solo cuando necesitas ejecutar una acción o consulta.
• Atributos personalizados: Los endpoints de /contacts y /conversations reciben el objeto custom_attributes para inyectar datos de negocio.
• Bots de agentes (Agent Bots): Usan tokens de bot para responder chats y pasarlos a estado open.

Relación con otros productos Waclis

• En Waclis Inbox (Nativo): La API REST opera los recursos nativos de Inbox (contactos, chats, mensajes, Kanban y tareas).
• Con el ecosistema Waclis (Waclis Connect, WaclisPOS, Waclis Factur, WaclisCAL y Waclis Reach): Waclis Connect gobierna la identidad y sesión única entre aplicaciones manteniendo el aislamiento de datos por organización. Para integrar sistemas externos o articular flujos programáticos con herramientas como Waclis Reach, WaclisPOS o tu propio ERP, puedes utilizar la API REST de Cuenta y los Webhooks.
• Con panel.waclis.com: Los planes y asientos de la cuenta se administran desde panel.waclis.com.

Buenas prácticas

Errores frecuentes y solución de problemas

Preguntas frecuentes

¿Dónde obtengo mi api_access_token en Waclis Inbox?

En tu avatar abajo a la izquierda, ingresa a Ajustes de perfil y copia la clave ubicada en la sección Token de acceso.

¿Cómo publico una nota privada interna mediante la API?

Envía un POST a /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages incluyendo "private": true y "content": "Texto".

¿Qué sucede si regenero mi Token de acceso en Ajustes de perfil?

El token anterior queda revocado al instante y deberás actualizar la credencial en todos tus servicios externos.

¿Cómo envío archivos adjuntos por la API REST?

Envía el POST a /messages con formato multipart/form-data adjuntando los archivos en el campo attachments[].

Artículos relacionados

• Webhooks salientes en tiempo real y verificación de firma de seguridad HMAC-SHA256
• Aplicaciones del panel: incrustación de portales web en iFrames contextuales del chat
• Configuración de bandejas de entrada y canales personalizados