Con Papo (https://papo.global/), puede usar la API REST para listar conversaciones, enviar mensajes de texto, aplicar etiquetas y asignar conversaciones a agentes, automatizando procesos de atención sin acceder a la interfaz. La API ofrece endpoints que reflejan las funcionalidades del módulo de Conversaciones, lo que permite que sistemas externos gestionen interacciones de forma programática.
| Acción de la API | Qué hace | Ejemplo de uso |
|---|---|---|
| Listar conversaciones | Devuelve las conversaciones de la cuenta, con filtros por estado, etiqueta o agente | Monitorear atenciones activas o cerradas de un CRM externo |
| Enviar mensaje de texto | Dispara un mensaje de texto a un contacto (respetando la ventana de 24 h de WhatsApp) | Notificar a un cliente sobre la actualización de un pedido |
| Aplicar etiqueta | Crea una etiqueta (si no existe) y la aplica al contacto y a la conversación abierta | Marcar conversaciones como “Urgente” o “Posventa” automáticamente |
| Asignar conversación | Asigna las conversaciones abiertas de un contacto a un agente específico | Dirigir leads al vendedor responsable de la región |
Cómo funciona la API de Conversaciones de Papo
La API de Papo sigue el estándar REST, con autenticación mediante clave secreta (token Bearer) y respuestas en JSON. Todas las operaciones descritas aquí utilizan la misma base de autenticación y pueden combinarse para crear flujos de trabajo automatizados; por ejemplo, un sistema de triaje que, al recibir un nuevo lead, lista las conversaciones recientes, aplica una etiqueta de “Nuevo” y asigna al agente de guardia.
La base de la API es https://app.papo.global/api/v1. Para utilizar los endpoints de conversaciones, etiquetas y asignaciones, necesita un token de API generado en el panel de Papo. La documentación completa con los endpoints específicos y parámetros está disponible en papo.global/pt/docs.
Paso a paso para utilizar los recursos de la API
1. Genere un token de API
En el panel de Papo, acceda a la sección de desarrollador o tokens de acceso. Cree una clave secreta (sk_live_…) con los permisos adecuados para gestionar conversaciones. Guarde el token en un lugar seguro: se enviará en el encabezado Authorization de todas las solicitudes.
2. Liste las conversaciones
Utilice el endpoint de listado de conversaciones para obtener las atenciones de la cuenta. La solicitud acepta parámetros de filtro como:
- Estado: conversaciones abiertas, cerradas o todas.
- Etiqueta: filtra por una o más etiquetas aplicadas.
- Agente: restringe a las conversaciones asignadas a un usuario específico.
- Período: intervalo de fechas para limitar la consulta.
La respuesta incluye el identificador de la conversación, el contacto, el canal, el estado y los últimos mensajes. Con estos datos, puede monitorear el volumen de atenciones o disparar acciones condicionales desde un sistema externo.
3. Envíe un mensaje de texto
Para enviar un mensaje de texto a un contacto, utilice el endpoint de envío de mensajes. La solicitud requiere:
- Número del destinatario en formato internacional (ej.:
5511999999999). - Texto del mensaje.
- Identificador de la instancia (opcional): si su cuenta tiene más de una conexión de WhatsApp, puede especificar cuál usar.
La API devuelve una confirmación de que la solicitud fue aceptada. Recuerde que el envío de mensajes de texto está sujeto a la ventana de 24 horas de WhatsApp; para comunicaciones fuera de ese período, es necesario utilizar plantillas de mensaje (HSM) previamente aprobadas.
4. Aplique etiquetas a contactos y conversaciones
La API permite gestionar etiquetas de dos formas:
- Crear una etiqueta en la cuenta: defina un título, color y descripción para la nueva etiqueta.
- Aplicar una etiqueta: asocie una etiqueta existente a un contacto y a la conversación abierta de ese contacto. Si la etiqueta aún no existe, se creará automáticamente durante la aplicación.
Esto es útil para clasificar conversaciones automáticamente con base en reglas de su sistema; por ejemplo, marcar como “Reclamación” cuando el cliente envía una palabra clave específica.
5. Asigne conversaciones a agentes
Con el endpoint de asignación, puede designar un agente para todas las conversaciones abiertas de un contacto determinado. Basta con informar el identificador del contacto y el ID del usuario/agente. La lista de agentes de la cuenta puede obtenerse mediante el endpoint de listado de usuarios, que devuelve nombre, correo electrónico e ID de cada miembro del equipo.
Esta funcionalidad es esencial para el enrutamiento automático: un sistema de CRM puede, al identificar el perfil del lead, asignarlo al vendedor correcto sin intervención manual.
Quién debe usar la API de Conversaciones
- Operaciones que ya utilizan sistemas externos (ERP, CRM, plataformas de e-commerce) y desean integrar la atención de Papo sin duplicar esfuerzos.
- Equipos de soporte con reglas de enrutamiento complejas, que necesitan clasificar y dirigir conversaciones automáticamente con base en datos del cliente.
- Desarrolladores que construyen paneles personalizados o disparan notificaciones a partir de eventos de la atención.
- Reventas white label que gestionan múltiples cuentas y quieren automatizar la configuración de etiquetas y asignaciones para cada cliente.
Preguntas frecuentes
¿Necesito un token de API para usar estos endpoints?
Sí. Todas las solicitudes a la API de Papo requieren autenticación mediante clave secreta, enviada en el encabezado Authorization: Bearer sk_live_…. Los tokens se generan en el panel de la cuenta.
¿La API permite enviar mensajes fuera de la ventana de 24 horas de WhatsApp?
El envío de mensajes de texto mediante la API respeta la ventana de 24 horas. Para comunicaciones proactivas fuera de ese período, es necesario utilizar plantillas de mensaje (HSM) aprobadas. Papo ofrece endpoints específicos para el envío de HSM.
¿Puedo listar conversaciones por etiqueta?
Sí. El endpoint de listado de conversaciones acepta filtro por etiqueta, lo que permite recuperar solo las atenciones marcadas con una o más etiquetas específicas.
¿Cómo aplico una etiqueta a un contacto mediante la API?
Utilice el endpoint de etiquetas, informando el identificador de la etiqueta (o los datos para su creación) y el identificador del contacto. La etiqueta se aplicará al contacto y a la conversación abierta correspondiente.
¿La API devuelve el historial completo de la conversación?
El listado de conversaciones devuelve los metadatos y los últimos mensajes. Para obtener el historial completo de mensajes de una conversación específica, consulte la documentación de la API, que detalla los endpoints de recuperación de mensajes.
¿Es posible asignar una conversación a un agente sin saber el ID del usuario?
Puede listar primero los usuarios de la cuenta (endpoint de agentes) para obtener los ID y luego usar el endpoint de asignación. La lista de agentes incluye nombre y correo electrónico, lo que facilita la identificación.
Lea también
- Cómo usar la API de Papo para gestionar clientes de su reventa white label
- Cómo usar la API de Papo para gestionar atributos personalizados de los contactos
Pruebe la API y todos los módulos de Papo sin costo: el primer usuario es gratuito y no requiere tarjeta de crédito.