Crie Seu Próprio Aplicativo de Voz com IA Usando os Ramais Programáveis 3CX

Conecte um aplicativo de voz com IA hospedado externamente ao 3CX usando a API de Controle de Chamadas, o SDK de Controle de Chamadas e um provedor de IA em tempo real compatível.

Introdução

Os Ramais Programáveis do 3CX permitem que um aplicativo hospedado externamente se conecte ao PABX e funcione como um ramal nativo. O aplicativo pode receber chamadas, transmitir áudio em ambas as direções e controlar o encaminhamento de chamadas por meio da API de Controle de Chamadas do 3CX.

Os exemplos do Controle de Chamadas por Agente oferecem aplicativos Node.js funcionais para:

• OpenAI Realtime
• Google Gemini ao vivo
• Voz xAI Grok
• Alibaba Cloud Qwen Omni Realtime

Cada exemplo utiliza uma única sessão de áudio bidirecional em tempo real. O reconhecimento de fala, o raciocínio e a geração de fala são gerenciados pelo provedor de IA selecionado, enquanto a 3CX continua a fornecer os serviços de telefonia, encaminhamento de chamadas, ramais, troncos SIP e números DID.

Os exemplos se conectam por meio das APIs publicadas do 3CX e não exigem alterações no código-fonte do PABX. Eles também se conectam ao endpoint do 3CX MCP para que o aplicativo de voz possa utilizar ferramentas autorizadas do PABX, como a consulta à lista telefônica. Servidores MCP externos opcionais podem ser adicionados a calendários, CRMs e outros sistemas empresariais.

Qual opção devo usar?

Este guia aborda os Ramais Programáveis, nos quais o aplicativo é executado fora do 3CX, em uma infraestrutura gerenciada por você. Para uma solução pronta para configuração, utilize os Agentes de IA integrados ao 3CX. Para aplicativos personalizados que são executados diretamente no Servidor 3CX, utilize os Scripts de Chamada com IA.

O que Você Vai Construir

Ao final deste guia, você terá um aplicativo de voz com IA externa capaz de:

• Receber chamadas internas por meio do seu ID de Cliente 3CX.
• Receber chamadas externas por meio de um número DID atribuído.
• Faça uma conversa por voz em tempo real usando o provedor de IA que você escolheu.
• Pesquise na lista telefônica do 3CX por meio do MCP.
• Transfira uma chamada, encaminhe-a para o correio de voz ou encerre-a por meio do Controle de Chamadas 3CX.
• Conecte-se a servidores MCP adicionais e disponibilize as ferramentas selecionadas para o modelo.

O perfil de agente fornecido implementa um fluxo básico de atendimento. Ele serve como ponto de partida e pode ser ampliado para agendamento de consultas, informações ao cliente, pesquisas, serviços de suporte interno e outros fluxos de trabalho.

Antes de Começar

Você precisa de:

• Um sistema 3CX V20 Update 10 com acesso à API de Controle de Chamadas.
• Acesso de Administrador para criar uma Entidade de Serviço de API.
• Node.js 20 ou versão posterior no computador ou servidor que hospedará o aplicativo.
• A versão do Yarn incluída no repositório.
• Uma chave de API e uma cota disponível para pelo menos um provedor de IA compatível.
• Acesso à rede do host do aplicativo ao FQDN HTTPS do 3CX e aos endpoints WebSocket do provedor selecionado.

Etapa 1: Baixe os Exemplos

Clone ou baixe o repositório Agentic Call Control: Abra o repositório Github do Agentic Call Control

Em um terminal, acesse a raiz do repositório e instale todas as dependências da área de trabalho:

yarn install



Se o comando `yarn` não estiver disponível, habilite primeiro o Corepack:

corepack enable

yarn install



Não execute a instalação do Yarn separadamente em cada diretório do provedor. O repositório é um espaço de trabalho do Yarn e deve ser instalado a partir de sua raiz.

Etapa 2: Criar uma Entidade de Serviço 3CX

Crie as credenciais que o aplicativo externo utilizará para se autenticar no PABX.

