Centrais telefónicas e ligações
O CallerHub liga-se às centrais telefónicas de quatro formas: por consulta HTTP a cada chamada, como lista telefónica LDAP, por listas telefónicas exportadas e – para a análise – pelos registos de chamadas.
Guias passo a passo: STARFACE · 3CX · Asterisk/FreePBX · Yealink/Snom · Mitel 100 · FRITZ!Box · todas as soluções
Consulta de nome via HTTP
Cada central telefónica é ligada como interface própria, com chave de API e IPs permitidos próprios. A edição Básica permite uma interface; a Completa, até dez (mais com licença especial). Todas usam a mesma porta; o CallerHub identifica-as pela chave de API.
| Sistema ou perfil | Formato de resposta | Endereço de exemplo | Configuração | Estado |
|---|---|---|---|---|
| STARFACE | Texto | …/lookup?number= + cabeçalho X-Api-Key | através de um módulo STARFACE; módulo de exemplo CallerHub_Interface_v49.sfm incluído | testado |
| 3CX | JSON | …/lookup?format=json&apikey=…&number=[Number] | modelo de CRM gerado pelo CallerHub (“Modelo 3CX …”) | Procuram-se testers |
| Asterisk / FreePBX | Texto | …/lookup?apikey=…&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})} | plano de marcação com CURL (módulo func_curl) | Procuram-se testers |
| VitalPBX | Texto | …/lookup?apikey=…&number=[CIDNUM] | origem de consulta CID na rota de entrada | Procuram-se testers |
| Issabel (também FreePBX) | Texto | caminho /lookup, consulta format=text&apikey=…&number=[NUMBER] | CallerID Lookup Sources | Procuram-se testers |
| Yealink / Fanvil | Lista telefónica XML | …/lookup?format=yealink&apikey=…&number=#SEARCH | lista telefónica remota no telefone ou por aprovisionamento | Procuram-se testers |
| Snom | Lista telefónica XML | …/lookup?format=snom&apikey=…&number=#SEARCH | lista telefónica XML no telefone | Procuram-se testers |
| Genérico (HTTP) | Texto, JSON, XML | …/lookup?format=json&apikey=…&number=03023125017 | qualquer sistema que consiga chamar um endereço via HTTP GET a cada chamada | genérico |
Testados: a ligação STARFACE, a ligação CSTA de Mitel 100, Aastra e OpenCom, os telefones Mitel 6800/6900 e a FRITZ!Box. Os guias dos outros sistemas baseiam-se em interfaces publicadas; confirme os marcadores, os caminhos de menu e os nomes das definições na documentação da sua versão.
O seu sistema ainda não foi testado? Torne-se cliente piloto – 12 meses da edição Completa grátis.
Um cartão por central telefónica
Na página Interfaces, cada sistema tem o seu cartão com nome, estado da última consulta, chave de API, IPs permitidos e origens consultadas. “Copiar guia” fornece o guia de configuração do sistema escolhido com a chave de API real.


