Saltar al contenido principal

API REST local

AI Softphone tiene una API REST para la integración CTI: un programa del mismo ordenador puede hacer y controlar llamadas, leer los contactos, el historial de llamadas y las cuentas SIP, y vigilar las llamadas en curso. Sin SDK, sin intermediario en la nube y sin ningún puerto de escucha expuesto a la red. Las peticiones y las respuestas son JSON, así que basta con curl o cualquier cliente HTTP.

La API está apagada tras la instalación; nada escucha hasta que la encienda. Entonces solo escucha en la interfaz de bucle local — una pequeña interfaz web que solo responde a este ordenador — y no se puede alcanzar desde la red de la oficina, una VPN u otra máquina.

Use la API cuando su programa necesite datos del teléfono o tenga que controlar una llamada. Use los webhooks cuando tenga que reaccionar a las llamadas a medida que ocurren, sin sondear. La mayoría de las integraciones usan ambos; son independientes entre sí.

Encenderla​

Abra Ajustes → Integración y vaya a Control local.

  1. Encienda Dejar que otros programas de este ordenador manejen el teléfono. El servidor arranca al momento.
  2. Mantenga el Puerto por defecto, 8377, salvo que otro programa ya lo use.
  3. Opcionalmente, ponga un Token. Una vez guardado, el campo muestra Guardado — escriba para reemplazarlo.
  4. En Acceso, elija los grupos que abrir: Contactos, Historial de llamadas, Las llamadas y su control, Cuentas, Ajustes, Contadores (las métricas). Un grupo apagado no se filtra: directamente no se sirve.
  5. Pruébela: curl http://127.0.0.1:8377/accounts. Si la respuesta es JSON, la API funciona.

No se instala ningún servicio aparte y no hace falta reiniciar. La parte del programa que hace esto se puede apagar en Módulos (Integración).

La página de la propia API​

Abrir la página de la propia API abre http://127.0.0.1:8377 en un navegador. La dirección responde con una lista de todo lo que sirve, en inglés; las direcciones que leen algo son enlaces que puede seguir.

El acceso y el token​

Lo que puede hacer un programa depende de si cambia datos guardados, no de si lee:

  • Sin token, cualquier programa del ordenador puede leer todo lo de los grupos encendidos y controlar llamadas: hacer, contestar, colgar, poner en espera, reanudar, transferir y enviar DTMF.
  • Con el token en la cabecera Authorization, también puede usar los puntos de acceso que cambian lo guardado. Sin el token, esos puntos de acceso no aparecen en la página de la propia API y responden 401. Si no hay ningún token puesto, nada puede cambiar lo guardado.

El token se guarda en el llavero del ordenador, no en el archivo de ajustes, y /settings nunca lo devuelve.

precaución

Sin token, cualquier programa que se ejecute en este ordenador puede controlar el teléfono, incluido contestar llamadas. En un puesto personal eso suele ser aceptable. En una máquina compartida o gestionada, ponga un token y trátelo como cualquier otra contraseña. El token solo protege las peticiones que cambian datos guardados, no las llamadas: para que otros programas no puedan tocarlas, apague Las llamadas y su control en Acceso.

Puntos de acceso​

La dirección base es http://127.0.0.1:8377. Los puntos de acceso de abajo no necesitan token.

MétodoRutaHace
GET/metricsLos contadores, en formato Prometheus.
GET/uiLa lista de grabaciones, como página HTML.
GET/ui/recordings/{id}Una grabación con su transcripción, como página HTML.
GET/ui/recordings/{id}/audioEl audio de la página anterior.
GET/contactsLos contactos.
GET/contacts/{id}Un solo contacto.
GET/historyEl historial de llamadas, con la más reciente primero. Admite ?limit=, ?missed=true y ?declined=true.
GET/callsLas llamadas en curso.
POST/callsHace una llamada: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerContesta una llamada.
POST/calls/{id}/hangupCuelga una llamada.
POST/calls/{id}/holdPone una llamada en espera.
POST/calls/{id}/resumeLa saca de la espera.
POST/calls/{id}/dtmfEnvía tonos: {"digits": "..."}.
POST/calls/{id}/transferTransfiere la llamada: {"target": "..."}.
GET/accountsLas cuentas SIP y su estado de registro. Nunca una contraseña.
GET/settingsToda la configuración, sin los secretos.
GET/taxonomyCategorías, etiquetas y señales, con sus códigos.

Puntos de acceso que necesitan el token​

Cambian lo guardado, así que cada petición tiene que llevar el token en la cabecera Authorization. La página de la propia API solo los muestra a una petición que lo lleve.

