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.
- Encienda Dejar que otros programas de este ordenador manejen el teléfono. El servidor arranca al momento.
- Mantenga el Puerto por defecto,
8377, salvo que otro programa ya lo use. - Opcionalmente, ponga un Token. Una vez guardado, el campo muestra Guardado — escriba para reemplazarlo.
- 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.
- 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 responden401. 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.
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étodo | Ruta | Hace |
|---|---|---|
| GET | /metrics | Los contadores, en formato Prometheus. |
| GET | /ui | La 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}/audio | El audio de la página anterior. |
| GET | /contacts | Los contactos. |
| GET | /contacts/{id} | Un solo contacto. |
| GET | /history | El historial de llamadas, con la más reciente primero. Admite ?limit=, ?missed=true y ?declined=true. |
| GET | /calls | Las llamadas en curso. |
| POST | /calls | Hace una llamada: {"number": "...", "account_id": "..."}. |
| POST | /calls/{id}/answer | Contesta una llamada. |
| POST | /calls/{id}/hangup | Cuelga una llamada. |
| POST | /calls/{id}/hold | Pone una llamada en espera. |
| POST | /calls/{id}/resume | La saca de la espera. |
| POST | /calls/{id}/dtmf | Envía tonos: {"digits": "..."}. |
| POST | /calls/{id}/transfer | Transfiere la llamada: {"target": "..."}. |
| GET | /accounts | Las cuentas SIP y su estado de registro. Nunca una contraseña. |
| GET | /settings | Toda la configuración, sin los secretos. |
| GET | /taxonomy | Categorí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étodo | Ruta | Hace |
|---|---|---|
| POST | /contacts | Añ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 | /history | Olvida 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 | /settings | Sustituye 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" }
numberes obligatorio. Sin él, la respuesta es400 {"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:
1020se envía comosip:1020@pbx.example.com.POST /calls/{id}/transfercompleta sutargetdel mismo modo; un destino que ya tiene esquema o@se envía tal cual. account_ides opcional; tómelo deGET /accounts. Sin él, la llamada sale por la cuenta seleccionada en la ventana principal.- Use el
iden/calls/{id}/…:hangup,hold,resume,dtmfytransfer. Los webhooks de esta llamada llevan el mismoid.
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.
stateesdialing,ringing-out,ringing-in,active,hold(en espera puesta por este teléfono),onhold(en espera puesta por el interlocutor),conferenceoended. Cuando se aplica más de uno,conferencegana ahold, yholdaonhold.muteddice si el micrófono está silenciado en la llamada; silenciar no cambiastate.seance_ides la conversación: las llamadas enlazadas por una transferencia, una consulta o una conferencia lo comparten.event_tses cuándo se generó la respuesta. Compárelo concallstate_tspara 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ó.
| Campo | Significado |
|---|---|
id | El identificador propio de la entrada del historial. No es el id de llamada de /calls ni de los webhooks; seance_id relaciona ambos. |
outcome | La clasificación principal: answered, missed, declined o failed. |
answered | true o false. |
duration_s | 0 para una llamada que nunca llegó a conectarse. |
number, uri | El interlocutor, como número y como dirección SIP. |
name | De Contactos si el número es conocido; si no, vacío. Relacione por number, no por esto. |
dialed | Los dígitos marcados, en una llamada saliente; vacío en una entrante. |
account, account_id | La línea en la que estuvo la llamada. |
reason | Cómo terminó: local-hangup, remote-hangup, cancelled… |
answered_by | no 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.
| Estado | Cuerpo | Significado |
|---|---|---|
| 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.
| Contador | Cuenta |
|---|---|
calls_incoming_total | Llamadas entrantes recibidas. |
calls_outgoing_total | Llamadas salientes hechas. |
calls_answered_total | Llamadas que se contestaron. |
calls_missed_total | Llamadas entrantes que no se contestaron. |
calls_declined_total | Llamadas rechazadas aquí o por el otro lado. |
calls_failed_total | Llamadas que no se pudieron establecer. |
registrations_succeeded_total | Registros SIP correctos. |
registrations_failed_total | Registros SIP rechazados o caducados. |
webhooks_delivered_total | Webhooks que aceptó el receptor. |
webhooks_failed_total | Webhooks rechazados o no entregados. |
webhooks_dropped_total | Webhooks descartados porque la cola estaba llena. |
api_requests_total | Peticiones atendidas por la API. |
api_requests_refused_total | Peticiones 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íntoma | Qué comprobar |
|---|---|
Conexión rechazada en 127.0.0.1:8377 | El 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ágina | Su grupo de acceso está apagado. |
Leer funciona, escribir se rechaza con 401 | Los 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és | Los títulos siguen el idioma de la interfaz. Relacione por code de /taxonomy. |
Faltan accountId, startedAt o at | La 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.