Exemplo Asterisk / FreePBX
exten => _X.,1,Set(CURLOPT(httptimeout)=2)
same => n,Set(CALLERID(name)=${CURL(http://192.168.10.5:8080/lookup?apikey=API-KEY&called=${EXTEN}&number=${URIENCODE(${CALLERID(num)})})})
same => n,Goto(from-pstn,${EXTEN},1)
Exemplo Yealink (aprovisionamento)
remote_phonebook.data.1.url = http://192.168.10.5:8080/lookup?format=yealink&apikey=API-KEY&number=#SEARCH
remote_phonebook.data.1.name = CallerHub
features.remote_phonebook.enable = 1
Módulo STARFACE
O STARFACE não tem consulta de nome integrada por endereço web; um módulo no Module Designer pede o nome ao CallerHub a cada chamada recebida. Para isso, importe Samples\CallerHub_Interface_v49.sfm; este módulo faz a consulta de nome. Um módulo alargado também comunica todos os eventos de uma chamada (a tocar, atendida, desligada, reencaminhada) para análise, estatísticas e vista em direto; detalhes mediante pedido ao suporte. As chamadas anónimas não são consultadas.
Lista telefónica LDAP para sistemas sem consulta HTTP
Muitas centrais telefónicas e telefones de secretária não consultam um endereço web, mas sim um diretório LDAP. Para estes, o módulo Lista telefónica oferece um diretório LDAPv3 só de leitura (porta 389, 636 com LDAPS). A pesquisa inversa de chamadas recebidas consulta todas as origens ativas, incluindo regras e listas de bloqueio e VIP.
Aparelhos típicos: Unify OpenScape Business, Auerswald COMtrexx/COMpact, Avaya J100 no IP Office, Yeastar série P, innovaphone (pesquisa inversa), Ascom IP-DECT, Grandstream UCM, pascom, Gigaset, Yealink e a família Mitel 100 (Mitel 112, 130, 150).

Servidor: nome ou IP do computador do CallerHub, porta 389 (636 com LDAPS)
Base DN: ou=callerhub
Filtro de nome: (|(cn=%)(sn=%))
Filtro de número: (|(telephoneNumber=%)(mobile=%))
Atributo exibido: cn Atributo número: telephoneNumber
As tentativas de escrita são recusadas; o StartTLS não é suportado. A ligação LDAP da família Mitel 100 está testada com o CallerHub.
Exportação da lista telefónica e FRITZ!Box
As centrais telefónicas na nuvem, como Microsoft Teams, Zoom, NFON ou Placetel, e a FRITZ!Box usam as suas próprias listas de contactos. Para estas, o CallerHub exporta as entradas de todas as listas de números (após as regras, sem números bloqueados).
| Formato | Uso |
|---|---|
| FRITZ!Box (XML) | FRITZ!Box: Telefonia → Lista telefónica → Restaurar. O número de entradas é limitado conforme o modelo. |
| vCard 3.0 (.vcf) | Outlook, Auerswald, Gigaset e muitas centrais telefónicas na nuvem |
| CSV | Excel e importação em centrais telefónicas na nuvem (p. ex. Zoom, NFON, Placetel) |
| Yealink (XML) | Lista telefónica remota para Yealink e telefones compatíveis |
Os telefones com lista telefónica remota também podem carregar a lista diretamente: /phonebook?format=yealink&key=ACCESS_KEY (formatos yealink, fritzbox, vcard, csv). Para a análise, o CallerHub lê o monitor de chamadas da FRITZ!Box na porta 1012.
Sincronizar o livro de endereços do STARFACE
Nas chamadas efetuadas, a aplicação STARFACE, o cliente web e as listas de chamadas só mostram nomes dos livros de endereços do STARFACE. Por isso, o CallerHub grava os contactos das suas listas de números num livro de endereços próprio através da API REST do STARFACE – todas as noites à hora configurada, após cada recarregamento das origens e com um clique.
- Só no próprio livro de endereços: o CallerHub cria, altera e elimina entradas apenas aí. Se uma origem estiver vazia ou tiver diminuído mais de metade, não elimina nada.
- Sem acesso de entrada: a ligação vai do CallerHub à central telefónica; com OAuth a partir do STARFACE 10.
- Grandes volumes por etapas: limites por execução e para o livro de endereços inteiro, escolha das origens.

Aprovisionar telefones Mitel (6800/6900)
O módulo de aprovisionamento entrega aos telefones Mitel as suas definições via HTTP e TFTP – extensão, conta SIP, teclas e páginas – e mostra no visor informações de chamada, pesquisa no CRM e página da equipa.
- Telefones em tabela: MAC, modelo, extensão, nome; a coluna de estado mostra quando o telefone obteve o seu ficheiro pela última vez.
- Teclas para todos: BLF, marcação rápida, correio de voz próprio, funções ou nova página – ordenadas por arrastamento.
- Página da equipa: a tecla “Team” mostra os colegas com o seu estado (em chamada, a tocar, livre); ao escolher um, marca o número.
O STARFACE Cloud não responde a subscrições BLF de telefones de terceiros; as teclas de colegas podem então ser marcações rápidas, e a página da equipa continua a mostrar o estado.
Registos de chamadas para a análise
A análise precisa dos registos detalhados (CDR) da central telefónica. Estes chegam ao CallerHub como ficheiro, em direto por uma ligação ou por API. É possível configurar até cinco recetores em direto.
| Origem | Caminho | Configuração na central telefónica |
|---|---|---|
| Asterisk / FreePBX | Ficheiro Master.csv ou em direto via AMI (o CallerHub liga-se, porta 5038) | manager.conf: utilizador com read = cdr; cdr_manager.conf: enabled = yes |
| STARFACE | Ficheiro output.csv | Admin → Relatórios → Exportar registos de chamadas |
| 3CX (v18/v20) | Socket CDR ativo (o CallerHub escuta, p. ex. porta 5100) ou passivo; exportação CSV | Admin → Settings → CDR |
| 3CX V20 (nuvem ou local) | API: o CallerHub consulta a XAPI | Integrações → API: cliente com acesso XAPI |
| Microsoft Teams Phone | API: Microsoft Graph, permissão CallRecords.Read.All | Registo de aplicação no Microsoft Entra ID |
| Webex Calling | API: analytics.webexapis.com, scope spark-admin:calling_cdr_read | Control Hub: função “Detailed Call History API access” |
| Mitel MiVoice Office 400 | SMDR no formato PC5, o CallerHub liga-se (porta 1080) | Saída dos registos via TCP |
| Unify OpenScape Business | Dados de tarifação via LAN, o CallerHub escuta (p. ex. porta 5101) | Cliente TCP para endereço:porta do CallerHub |
| innovaphone | TCP ou HTTP /cdr | Gateway → CDR0 |
| FRITZ!Box | Monitor de chamadas, o CallerHub liga-se (porta 1012) | marcar uma vez #96*5* num telefone |
| Placetel | HTTP /event | API Notify com o endereço do CallerHub |
| sipgate.io | HTTP /event | URL para chamadas recebidas e efetuadas |
| Qualquer sistema ou script | HTTP ou ficheiro CSV na pasta CallData | detalhes mediante pedido ao suporte |
Configuração em cinco passos
- Em Interfaces, adicione uma interface, escolha a central telefónica e indique um nome.
- Em “IPs permitidos”, indique o endereço do sistema ou a rede dos telefones, p. ex.
192.168.10.20ou192.168.20.0/24. - Verifique as origens consultadas e escolha “Guardar e aplicar”.
- Teste no browser de um computador da mesma rede:
http://192.168.10.5:8080/lookup?apikey=API-KEY&number=040 66969000devolve o nome. - Configure a central telefónica conforme o guia e faça uma chamada de teste. A consulta aparece no ecrã inicial em “Consultas recentes”.

Erros de ligação comuns
| Sintoma | Causa e solução |
|---|---|
| Nenhuma entrada em “Consultas recentes”, estado “À espera de consultas” | A consulta não chega ao CallerHub. Verifique o endereço na central telefónica (IP, porta, http/https), a firewall do Windows e as firewalls entre redes. |
status=401 | Chave de API errada ou em falta. Copie novamente o guia; uma chave gerada de novo também tem de ser substituída na central telefónica. |
status=403 | O endereço de origem não está entre os IPs permitidos. Atrás de NAT ou de um proxy inverso, a origem é outra. |
status=429 | Demasiadas chaves erradas a partir deste endereço. Aguarde o fim do bloqueio (5 minutos por predefinição). |
| A consulta chega, mas sem nome | Número desconhecido, format errado para o sistema, ou o tempo limite do sistema é inferior ao tempo de resposta. |
| O HTTPS falha | O sistema não confia no certificado ou o nome não corresponde. Importe o certificado raiz no sistema. |
| Acentos errados ou nome cortado | As respostas são UTF-8; verifique o conjunto de carateres do sistema. Defina o tamanho máximo do nome em Administração → Avançado. |
Se a causa continuar pouco clara, “Resolução de problemas → Iniciar gravação alargada …” regista cada consulta com todos os cabeçalhos (chaves mascaradas). O simulador integrado testa uma configuração sem que uma central telefónica real ligue.