Para gestionar los atributos personalizados de los contactos de forma programática, utiliza la API REST de Papo. Con autenticación por clave secreta, puedes listar definiciones de atributos, crear nuevos campos personalizados y definir o fusionar valores en los contactos — ideal para sincronizar datos de CRMs externos, enriquecer perfiles y afinar la segmentación de campañas y automatizaciones sin intervención manual.
La API de Papo expone recursos específicos para atributos personalizados, lo que permite que tu operación mantenga una base de contactos siempre actualizada con información relevante del negocio. Ya sea para importar datos de un ERP, migrar listas de un CRM heredado o automatizar la clasificación de leads, estos endpoints funcionan con la misma autenticación simple que el resto de los recursos de la plataforma.
Resumen del proceso de integración
| Etapa | Acción | Detalle importante |
|---|---|---|
| 1. Obtener las claves | Generar la clave secreta (sk_live_…) y copiar la clave pública (pk_live_…) en el panel de Papo. | La clave secreta aparece una única vez; guárdala en un lugar seguro. |
| 2. Autenticar las llamadas | Incluir el header Authorization: Bearer sk_live_… en todas las peticiones de escritura. |
La clave pública puede enviarse en el header X-Papo-Public-Key (opcional). |
| 3. Gestionar las definiciones | Listar los atributos existentes o crear uno nuevo (con clave, nombre visible y modelo). | Consulta la documentación oficial para los paths y payloads exactos. |
| 4. Actualizar contactos | Enviar la petición para fusionar los custom_attributes en el contacto deseado. |
Se pueden actualizar uno o varios atributos a la vez, en lote mediante scripts. |
| 5. Verificar las respuestas | La API devuelve success: true y los datos actualizados. |
En caso de error, el cuerpo incluye el código y el mensaje para corregirlo. |
Cómo funciona: paso a paso
1. Autenticación y claves
Toda llamada que modifica datos exige la clave secreta de la cuenta, enviada como token Bearer en el header Authorization. La clave pública (fija por cuenta) puede acompañar la petición en el header X-Papo-Public-Key — su uso es opcional, pero si se envía debe corresponder a la misma cuenta de la clave secreta. La URL base de la API es https://app.papo.global/api/v1. Las claves se generan en el área de desarrollador del panel de Papo.
2. Gestionar las definiciones de atributos
Antes de poblar valores, es necesario que la definición del atributo exista en la cuenta. La API permite:
- Listar todos los atributos personalizados ya registrados, para auditar la estandarización o mapear campos antes de una integración.
- Crear una nueva definición, indicando:
attribute_key— identificador único (ej.:plano,ciudad).attribute_display_name— nombre legible que aparece en el CRM (ej.: “Plan Contratado”).attribute_model— tipo del campo: texto, número, fecha o lista (con opciones predefinidas).
Estas operaciones son esenciales para preparar la estructura que recibirá los datos provenientes de sistemas externos.
3. Definir y actualizar valores en los contactos
Con las definiciones listas, puedes enviar peticiones para fusionar los custom_attributes en un contacto específico. El payload incluye un objeto clave-valor con los atributos que deseas actualizar. Por ejemplo, para definir el plan “Pro” y la ciudad “São Paulo” en un contacto, el JSON contendría algo como {"plano": "Pro", "ciudad": "São Paulo"}. La API procesa un contacto por petición, pero la operación en masa se consigue ejecutando múltiples llamadas en secuencia — con scripts en Python, Node.js o automatizaciones en n8n.
4. Sincronización con CRM externo (caso de uso típico)
Un script puede:
- Leer registros de un CRM externo, ERP o base de datos.
- Para cada registro, mapear los campos de interés a las
attribute_keycorrespondientes en Papo. - Si es necesario, crear la definición del atributo (en caso de que aún no exista).
- Enviar la petición de actualización del contacto (identificado por ID, email o teléfono) con los
custom_attributes. - Recoger las respuestas y tratar eventuales errores (campo inválido, clave inexistente, etc.).
Así, la base de Papo se mantiene como espejo fiel de los datos de tu ecosistema, lista para segmentaciones y automatizaciones.
5. Impacto en las automatizaciones y campañas
Una vez que los atributos están poblados, quedan disponibles de inmediato para:
- Flows con condición basada en el atributo del contacto (ej.: enviar un mensaje específico a quien tiene
planoigual a “Enterprise”). - Segmentos dinámicos para campañas de WhatsApp o email marketing.
- Informes y filtros en el CRM, permitiendo que los equipos visualicen y prioricen contactos en función de cualquier campo personalizado.
Para quién está indicada esta integración
- Empresas que usan múltiples sistemas (CRM, ERP, e-commerce) y necesitan centralizar la información de los clientes en Papo sin digitación manual.
- Operaciones que migran desde otra plataforma y desean importar no solo los contactos, sino también campos personalizados como “fuente del lead”, “score” o “última compra”.
- Equipos de marketing y ventas que segmentan campañas en función de datos estructurados (plan, región, interés) y necesitan que esos datos estén siempre actualizados.
- Revendedores white label que personalizan atributos para cada cliente final y quieren automatizar la sincronización a partir de los sistemas de los propios clientes.
Preguntas frecuentes
¿Necesito crear el atributo antes de definir el valor en el contacto?
Sí. La definición del atributo (con attribute_key, nombre y modelo) debe existir en la cuenta. Puedes crearla vía API o desde el panel en Configuración → Atributos Personalizados.
¿Qué tipos de atributos puedo crear vía API?
La API admite los mismos tipos disponibles en el panel: texto, número, fecha y lista (con opciones predefinidas). El modelo se indica en el campo attribute_model al crear la definición.
¿Cómo actualizar varios contactos a la vez?
La API procesa un contacto por petición. Para operaciones en masa, automatiza el envío en lote con scripts (Python, Node.js) o herramientas como n8n, iterando sobre una lista de contactos y enviando las peticiones de forma secuencial.
¿Dónde encuentro los endpoints exactos y el formato del payload?
En la documentación oficial de la API, disponible en https://papo.global/pt/docs. Allí están detallados los endpoints de atributos personalizados, la autenticación y ejemplos de código.
¿Puedo usar la API para limpiar o eliminar un atributo de un contacto?
La documentación de la API describe las operaciones disponibles. Para casos de eliminación o limpieza, consulta la referencia oficial para verificar si hay endpoints específicos o si es necesario redefinir el valor.
¿Los atributos actualizados vía API disparan automatizaciones?
Sí. La actualización de un contacto vía API puede disparar eventos internos, como la ejecución de Flows configurados con disparadores relacionados con cambios en el contacto, siempre que se cumplan las condiciones.
Lea también
- Cómo usar la API de Papo para crear y actualizar contactos en masa
- Cómo usar la API de Papo para crear y gestionar etiquetas (tags)
Empieza gratis e integra tus datos →
Con la API de Papo, sincronizas atributos personalizados en masa y afinas la segmentación de campañas sin salir de tu flujo de trabajo.