Cómo funciona la API de Whaticket

La API de Whaticket permite que otros sistemas envíen mensajes y trabajen con chats, contactos y otros datos de tu cuenta. Cada llamada usa un token, y lo que ese token puede hacer depende de los permisos del perfil vinculado a él.

Qué puedes hacer con la API

Enviar mensajes de texto, archivos y plantillas a uno o varios contactos.
Consultar las conexiones y reiniciar una conexión WhatsApp QR Code desconectada.
Listar y crear contactos, y crear o actualizar un contacto existente.
Listar chats, responder, resolver, posponer, transferir, asignar y cambiar el departamento de un chat.
Consultar usuarios, departamentos, respuestas rápidas, mensajes programados e informes de conversaciones.
Gestionar los artículos y las lagunas de la base de conocimiento de Wäbot.

La lista completa de rutas, con los permisos que exige cada una, está en la pestaña Documentación.

Antes de empezar

Usar la API requiere conocimientos técnicos. Te recomendamos contar con un profesional de TI con experiencia en integraciones.
Para crear tokens, tu perfil necesita el permiso Crear en el grupo Tokens de API.
El perfil elegido para el token necesita los permisos de cada ruta que vas a usar. Para enviar mensajes, por ejemplo, se necesitan Crear e Iniciar en el grupo Campañas.
En conexiones WhatsApp QR Code, los mensajes enviados por la API consumen créditos de campaña. Las conexiones de API oficial no usan créditos, pero requieren una plantilla aprobada.

Paso a paso:

Crea un token de acceso

En el menú de la izquierda, haz clic en Integraciones.
En la pestaña Tokens, haz clic en Nuevo token.
Ponle un Nombre al token y elige el Perfil. En Permisos de este perfil, revisa lo que podrá hacer el token.
Haz clic en Guardar.
En la ventana Copia la clave del token, copia la Clave y guárdala en un lugar seguro. No vuelve a aparecer después de cerrar la ventana.

Los permisos del perfil se aplican en cada solicitud. Si editas el perfil, el token sigue los nuevos permisos al instante, sin generar otro.

Autoriza el token en la documentación

En Integraciones, abre la pestaña Documentación.
Haz clic en Authorize.
Pega la clave del token y confirma.
En cada ruta, usa Try it out para completar los campos y Execute para enviar la solicitud.

Consulta tus conexiones

La ruta GET /whatsapps lista las conexiones de WhatsApp con id, name, status y channel. El id es el que usas para enviar mensajes y reiniciar una conexión. El channel indica si es QR Code (WHATSAPP) o API oficial (WABA o WABA-COEX).

Reinicia una conexión desconectada

Abre la ruta PATCH /whatsapps/start/{whatsappId} y haz clic en Try it out.
Ingresa el ID de la conexión.
Haz clic en Execute.

La ruta tiene el mismo efecto que intentar reconectar en la pantalla de Conexiones. Solo funciona en conexiones WhatsApp QR Code desconectadas, y el perfil del token necesita el permiso Reiniciar en el grupo Conexiones.

Envía mensajes

Abre la ruta POST /messages y haz clic en Try it out.
Completa connectionId con el ID de la conexión.
En messages, indica para cada contacto el number (solo números, con código de país), el name y el body con el texto.
Haz clic en Execute.

Para enviar el mismo texto a varios contactos, usa globalBody y deja en messages solo el number de cada contacto. Cada solicitud acepta hasta 999 mensajes.

En conexiones de API oficial, indica también el templateId de la plantilla aprobada.

Envía archivos multimedia

Abre la ruta POST /medias, haz clic en Try it out y selecciona el archivo en tu computadora.

Haz clic en Execute y copia el mediaKey que aparece en la respuesta.

En la ruta POST /messages, indica el connectionId, pega el código en globalMediaKey e indica el tipo en globalMediaType: image, video, audio o document. Para un archivo distinto por contacto, usa mediaKey y mediaType dentro de cada mensaje.

Asigna el chat a un agente y a un departamento

En el mensaje, agrega el bloque ticketData.
En status, usa open, pending o closed.
En userId, indica el ID del agente. Lo copias en Equipo, editando el usuario.
En queueId, indica el ID del departamento, que copias en Departamentos & Chatbots.
Usa force con valor true para aplicar estos datos también a un chat que ya existe.

Sin ticketData, el chat se crea en Resueltos.

Mantén el chat con el agente

Desde la API, aplicas las opciones Mantener conmigo y Mantener conmigo hasta al chat creado.

Para mantener el chat con el agente sin plazo, usa keepAssigned con valor true junto con el userId.

Para mantenerlo hasta una fecha, agrega keepAssignedUntil con una fecha futura (a partir de mañana) en formato AAAA-MM-DD. El chat se libera automáticamente al inicio del día indicado, a las 0 h en horario UTC. Para mantener el chat durante un día entero, indica el día siguiente.

La retención se aplica cuando la API crea el chat. Para cambiar la retención o la fecha de un chat que ya existe, envía los nuevos valores con force en true. La nueva fecha reemplaza la anterior.
Si envías keepAssigned sin fecha, el chat queda con el agente sin plazo.

Preguntas frecuentes

¿Hay un límite de uso?
Sí. Cada ruta acepta hasta 600 solicitudes por minuto. Cada mensaje puede tardar hasta 120 segundos en enviarse.

¿Dónde veo los mensajes enviados por la API?
En Campañas. Los envíos de la API se agrupan en una campaña por día y por conexión, con el nombre API - seguido de la fecha.

¿Qué hago si la solicitud da error?
Lee el mensaje de error en la respuesta. Indica el campo con problema, como un número fuera del formato internacional o la falta de un permiso en el perfil del token. Revisa los campos y vuelve a intentarlo.

Perdí la clave del token. ¿Qué hago?
En la pestaña Tokens, haz clic en Regenerar. La clave anterior deja de funcionar de inmediato, así que actualiza los sistemas que la usan.