API REST local
O AI Softphone tem uma API REST para integração CTI: um programa no mesmo computador pode fazer e controlar chamadas, ler os contactos, o registo de chamadas e as contas SIP, e acompanhar as chamadas em curso. Sem SDK, sem intermediário na nuvem e sem nenhum serviço à escuta exposto à rede. Os pedidos e as respostas são JSON, por isso basta o curl ou qualquer cliente HTTP.
A API está desligada depois da instalação; nada está à escuta até a ligar. Depois, só escuta na interface de loopback — uma pequena interface web que só responde a este computador — e não pode ser alcançada a partir da rede do escritório, de uma VPN ou de outra máquina.
Use a API quando o seu programa precisar de dados do telefone ou tiver de controlar uma chamada. Use os webhooks quando tiver de reagir às chamadas à medida que acontecem, sem consultar repetidamente. A maioria das integrações usa os dois; são independentes um do outro.
Ligá-la
Abra Definições → Integração e vá a Controlo local.
- Ligue Deixar outros programas deste computador conduzir o telefone. O servidor arranca de imediato.
- Mantenha a Porta por omissão,
8377, a não ser que outro programa já a use. - Opcionalmente, defina um Código. Depois de guardado, o campo mostra Guardado — escreva para o substituir.
- Em Acesso, escolha os grupos a abrir: Contactos, Registo de chamadas, As chamadas e o seu controlo, Contas, Definições, Contadores (as métricas). Um grupo desligado não é filtrado: simplesmente não é servido.
- Teste-a:
curl http://127.0.0.1:8377/accounts. Se a resposta for JSON, a API funciona.
Não é instalado nenhum serviço à parte e não é preciso reiniciar. A parte do programa que faz isto pode ser desligada em Módulos (Integração).
A própria página da API
Abrir a própria página da API abre http://127.0.0.1:8377 num navegador. O endereço responde com uma lista de tudo o que serve, em inglês; os endereços que leem algo são ligações que pode seguir.
O acesso e o código
O que um programa pode fazer depende de mudar dados guardados ou não, e não de ler:
- Sem código, qualquer programa do computador pode ler tudo nos grupos ligados e controlar chamadas: fazer, atender, desligar, pôr em espera, retomar, transferir e enviar DTMF.
- Com o código no cabeçalho
Authorization, pode também usar os pontos de acesso que mudam o que está guardado. Sem o código, esses pontos de acesso não aparecem na própria página da API e respondem401. Sem nenhum código definido, nada pode mudar o que está guardado.
O código é guardado no porta-chaves do computador, não no ficheiro de definições, e nunca é devolvido por /settings.
Sem código, qualquer programa a correr neste computador pode controlar o telefone, incluindo atender chamadas. Num posto pessoal isso costuma ser aceitável. Numa máquina partilhada ou gerida, defina um código e trate-o como qualquer outra palavra-passe. O código protege só os pedidos que alteram dados guardados, não as chamadas: para manter outros programas longe das chamadas, desligue As chamadas e o seu controlo em Acesso.
Pontos de acesso
O endereço base é http://127.0.0.1:8377. Os pontos de acesso abaixo não precisam de código.
| Método | Caminho | Faz |
|---|---|---|
| GET | /metrics | Os contadores, em formato Prometheus. |
| GET | /ui | A lista de gravações, como página HTML. |
| GET | /ui/recordings/{id} | Uma gravação com a sua transcrição, como página HTML. |
| GET | /ui/recordings/{id}/audio | O áudio da página acima. |
| GET | /contacts | Os contactos. |
| GET | /contacts/{id} | Um único contacto. |
| GET | /history | O registo de chamadas, da mais recente para a mais antiga. Aceita ?limit=, ?missed=true e ?declined=true. |
| GET | /calls | As chamadas em curso. |
| POST | /calls | Faz uma chamada: {"number": "...", "account_id": "..."}. |
| POST | /calls/{id}/answer | Atende uma chamada. |
| POST | /calls/{id}/hangup | Desliga uma chamada. |
| POST | /calls/{id}/hold | Põe uma chamada em espera. |
| POST | /calls/{id}/resume | Tira-a da espera. |
| POST | /calls/{id}/dtmf | Envia tons: {"digits": "..."}. |
| POST | /calls/{id}/transfer | Transfere a chamada: {"target": "..."}. |
| GET | /accounts | As contas SIP e o seu estado de registo. Nunca uma palavra-passe. |
| GET | /settings | Toda a configuração, sem os segredos. |
| GET | /taxonomy | Categorias, etiquetas e sinais, com os seus códigos. |
Pontos de acesso que pedem o código
Mudam o que está guardado, por isso cada pedido tem de levar o código no cabeçalho Authorization. A própria página da API só os mostra a um pedido que o leve.
| Método | Caminho | Faz |
|---|---|---|
| POST | /contacts | Adiciona um contacto: {"name": "...", "number": "...", "account_id": "..."}; account_id é opcional. |
| PUT | /contacts/{id} | Substitui um contacto. |
| DELETE | /contacts/{id} | Remove um contacto. |
| DELETE | /history/{id} | Esquece uma chamada do registo de chamadas. |
| DELETE | /history | Esquece todo o registo de chamadas. Não pode ser desfeito. |
| PUT | /accounts/{id} | Substitui as definições de uma conta. A palavra-passe não está entre elas. |
| PUT | /settings | Substitui as definições. |
Cada identificador é um UUID emitido pelo telefone: o id de uma chamada vem de /calls ou da resposta a POST /calls, o id de uma conta de /accounts.
Os nomes dos campos estão em snake_case e o final indica o tipo: _id é uma referência a um UUID, _ts é um momento em milissegundos Unix (UTC), _s é uma duração em segundos. O mesmo vale para os webhooks; só /settings mantém nomes próprios. Na API REST estes valores são números JSON, e um momento desconhecido é null.
Exemplo: fazer uma chamada
POST /calls faz uma chamada a sair. O corpo é JSON com o number a marcar e, opcionalmente, o account_id da conta de onde ligar:
curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'
A resposta é o identificador da nova chamada:
{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
- O
numberé obrigatório. Sem ele, a resposta é400 {"error":"a call needs a number"}e nada é marcado. - O número é completado na conta escolhida tal como o marcador o completa:
1020é enviado comosip:1020@pbx.example.com.POST /calls/{id}/transfercompleta o seutargetda mesma maneira; um destino que já tenha um esquema ou um@é enviado tal como está. - O
account_idé opcional; obtenha-o emGET /accounts. Sem ele, a chamada sai pela conta selecionada na janela principal. - Use o
idem/calls/{id}/…:hangup,hold,resume,dtmfetransfer. Os webhooks desta chamada levam o mesmoid.
A partir de uma página web: clicar para ligar
Uma página que chama 127.0.0.1 chega ao computador em que o navegador corre — o mesmo em que corre o telefone —, por isso um botão de clicar para ligar num CRM não precisa de servidor próprio:
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);
}
O que as respostas contêm
Chamadas em curso: GET /calls
Cada chamada tem o seu id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts e callstate_ts.
- O
stateédialing,ringing-out,ringing-in,active,hold(em espera por este telefone),onhold(em espera pelo interlocutor),conferenceouended. Quando se aplica mais do que um,conferencesobrepõe-se ahold, eholdaonhold. - O
muteddiz se o microfone está silenciado na chamada; silenciar não muda ostate. - O
seance_idé a conversa: as chamadas ligadas por uma transferência, uma consulta ou uma conferência partilham-no. - O
event_tsé quando a resposta foi gerada. Compare-o com ocallstate_tspara ver há quanto tempo a chamada está no seu estado, sem depender do seu próprio relógio.
Contas: GET /accounts
Cada conta tem o seu id (o account_id em todo o lado), as suas definições — transport (udp, tcp ou tls), port, registrar, outbound_proxy, expiry_s e outras —, se está enabled, e o seu state na central: registered enquanto a linha está ativa. As palavras-passe nunca são incluídas.
Registo de chamadas: GET /history
Da mais recente para a mais antiga, 100 entradas a não ser que ?limit= diga outra coisa. ?missed=true devolve só as chamadas perdidas, ?declined=true só as chamadas que este telefone recusou.
| Campo | Significado |
|---|---|
id | O identificador próprio da entrada do histórico. Não é o id de chamada de /calls e dos webhooks; o seance_id liga os dois. |
outcome | A classificação principal: answered, missed, declined ou failed. |
answered | true ou false. |
duration_s | 0 para uma chamada que nunca chegou a ser estabelecida. |
number, uri | O interlocutor, como número e como endereço SIP. |
name | Dos Contactos se o número for conhecido, senão vazio. Faça corresponder pelo number, não por este. |
dialed | Os dígitos marcados, numa chamada a sair; vazio numa a entrar. |
account, account_id | A linha em que a chamada esteve. |
reason | Como terminou: local-hangup, remote-hangup, cancelled… |
answered_by | no se foi uma pessoa a atender; caso contrário, o que atendeu a chamada. |
Contactos: GET /contacts
Cada contacto tem o seu id, name, number e a linha a que pertence, account_id e account; um account vazio significa que o contacto não está associado a nenhuma linha.
Gravações
As gravações e as transcrições não são dadas em JSON. A API serve-as como páginas HTML, /ui e /ui/recordings/{id}: no seu CRM, ponha ligações para estas páginas em vez de andar a mover áudio. A ligação abre no computador que guarda a gravação, e o áudio nunca sai dele.
Taxonomia e definições
Cada entrada de /taxonomy tem um code constante, um title e uma description na língua da interface, um kind (category, tag ou red_flag) e, para os sinais, uma severity. Faça corresponder pelo code, nunca pelo title: os títulos vêm na língua definida no telefone. Uma entrada com retired: true é mantida para que as chamadas antigas continuem a resolver-se; já não é atribuída a chamadas novas. Carregue a taxonomia uma vez no arranque para fazer corresponder as palavras do telefone aos seus próprios campos.
/settings devolve a configuração exceto os segredos: dispositivos de áudio e volumes, prioridade dos codecs, aspeto e língua, arranque, atalhos, o nível de diagnóstico e o estado de ambas as integrações — útil para uma ferramenta de apoio que tenha de verificar um posto sem partilhar o ecrã. api.disabled lista os grupos de acesso desligados e webhooks.silenced os eventos desligados; listas vazias significam que está tudo ligado. Nunca inclui a palavra-passe SIP, o código da API nem o valor do cabeçalho do webhook.
Erros
Cada erro é JSON com uma única chave error, pensada para pessoas, não para ser analisada.
| Estado | Corpo | Significado |
|---|---|---|
| 404 | {"error":"no such endpoint"} | O caminho não existe, ou o seu grupo de acesso está desligado; ambos dão de propósito a mesma resposta. |
| 405 | {"error":"that endpoint does not take this method"} | O caminho existe, mas não aceita este método: por exemplo POST /settings em vez de PUT. |
| 401 | {"error":"writing needs a token, and none is configured"} | Um ponto de acesso que muda o que está guardado, num telefone onde o campo Código está vazio. Preencha-o em Controlo local. |
| 401 | {"error":"this endpoint needs the authorization token"} | Um ponto de acesso que muda o que está guardado, sem o código certo. |
| 404 | {"error":"no contact with that id"} | O caminho está certo, o identificador não. |
| 400 | {"error":"no call with that id"} | A chamada terminou, ou nunca existiu. |
| 400 | {"error":"a call needs a number"} | POST /calls sem número. Nada foi marcado. |
| 400 | {"error":"no digits to send"} | POST /calls/{id}/dtmf sem dígitos. |
| 400 | {"error":"a transfer needs a target"} | POST /calls/{id}/transfer sem destino. |
| 400 | {"error":"the account this call is on is no longer set up"} | A conta da chamada foi removida durante a chamada, por isso o destino não pode ser completado. Nada foi enviado à central. |
Os pedidos recusados são contados em api_requests_refused_total, por isso uma integração que falha em silêncio aparece nas métricas, e não só nos seus próprios registos.
Métricas
GET /metrics devolve todos os contadores do telefone, cada um com um texto de ajuda. Recolha-os com o Prometheus ou leia-os à mão.
| Contador | Conta |
|---|---|
calls_incoming_total | Chamadas a entrar recebidas. |
calls_outgoing_total | Chamadas a sair feitas. |
calls_answered_total | Chamadas que foram atendidas. |
calls_missed_total | Chamadas a entrar que não foram atendidas. |
calls_declined_total | Chamadas recusadas aqui ou pelo outro lado. |
calls_failed_total | Chamadas que não foi possível estabelecer. |
registrations_succeeded_total | Registos SIP bem-sucedidos. |
registrations_failed_total | Registos SIP recusados ou expirados. |
webhooks_delivered_total | Webhooks aceites pelo recetor. |
webhooks_failed_total | Webhooks recusados ou não entregues. |
webhooks_dropped_total | Webhooks descartados porque a fila estava cheia. |
api_requests_total | Pedidos tratados pela API. |
api_requests_refused_total | Pedidos recusados: código errado, grupo desligado ou caminho desconhecido. |
Atualizar uma integração antiga
As versões anteriores usavam nomes em camelCase e identificadores curtos. accountId passou a account_id, startedAt a callstart_ts, durationSeconds a duration_s, answeredBy a answered_by, e o campo de webhook at a event_ts. As chamadas e as contas são identificadas só por UUID: runtimeId e identificadores como call-3 ou account-2 já não são devolvidos nem aceites.
Quando não funciona
| Sintoma | O que verificar |
|---|---|
Ligação recusada em 127.0.0.1:8377 | O controlo local está desligado, o telefone não está a funcionar, ou a porta foi mudada. |
404 {"error":"no such endpoint"} para um caminho desta página | O seu grupo de acesso está desligado. |
Ler funciona, escrever é recusado com 401 | Os pontos de acesso que mudam dados guardados pedem o código no cabeçalho Authorization, e o campo Código do telefone tem de ser preenchido primeiro. |
| Os títulos das categorias não estão em inglês | Os títulos seguem a língua da interface. Faça corresponder pelo code de /taxonomy. |
Faltam accountId, startedAt ou at | A integração foi escrita para os nomes antigos; veja acima. |
Para um problema de registo ou da própria chamada, abra o Diagnóstico.