MétodoRutaHace
POST/contactsAñade un contacto: {"name": "...", "number": "...", "account_id": "..."}; account_id es opcional.
PUT/contacts/{id}Sustituye un contacto.
DELETE/contacts/{id}Elimina un contacto.
DELETE/history/{id}Olvida una llamada del registro de llamadas.
DELETE/historyOlvida todo el registro de llamadas. No se puede deshacer.
PUT/accounts/{id}Sustituye los ajustes de una cuenta. La contraseña no está entre ellos.
PUT/settingsSustituye los ajustes.

Cada identificador es un UUID emitido por el teléfono: el id de una llamada viene de /calls o de la respuesta a POST /calls, el id de una cuenta de /accounts.

Los nombres de campo están en snake_case y la terminación indica el tipo: _id es una referencia a un UUID, _ts es un momento en milisegundos Unix (UTC), _s es una duración en segundos. Lo mismo vale para los webhooks; solo /settings mantiene nombres propios. En la API REST estos valores son números JSON, y un momento desconocido es null.

Ejemplo: hacer una llamada​

POST /calls hace una llamada saliente. El cuerpo es JSON con el number que marcar y, opcionalmente, el account_id de la cuenta desde la que llamar:

curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'

La respuesta es el identificador de la nueva llamada:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number es obligatorio. Sin él, la respuesta es 400 {"error":"a call needs a number"} y no se marca nada.
  • El número se completa en la cuenta elegida igual que lo completa el marcador: 1020 se envía como sip:1020@pbx.example.com. POST /calls/{id}/transfer completa su target del mismo modo; un destino que ya tiene esquema o @ se envía tal cual.
  • account_id es opcional; tómelo de GET /accounts. Sin él, la llamada sale por la cuenta seleccionada en la ventana principal.
  • Use el id en /calls/{id}/…: hangup, hold, resume, dtmf y transfer. Los webhooks de esta llamada llevan el mismo id.

Desde una página web: clic para llamar​

Una página que llama a 127.0.0.1 llega al ordenador en el que se ejecuta el navegador — el mismo en el que se ejecuta el teléfono —, así que un botón de clic para llamar en un CRM no necesita servidor propio:

async function dial(number) {
const r = await fetch("http://127.0.0.1:8377/calls", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ number }),
});
if (!r.ok) console.warn("softphone:", (await r.json()).error);
}

Qué contienen las respuestas​

Llamadas en curso: GET /calls​

Cada llamada tiene su id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts y callstate_ts.

  • state es dialing, ringing-out, ringing-in, active, hold (en espera puesta por este teléfono), onhold (en espera puesta por el interlocutor), conference o ended. Cuando se aplica más de uno, conference gana a hold, y hold a onhold.
  • muted dice si el micrófono está silenciado en la llamada; silenciar no cambia state.
  • seance_id es la conversación: las llamadas enlazadas por una transferencia, una consulta o una conferencia lo comparten.
  • event_ts es cuándo se generó la respuesta. Compárelo con callstate_ts para saber cuánto lleva la llamada en su estado, sin depender de su propio reloj.

Cuentas: GET /accounts​

Cada cuenta tiene su id (el account_id en todas partes), sus ajustes — transport (udp, tcp o tls), port, registrar, outbound_proxy, expiry_s y otros —, si está enabled, y su state en la centralita: registered mientras la línea está activa. Nunca se incluyen contraseñas.

Historial de llamadas: GET /history​

Con la más reciente primero, 100 entradas salvo que ?limit= diga otra cosa. ?missed=true devuelve solo las llamadas perdidas, ?declined=true solo las llamadas que este teléfono rechazó.

CampoSignificado
idEl identificador propio de la entrada del historial. No es el id de llamada de /calls ni de los webhooks; seance_id relaciona ambos.
outcomeLa clasificación principal: answered, missed, declined o failed.
answeredtrue o false.
duration_s0 para una llamada que nunca llegó a conectarse.
number, uriEl interlocutor, como número y como dirección SIP.
nameDe Contactos si el número es conocido; si no, vacío. Relacione por number, no por esto.
dialedLos dígitos marcados, en una llamada saliente; vacío en una entrante.
account, account_idLa línea en la que estuvo la llamada.
reasonCómo terminó: local-hangup, remote-hangup, cancelled…
answered_byno si contestó una persona; si no, qué contestó la llamada.

Contactos: GET /contacts​

Cada contacto tiene su id, name, number y la línea a la que pertenece, account_id y account; un account vacío significa que el contacto no está ligado a ninguna línea.

Grabaciones​

Las grabaciones y las transcripciones no se entregan como JSON. La API las sirve como páginas HTML, /ui y /ui/recordings/{id}: enlace a estas páginas desde su CRM en lugar de mover audio de un lado a otro. El enlace se abre en el ordenador que guarda la grabación, y el audio nunca sale de él.

