API Key y ARI

Panorama

Conexia Infinity ofrece cinco vías de integración; esta referencia cubre las dos de backend → plataforma. Se complementan con las «en vivo» (Real-time API y Conector MCP) y con el Webhook, documentadas aparte.

Parte A · API Key — consultar: qué es y cómo autentica

La API Key es una vía HTTP de solo lectura: preguntas, la plataforma responde. Es la fuente correcta para datos cerrados (llamadas de días pasados, configuración, presencia), no para tiempo real —eso es la Real-time API—.

• Autenticación: parámetro apikey en la URL.
• Transporte: HTTPS · GET.
• Dónde: backend, servidor a servidor.
• Buenas prácticas: cachea lo que cambia poco (CDR de días cerrados, configuración); no sondees en bucle apretado.

Historial de llamadas (CDR)

Para poblar la pestaña de actividad del contacto, cuadros de mando y reporting.

Flujo típico de sincronización

1. <PREFIJO>.tenant.list una vez para conocer tu server (código de tenant).
2. <PREFIJO>.cdr.download periódicamente, por rango de fechas y paginado, para traer las llamadas nuevas. Cruza los campos de origen/destino con tus contactos.
3. Por cada llamada con grabación disponible, pide <PREFIJO>.transcription.get con su identificador único y adjunta el texto a la actividad.
4. Guarda la última fecha sincronizada para pedir solo lo nuevo la próxima vez.

GET https://<TU_SERVIDOR>/index.php?action=<PREFIJO>.cdr.download
    &apikey=<API_KEY>&apiformat=json&server=<TENANT>
    &start=<Mmm-DD-YYYY>&end=<Mmm-DD-YYYY>&page=0

// fecha en formato Mmm-DD-YYYY (mes en inglés). Sube page mientras haya más resultados.

Grabaciones y transcripción

Cuando una llamada tiene grabación disponible, puedes pedir su transcripción con <PREFIJO>.transcription.get usando el identificador único de la llamada, y adjuntar el texto a la actividad del contacto en el CRM.

Presencia del equipo

<PREFIJO>.monitor.list devuelve el estado de todas las extensiones del tenant: ideal para un panel de supervisión del equipo completo. Refresca cada pocos segundos; no sondees en bucle apretado.

{ "0": { "ext":"<EXT>", "name":"<NOMBRE>", "status":"online", "on_call":"0", "dnd":"0" },
  "1": { "ext":"<EXT>", "name":"<NOMBRE>", "status":"online", "on_call":"1", "dnd":"0" } }

// derivación: offline si status≠online; si no → en llamada (on_call=1), no molestar (dnd=1)

Parte B · ARI — originar (click-to-call): qué es y cómo autentica

La ARI es la vía para originar llamadas desde tu backend: haces sonar la extensión del agente y, al descolgar, la centralita marca al destino y los une. Una sola petición REST resuelve el click-to-call.

• Autenticación: Basic Auth (usuario:contraseña).
• Transporte: HTTPS · REST.
• Restricción por IP: la ARI solo acepta peticiones desde las IPs autorizadas (la IP pública de tu servidor). Es una capa de seguridad, no un obstáculo.
• Dónde: backend. La credencial nunca sale al cliente.

Click-to-call desde la ficha

El botón «Llamar» sobre un teléfono del contacto.

1. El agente pulsa «Llamar» en la ficha. El navegador solo avisa a tu backend (extensión del agente + número del contacto). La credencial ARI no sale al cliente.
2. Tu backend hace POST /channels a la ARI con Basic Auth.
3. Suena el teléfono del agente; al descolgar, la centralita marca al destino y conecta.
4. En paralelo, tu puente Real-time recibe event_call_started (state:2, Ring Out): úsalo para reflejar el estado en la interfaz.

POST https://<ARI_URL>/channels
Authorization: Basic base64(<ARI_USER>:<ARI_PASS>)
Content-Type: application/x-www-form-urlencoded

endpoint=Local/<EXT>@<TENANT>      // EXT = extensión del agente; TENANT = contexto del tenant
&extension=<DESTINO>                // número del contacto (destino)
&context=<TENANT>&priority=1&timeout=40&app=<APP>

¿Y si necesito control fino del dispositivo?

Con la ARI, Local/<EXT> hace sonar los dispositivos de esa extensión según su configuración. Si necesitas elegir «solo softphone» o «solo móvil», eso se hace mejor con el comando call de la Real-time API y su parámetro device.

Diagnóstico: 403 al originar

• ¿Cambió la IP pública de tu servidor? Si tu backend salió por otra IP (proxy, nuevo despliegue), la lista blanca ya no coincide.
• ¿Credenciales correctas pero mismo 403? Es señal casi segura de IP, no de auth.

Cómo empezar

1. Solicita credenciales. Pide a tu contacto de Conexia tu <API_KEY>, tu código de tenant y las credenciales ARI; para la ARI, indica la IP pública de tu servidor para la lista blanca.
2. Empieza por consultar. Con la API Key, sincroniza el CDR y muéstralo en la actividad del contacto. Es de solo lectura: bajo riesgo.
3. Añade el click-to-call con la ARI (POST /channels) desde el backend.
4. Combina con las vías en vivo (Real-time API) para el Call Popup y el control de la llamada.

¿Buscas las otras vías? Consulta la referencia de Real-time API y Conector MCP y la de Webhook en el índice de integraciones.