• Faça login no Cliente Web 3CX e abra Admin.
• Acesse Integrações > API.
• Clique em Adicionar para criar uma Entidade de Serviço.
• Digite um ID de Cliente, por exemplo, ai-receptionist. Esse valor se tornará o appId do aplicativo e o número interno que os usuários poderão discar para ligar para o aplicativo.
• Habilite o acesso à API de Controle de Chamadas do 3CX para o aplicativo.
• Opcionalmente, atribua um DID caso os chamadores externos precisem alcançá-lo diretamente.
• Opcionalmente, selecione os ramais que o aplicativo tem permissão para monitorar ou controlar. Conceda apenas o acesso necessário para o fluxo de trabalho pretendido.
• Salve o Entidade de Serviço.
• Copie imediatamente a chave de API ou o Segredo do Cliente gerado. Ele será usado como appSecret e será exibido apenas uma vez.

Etapa 3: Escolha um Provedor de IA

Use um dos exemplos incluídos.

Crie a chave de API no console do provedor selecionado e guarde-a em local seguro:

• Chaves de API da OpenAI
• Chaves de API do Google AI Studio
• Console xAI
• Console do DashScope da Alibaba Cloud

Para obter informações sobre a disponibilidade atual dos modelos, vozes, regiões, preços e limites de taxa, consulte a documentação do provedor selecionado e o arquivo README no diretório de exemplos correspondente.

Observação sobre a região do Qwen: as credenciais e os endpoints do DashScope são específicos para cada região. Utilize o endpoint correspondente à região e ao espaço de trabalho em que a chave de API foi criada.

Etapa 4: Criar a Configuração do Provedor

Copie o arquivo config.yaml.example para config.yaml no diretório de exemplo selecionado.

OpenAI

cp examples/openai-realtime/config.yaml.example examples/openai-realtime/config.yaml

Gemini

cp examples/gemini-realtime/config.yaml.example examples/gemini-realtime/config.yaml

xAI

cp examples/xai-realtime/config.yaml.example examples/xai-realtime/config.yaml

Alibaba Qwen

cp examples/alibaba-qwen-realtime/config.yaml.example examples/alibaba-qwen-realtime/config.yaml



No Windows PowerShell, use o comando `Copy-Item` em vez de `cp`.

Abra o novo arquivo config.yaml e insira os valores comuns do 3CX:

appId: ai-receptionist

appSecret: your-3cx-api-key

pbxBase: https://your-pbx.example.com

companyName: Your Company

agentName: Assistant

initialGreeting: Thank you for calling. How can I help you today?



Mantenha o valor de `agentProfile` fornecido pelo exemplo selecionado. O OpenAI, o Gemini e o xAI utilizam o perfil “receptionist”; o Qwen inclui perfis separados em inglês e chinês.

Em seguida, defina as credenciais para o provedor selecionado. Por exemplo, a configuração do OpenAI contém:

openaiApiKey: sk-your-openai-api-key



Utilize o arquivo config.yaml.example fornecido pelo provedor como referência oficial para as configurações do modelo, da voz, da detecção de atividade de voz e das configurações específicas do provedor. Para o Qwen, mantenha a configuração da URL base específica da região fornecida pelo provedor.

Segurança: o arquivo config.yaml contém segredos. Ele está excluído pelo arquivo .gitignore fornecido, mas você deve evitar compartilhá-lo, submetê-lo ao controle de versão ou incluí-lo em registros de suporte. Use um gerenciador de segredos ou um método de implantação baseado em ambiente para a produção.

Etapa 5: Iniciar o Aplicativo

Execute o comando correspondente ao provedor selecionado a partir da raiz do repositório.

OpenAI

yarn start:openai

Gemini

yarn start:gemini

xAI

yarn start:xai

Alibaba Qwen

yarn start:alibaba-qwen



A saída exata da inicialização varia de acordo com o provedor. Uma inicialização bem-sucedida deve confirmar que:

• O aplicativo foi autenticado no 3CX.
• O SDK de Controle de Chamadas e a conexão WebSocket estão ativos.
• O aplicativo se conectou ao terminal 3CX MCP.
• As ferramentas MCP ativadas foram carregadas.
• O processador de chamadas é inicializado e o aplicativo está pronto para receber chamadas.

Etapa 6: Chamar e Testar o Aplicativo

Fazer uma Chamada Interna