Taxonomía y ajustes​

Cada entrada de /taxonomy tiene un code constante, un title y una description en el idioma de la interfaz, un kind (category, tag o red_flag) y, en las señales, una severity. Relacione por code, nunca por title: los títulos vienen en el idioma configurado en el teléfono. Una entrada con retired: true se conserva para que las llamadas antiguas sigan resolviéndose; ya no se asigna a llamadas nuevas. Cargue la taxonomía una vez al arrancar para relacionar las palabras del teléfono con sus propios campos.

/settings devuelve la configuración salvo los secretos: dispositivos de audio y volúmenes, prioridad de códecs, apariencia e idioma, arranque, atajos, el nivel de diagnóstico y el estado de ambas integraciones — útil para una herramienta de soporte que tenga que revisar un puesto sin compartir la pantalla. api.disabled lista los grupos de acceso apagados y webhooks.silenced los eventos apagados; listas vacías significan que todo está encendido. Nunca incluye la contraseña SIP, el token de la API ni el valor de la cabecera del webhook.

Errores​

Cada error es JSON con una sola clave error, pensada para personas, no para analizarla.

EstadoCuerpoSignificado
404{"error":"no such endpoint"}La ruta no existe, o su grupo de acceso está apagado; ambos casos dan la misma respuesta a propósito.
405{"error":"that endpoint does not take this method"}La ruta existe, pero no admite ese método: por ejemplo POST /settings en lugar de PUT.
401{"error":"writing needs a token, and none is configured"}Un punto de acceso que cambia lo guardado, en un teléfono donde el campo Token está vacío. Rellénelo en Control local.
401{"error":"this endpoint needs the authorization token"}Un punto de acceso que cambia lo guardado, sin el token correcto.
404{"error":"no contact with that id"}La ruta es correcta, el identificador no.
400{"error":"no call with that id"}La llamada ha terminado, o nunca existió.
400{"error":"a call needs a number"}POST /calls sin número. No se marcó nada.
400{"error":"no digits to send"}POST /calls/{id}/dtmf sin dígitos.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer sin destino.
400{"error":"the account this call is on is no longer set up"}La cuenta de la llamada se eliminó durante la llamada, así que el destino no se puede completar. No se envió nada a la centralita.

Las peticiones rechazadas se cuentan en api_requests_refused_total, así que una integración que falla en silencio se ve en las métricas, no solo en sus propios registros.

Métricas​

GET /metrics devuelve cada contador del teléfono, cada uno con un texto de ayuda. Recójalo con Prometheus o léalo a mano.

ContadorCuenta
calls_incoming_totalLlamadas entrantes recibidas.
calls_outgoing_totalLlamadas salientes hechas.
calls_answered_totalLlamadas que se contestaron.
calls_missed_totalLlamadas entrantes que no se contestaron.
calls_declined_totalLlamadas rechazadas aquí o por el otro lado.
calls_failed_totalLlamadas que no se pudieron establecer.
registrations_succeeded_totalRegistros SIP correctos.
registrations_failed_totalRegistros SIP rechazados o caducados.
webhooks_delivered_totalWebhooks que aceptó el receptor.
webhooks_failed_totalWebhooks rechazados o no entregados.
webhooks_dropped_totalWebhooks descartados porque la cola estaba llena.
api_requests_totalPeticiones atendidas por la API.
api_requests_refused_totalPeticiones rechazadas: token incorrecto, grupo apagado o ruta desconocida.

Actualizar una integración antigua​

Las versiones anteriores usaban nombres en camelCase e identificadores cortos. accountId es ahora account_id, startedAt es callstart_ts, durationSeconds es duration_s, answeredBy es answered_by, y el campo de webhook at es event_ts. Las llamadas y las cuentas se identifican solo por UUID: runtimeId e identificadores como call-3 o account-2 ya no se devuelven ni se aceptan.

Cuando no funciona​

SíntomaQué comprobar
Conexión rechazada en 127.0.0.1:8377El control local está apagado, el teléfono no está en marcha o se cambió el puerto.
404 {"error":"no such endpoint"} para una ruta de esta páginaSu grupo de acceso está apagado.
Leer funciona, escribir se rechaza con 401Los puntos de acceso que cambian datos guardados necesitan el token en la cabecera Authorization, y antes hay que rellenar el campo Token en el teléfono.
Los títulos de las categorías no están en inglésLos títulos siguen el idioma de la interfaz. Relacione por code de /taxonomy.
Faltan accountId, startedAt o atLa integración se escribió para los nombres anteriores; vea más arriba.

Para un problema con el registro o con la propia llamada, abra el Diagnóstico.