Importar Contactos mediante API Externa

🔌

CRMInbox · Integraciones — REST API

Conecta CRMInbox a cualquier sistema externo (CRM, ERP, e-commerce o base de datos) mediante peticiones HTTP en tiempo real y mapea variables personalizadas para tus llamadas con IA.

💡 Integración Universal por API: El conector de API REST de CRMInbox te permite consultar directamente tus propios servidores o servicios de terceros (como HubSpot, Salesforce, WooCommerce o endpoints personalizados en Node, Python, PHP o n8n) para obtener destinatarios al instante sin necesidad de exportar ni subir archivos.

🎯 Objetivo

Configurar una petición HTTP (GET o POST), autenticar la conexión (Bearer, API Key o Basic Auth), extraer los contactos del payload JSON, mapear las columnas a variables dinámicas para el Agente de IA y validar los teléfonos antes del lanzamiento.

✅ Requisitos técnicos previos

🌐

Endpoint HTTP accesible: Dirección URL de tu API que responda con una estructura de datos en formato JSON. Se aconseja utilizar HTTPS.

🔑

Credenciales de autenticación: Token JWT, API Key de cabecera o usuario y contraseña según los requerimientos de tu servidor.

📞

Campo telefónico internacional: Los números en el JSON deben incluir el código de país (ej. +52 para México) para que la validación telefónica sea inmediata.

Procedimiento

Pasos para configurar la conexión y los contactos

1

Seleccionar el Origen API y Definir la URL del Endpoint

Abre el asistente de importación por API e ingresa la URL de tu servicio web y el método de consulta.

Ruta: Crear Campaña → 2. Selección de contactos → Añadir contactos por API

En la fase 2. Selección de contactos de tu campaña de voz:

Haz clic en la tarjeta Añadir contactos por API (Obtén tus contactos directamente desde un endpoint).
Se desplegará el modal interactivo con el asistente de 3 pasos: 1 Configurar Endpoint → 2 Mapeo de campos → 3 Revisión.
URL del Endpoint: Escribe o pega la dirección URL completa de tu servicio (ej. https://api.tuempresa.com/v1/contacts).
Método HTTP: Selecciona GET si los datos se consultan de forma estándar o POST si tu API requiere enviar un cuerpo de consulta.

Modal de configuración de Endpoint con campo URL y selector de Método HTTP

✅ Resultado esperado: Aparecerán las opciones para configurar las cabeceras de autenticación y la estructura de datos.

2

Configurar el Esquema de Autenticación

Elige entre Bearer Token, API Key en Header, Basic Auth o acceso público según las políticas de tu servidor.

En el campo Tipo de Autenticación, selecciona el mecanismo requerido por tu API:

1. Ninguna: Para endpoints públicos o pruebas sin cabeceras de autorización requeridas.

2. Bearer Token: Envía el encabezado Authorization: Bearer <token>. Ideal para tokens JWT y OAuth2.

3. API Key en Header: Permite especificar el Nombre del Header (ej. X-API-Key) y su correspondiente Valor.

4. Basic Auth: Envía credenciales codificadas en Base64 ingresando Usuario y Contraseña.

Desplegable con los cuatro tipos de autenticación disponibles

✅ Resultado esperado: Los campos dinámicos de credenciales se adaptarán inmediatamente a la opción seleccionada.

3

Ruta de Datos en JSON y Prueba de Conexión en Vivo

Especifica la ruta JSON donde está el listado de clientes y presiona Probar Conexión para validar la respuesta.

Define la localización de los registros dentro de la respuesta:

Ruta de la lista de contactos en JSON: Indica la clave donde se aloja el arreglo de registros (ej. results, data.contacts o items). Si el arreglo está en la raíz, déjalo vacío.
Configuración de Paginación: Actívala si tu servicio distribuye los registros en varias llamadas (por número de página o cursor).
Probar Conexión: Haz clic en el botón azul para verificar la comunicación en tiempo real.

✅ Si la conexión es exitosa, se mostrará un banner verde indicando el número exacto de registros devueltos por el endpoint.

Configuración de ruta JSON y opciones de paginación

Banner de confirmación: Conexión exitosa y conteo de contactos detectados

✅ Resultado esperado: Al validar la conexión, se activará el botón Siguiente para pasar al mapeo de campos.

4

Mapeo de Teléfono, Nombre y Variables Dinámicas

Conecta los campos del JSON con las columnas de CRMInbox y añade variables personalizadas para el agente de voz.

En la etapa 2. Mapeo de campos, vincula las propiedades del JSON con CRMInbox:

Teléfono (Obligatorio): Selecciona el atributo JSON que almacena el número de contacto (ej. phone, celular).

Nombre (Opcional): Selecciona el atributo con el nombre del destinatario (ej. name, first_name).

Inyección de Variables Dinámicas para el Agente de IA:

Presiona + Añadir campo personalizado para mapear datos como saldos, fechas o servicios (ej. actividad_cliente).
Asigna el nombre de la variable en CRMInbox (ej. actividad_cliente). Podrás usarla en el prompt del agente escribiendo {{actividad_cliente}}.

Mapeo de los campos requeridos: Teléfono y Nombre

Formulario para añadir campo personalizado

Mapeo completo con campos personalizados vinculados

✅ Resultado esperado: Cada atributo personalizado quedará disponible para que la IA lo mencione de forma natural en la llamada.

5

Auditoría de Registros, Búsqueda y Guardado Final

Inspecciona la tabla de contactos válidos e inválidos, aplica filtros de búsqueda y confirma la importación.

En la etapa 3. Revisión de contactos importados, audita la lista obtenida:

Contactos Válidos

Inválidos / Incompletos

Usa la barra de búsqueda y los checkboxes para filtrar o descartar registros puntuales. Cuando la lista esté lista, presiona Guardar contactos para integrarlos a la campaña.

Tabla de revisión con desglose de contactos válidos e inválidos

Filtrado y selección manual en la tabla de resultados

Botón final Guardar contactos con confirmación de registros

✅ Resultado esperado: Los contactos se añadirán a la lista de marcación de la campaña y podrás proceder a la Programación.

🧭 Preguntas frecuentes

¿Qué formato debe tener el teléfono para ser considerado 'Válido'?

Debe ser un número numérico completo que incluya el prefijo internacional (estándar E.164, por ejemplo +52 para México o +57 para Colombia). Números con menos de 10 dígitos o caracteres alfanuméricos serán clasificados como inválidos.

¿Qué significa el error 'Ruta JSON no encontrada'?

Significa que la clave ingresada en el campo 'Ruta de la lista' no coincide con la estructura del JSON retornado por tu servidor. Si tu respuesta es {"data": {"items": [...]}}, la ruta correcta debe ser data.items.

¿Puedo conectar webhooks o flujos de Make, n8n o Zapier?

Sí. Puedes crear un webhook que procese los datos de tus sistemas y devuelva un array JSON con la lista de clientes. CRMInbox consultará esa URL mediante GET o POST de forma totalmente transparente.

¿Se pueden actualizar los datos antes de lanzar la campaña?

Sí. Si tus contactos cambian frecuentemente, puedes ingresar a editar la campaña y volver a ejecutar la consulta por API para traer la lista actualizada justo antes de programar la emisión.

Documentación relacionada y otros orígenes

📞 Guía Base: Cómo Crear Campañas de Voz en CRMInbox→ 📊 Añadir contactos mediante archivo Excel o CSV→ 🌐 Añadir contactos desde WispHub (Clientes y Cobranza)→ 📡 Añadir contactos desde MikroWisp (Clientes y Cobranza)→ 🧭 Comparativa de los 5 Orígenes de Campañas de Voz→

VOLVER A LA GUÍA MAESTRA DE CAMPAÑAS ➜