A partir de um ramal 3CX registrado, disque o ID do Cliente da Entidade de Serviço configurado como appId.

Por exemplo, se o ID do cliente for ai-receptionist, disque ai-receptionist a partir do Cliente Web 3CX, do aplicativo para desktop, do aplicativo móvel ou de um telefone configurado.

Fazer uma Chamada Externa

Se você atribuiu um DID à Entidade de Serviço, ligue para esse número de um telefone externo.

Testes Sugeridos

Teste o fluxo de trabalho completo antes de personalizá-lo:

• Verifique se o agente responde com a saudação configurada.
• Peça para falar com alguém cujo nome conste na lista telefônica.
• Confirme se o agente consulta a lista telefônica por meio do MCP.
• Teste uma transferência bem-sucedida.
• Teste o caminho para usuários indisponíveis e para o correio de voz.
• Interrompa o agente enquanto ele estiver falando para verificar o comportamento de intrometer-se.
• Encerre a chamada e confirme se o aplicativo encerra a chamada corretamente.

Encerre o aplicativo com Ctrl+C.

Personalizar o Agente

As configurações básicas, como o nome da empresa e o nome do agente, são armazenadas no arquivo config.yaml.

O comportamento mais detalhado é definido pelo perfil YAML no diretório “agents” do exemplo selecionado. Dependendo do exemplo do provedor, o perfil padrão é chamado de receptionist.yaml

O perfil controla áreas como:

• A função e o prompt do sistema.
• Saudações e comportamento linguístico.
• Requisitos para triagem de chamadas.
• Verificações de disponibilidade antes da transferência.
• Ações permitidas na chamada.
• Ramais bloqueados.
• Spam, hostilidade e políticas de atendimento que não promovem a colaboração.
• As ferramentas do MCP disponibilizadas para o modelo.

Reinicie o aplicativo após alterar o arquivo config.yaml ou o perfil do agente selecionado.

Mantenha as instruções e as permissões das ferramentas alinhadas. Informar ao modelo que ele pode realizar uma ação não concede ao aplicativo subjacente ou à Entidade de Serviço permissão para realizá-la.

Use as Ferramentas MCP do 3CX

Ao iniciar, os exemplos se conectam ao endpoint do 3CX MCP e identificam as ferramentas disponíveis para a Entidade de Serviço autenticada.

Apenas as ferramentas listadas na lista de permissões mcpTools do perfil do agente são disponibilizadas ao modelo de IA. O perfil padrão de recepcionista permite a consulta da lista telefônica:

mcpTools:

  - list_phonebook



O log de inicialização mostra as ferramentas detectadas no servidor e se cada uma delas está ativada. Para habilitar outra ferramenta autorizada, adicione seu nome exato ao mcpTools e reinicie o aplicativo.

Restrinja a lista ao menor conjunto de ferramentas exigido pelo fluxo de trabalho. Uma ferramenta que não esteja exposta ao modelo não pode ser chamada por ele.

Conectar Servidores MCP Adicionais

Os servidores MCP personalizados podem ser locais ou remotos. Qualquer servidor que utilize o protocolo HTTP Streamable MCP e exponha ferramentas incluídas na lista de permissões do seu perfil de agente pode ser conectado por meio de customMcpServers.

Os exemplos suportam auth.type: bearer ou none para facilitar os testes. Para um teste rápido sem precisar executar seu próprio servidor MCP, use um agregador MCP hospedado, como o Smithery AI ou o Zapier. Crie uma conta e cole a URL remota e o token bearer em customMcpServers; em seguida, habilite os nomes das ferramentas detectadas em mcpTools.

customMcpServers:

  - name: GoogleCalendar

    url: https://mcp.example.com/your-server

    auth:

      type: bearer

      token: your-mcp-bearer-token

    enabled: true



Adicione cada ferramenta que você deseja disponibilizar ao perfil do agente usando seu nome exato:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add



As ferramentas detectadas em servidores MCP personalizados são integradas às ferramentas disponíveis no MCP do 3CX, mas a lista de permissões do perfil continua determinando quais ferramentas o modelo pode utilizar.

Ao adicionar servidores MCP externos:

• Utilize credenciais com o mínimo de privilégios.
• Mostre apenas as ferramentas necessárias.
• Validar os parâmetros da ferramenta no lado do servidor.
• Exija aprovação para operações delicadas ou irreversíveis, quando for o caso.
• Não coloque segredos de produção de longa duração diretamente no controle de código-fonte.

Indo Além do Exemplo de Recepcionista

A lógica de recepcionista incluída demonstra a pesquisa na lista telefônica, o encaminhamento de chamadas, o uso do correio de voz e o encerramento de chamadas. A mesma arquitetura pode ser ampliada para oferecer suporte a fluxos de trabalho como:

• Agendamento de consultas.
• Consulta de informações sobre clientes ou contas.
• Pesquisas automatizadas.
• Serviços de suporte interno de TI ou RH.
• Criação e atualização de tíquetes no CRM.
• Serviços de acompanhamento de pedidos ou informações sobre entrega.
• Interfaces de voz para aplicativos empresariais personalizados.

O aplicativo continua sendo responsável pela lógica de negócios, validação, tratamento de erros e segurança da ferramenta. O 3CX fornece a conexão de chamadas, o streaming de áudio e as funções de controle de chamadas, enquanto o provedor de IA selecionado lida com a conversa em tempo real.

Lista de Verificação de Produção

Antes de levar um aplicativo personalizado para além da fase de testes:

• Execute-o como um serviço gerenciado, com reinício automático e monitoramento de integridade.
• Proteja as credenciais da API com um gerenciador de segredos e faça a rotação delas periodicamente.
• Restrinja a Entidade de Serviço aos ramais e às funções necessárias.
• Analise as políticas de processamento de dados, retenção e disponibilidade regional do provedor de IA.
• Informe os interlocutores e obtenha o consentimento nos casos em que for necessária a gravação, a transcrição ou a divulgação por meio de IA.
• Monitore o uso dos provedores, os limites de taxa e os custos.
• Adicionar tempos limite, tratamento de novas tentativas e um encaminhamento alternativo que não envolva IA.
• Teste os caminhos de transferência, correio de voz, falhas e desconexão em condições reais de chamada.
• Analise todas as ferramentas do MCP ativadas e proteja as ações confidenciais com validação ou aprovação adicional.

Solução de Problemas

Yarn Não É Reconhecido

Certifique-se de que o Node.js 20 ou uma versão posterior esteja instalado e, em seguida, habilite o Corepack:

corepack enable



Execute o comando `yarn install` novamente a partir da raiz do repositório.

A Autenticação do PABX Retorna 401 ou 403

Verifique se appId, appSecret e pbxBase correspondem à Entidade de Serviço. Confirme se o acesso à API de Controle de Chamadas está habilitado e se a licença e as permissões do 3CX permitem a operação solicitada.

O Aplicativo Inicia, mas Não Recebe Chamadas

Confirme se o aplicativo ainda está em execução, disque o ID do cliente correto e verifique se o DID está atribuído à Entidade de Serviço ao testar chamadas externas.

Uma Ferramenta MCP Aparece como Desativada

Copie o nome exato da ferramenta exibido no log de inicialização para a lista mcpTools do perfil e, em seguida, reinicie o aplicativo. Verifique também se a Entidade de Serviço está autorizada a usar a ferramenta.

Falha nas Transferências ou na Caixa Postal

Verifique se o destino é válido e acessível à Entidade de Serviço. Se a triagem de chamadas estiver ativada no perfil, confirme se os campos de triagem necessários foram coletados antes da tentativa de transferência.

O Provedor de IA Rejeita a Conexão

Verifique a chave da API, o faturamento da conta, o acesso ao modelo, a região, a cota e a conectividade do WebSocket. No caso do Qwen, confirme se a chave da API e o endpoint pertencem à mesma região e ao mesmo espaço de trabalho.

O Áudio Está Atrasado ou o Atendente É Frequentemente Interrompido

Verifique a latência da rede e a perda de pacotes entre o host do aplicativo, o 3CX e o provedor de IA. Analise as configurações específicas do provedor relacionadas à detecção de atividade de voz e ao áudio no arquivo config.yaml.

Última atualização

Este guia foi atualizado pela última vez em 5 de agosto de 2026

https://www.3cx.com.br/docs/programmable-extensions/