Provedores de IA para Ramais Programáveis 3CX
Introdução
Os ramais programáveis do 3CX permitem que os desenvolvedores criem agentes de IA capazes de atender chamadas ao vivo por meio do Sistema Telefônico 3CX.
O Controle de Chamadas do 3CX Agentic é um conjunto de exemplos de código prontos para uso, destinados à criação desses agentes de IA. Cada exemplo conecta um Ramal Programável a um provedor de IA em tempo real, como OpenAI, xAI, Gemini ou Qwen, e disponibiliza ao agente as funções relevantes de controle de chamadas do 3CX.
Este guia mostra como escolher entre OpenAI, xAI, Gemini ou Qwen, configurar o exemplo correspondente com as credenciais do seu 3CX e do provedor, iniciá-lo e fazer uma chamada de teste.
Antes de Começar
Baixe e descompacte o código-fonte do Controle de Chamadas do 3CX Agentic. Todos os quatro exemplos estão incluídos no mesmo pacote.
Escolha entre OpenAI, xAI, Google Gemini ou Alibaba Cloud Qwen e, em seguida, utilize a pasta de exemplos e os valores de configuração correspondentes a esse provedor.
- Um administrador do 3CX com acesso a Admin > Integrações > API, capaz de criar uma Entidade de Serviço.
- Node.js 20+ instalado. O Yarn 4 está incluído no repositório.
- Uma chave de API com acesso ao serviço em tempo real do provedor de IA que você escolher.
- Um ramal do 3CX em funcionamento, como o Cliente Web 3CX, o aplicativo móvel ou o telefone de mesa, para fazer uma chamada de teste para o agente de IA.
Obtenha os Exemplos
Após baixar o código-fonte do Controle de Chamadas do 3CX Agentic, acesse a pasta principal; ela contém o arquivo package.json, examples e packages.
Na pasta “examples”, você encontrará o código de controle de chamadas de agente específico do provedor em questão:
- examples/openai-realtime
- examples/xai-realtime
- examples/gemini-realtime
- examples/alibaba-qwen-realtime
Dentro de cada uma das pastas de exemplo, você encontrará o arquivo config.yaml.example, que deverá ser copiado e renomeado para config.yaml. Mantenha o arquivo config.yaml.example inalterado para que você possa voltar às configurações originais do exemplo, se necessário.
O arquivo config.yaml contém as configurações de conexão com o PABX e com o provedor que permitem que o código do ramal programável funcione.
Criar uma Entidade de Serviço 3CX
No PABX, acesse Admin > Integrações > API e selecione Adicionar uma Entidade de Serviço.
- Digite um ID de cliente, por exemplo: “assistente”.
- Ative a opção "Ativar acesso à API de Controle de Chamadas 3CX para este aplicativo".
- Se você deseja que o agente tenha recursos de busca de contatos e verificação de presença em todo o sistema, também será necessário ativar a opção: “Ativar acesso à API de Configuração do 3CX (XAPI) para este aplicativo”. Defina o departamento e a função de acordo com os recursos que deseja que o agente tenha.
- Guarde a chave da API do 3CX em um local seguro.
Escolha um Provedor e Configure o Config.yaml
OpenAI
- No arquivo config.yaml, digite:
- appId: ID do Cliente do PABX Integrações > API > ID do Cliente
- appSecret: Chave de API do PABX do Principal de Serviço, em Integrações > API > Gerar Chave de API
- pbxBase: endereço do PABX
- openaiApiKey: chave de API da OpenAI, obtida em Chaves de API da OpenAI
Instale as dependências e execute o exemplo da OpenAI:
yarn install
yarn start:openai
Um registro de inicialização bem-sucedido da OpenAI inclui:
openai-realtime starting
3CX PBX: https://your-pbx.3cx.eu:5001
OpenAI model: <configured model>
OpenAI voice: <configured voice>
Agent profile: receptionist (role: receptionist)
SDK connected (auth + WebSocket + state)
[MCP] connected to https://your-pbx.3cx.eu:5001/mcp
MCP tools (1/8):
✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.
✗ get_server_time: Get the current server time in UTC and local timezone.
✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.
✗ find_extension: Find a contact by exact extension number
✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.
✗ find_by_email: Find a contact by email address
✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system
✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company
[CallStore] initialized (OpenAI Realtime mode)
All systems ready (OpenAI Realtime mode)
xAI
- No arquivo config.yaml, digite:
- appId: ID do Cliente do PABX Integrações > API > ID do Cliente
- appSecret: Chave de API do PABX do Principal de Serviço, em Integrações > API > Gerar Chave de API
- pbxBase: endereço do PABX
- xaiApiKey: chave de API da xAI, obtida em console.x.ai
Instale as dependências e execute o exemplo do xAI:
yarn install
yarn start:xai
Um log de uma inicialização xAI de sucesso inclui:
xai-realtime starting
3CX PBX: https://your-pbx.3cx.eu:5001
Agent profile: receptionist (role: receptionist)
xAI Voice: tara
SDK connected (auth + WebSocket + state)
[MCP] connected to https://your-pbx.3cx.eu:5001/mcp
MCP tools (1/8):
✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company
✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.
✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.
✗ get_server_time: Get the current server time in UTC and local timezone.
✗ find_by_email: Find a contact by email address
✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system
✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.
✗ find_extension: Find a contact by exact extension number
[CallStore] initialized (xAI realtime mode)
All systems ready (xAI realtime mode)
Gemini
- No arquivo config.yaml, insira:
- appId: ID do Cliente do PABX Integrações > API > ID do Cliente
- appSecret: Chave de API do PABX do Principal de Serviço, em Integrações > API > Gerar Chave de API
- pbxBase: endereço do PABX
- geminiApiKey: chave de API do Google AI Studio, obtida no Google AI Studio
Instale as dependências e execute o exemplo do Gemini:
yarn install
yarn start:gemini
Um registro de inicialização bem-sucedido do Gemini inclui:
agentic-call-control starting
3CX PBX: https://your-pbx.3cx.eu:5001
Gemini Voice: Kore
Agent profile: receptionist (role: receptionist)
SDK connected (auth + WebSocket + state)
[MCP] connected to https://your-pbx.3cx.eu:5001/mcp
MCP tools (1/8):
✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company
✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.
✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.
✗ get_server_time: Get the current server time in UTC and local timezone.
✗ find_by_email: Find a contact by email address
✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system
✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.
✗ find_extension: Find a contact by exact extension number
[CallStore] initialized (Gemini Live mode)
All systems ready (Gemini Live mode)
Qwen
- No arquivo config.yaml, digite:
- appId: ID do Cliente do PABX Integrações > API > ID do Cliente
- appSecret: Chave de API do PABX do Principal de Serviço, em Integrações > API > Gerar Chave de API
- pbxBase: endereço do PABX
- dashscopeApiKey: chave de API do DashScope do Alibaba Cloud, obtida em Chave de API do DashScope do Alibaba Cloud
- dashscopeBaseUrl: Use https://dashscope-intl.aliyuncs.com para uma chave internacional/de Cingapura ou https://dashscope.aliyuncs.com para uma chave da China continental.
Instale as dependências e execute o exemplo do Qwen:
yarn install
yarn start:alibaba-qwen
Um log de inicialização bem-sucedido do Qwen inclui:
alibaba-qwen-realtime starting
3CX PBX: https://your-pbx.3cx.eu:5001
DashScope: https://dashscope-intl.aliyuncs.com
Model: qwen3.5-omni-plus-realtime
Voice: Tina
Agent profile: receptionist_en (role: receptionist)
SDK connected (auth + WebSocket + state)
[McpManager] connected to https://your-pbx.3cx.eu:5001/mcp
MCP tools (1/8):
✓ list_phonebook: Search for contacts in the phonebook by name, number, email, or company
✗ control_participant: Control an active call participant: drop, answer, divert, routeto, or transferto.
✗ list_peers: List internal numbers of any type (extensions, queues, ring groups, IVRs, etc.). Supports filtering by name, number, or type.
✗ get_server_time: Get the current server time in UTC and local timezone.
✗ find_by_email: Find a contact by email address
✗ list_crm_contacts: Search for contacts in CRM (Customer Relationship Management) system
✗ get_edit_url: Get a clickable link to open a DN (extension, queue, ring group, IVR, trunk, etc.) in the management UI editor.
✗ find_extension: Find a contact by exact extension number
[CallStore] initialized (Qwen Omni realtime)
All systems ready (Qwen realtime mode)
Teste o Agent
Use um ramal de teste. Para testes de transferência, use um segundo ramal interno de teste. Na pasta principal “3CX Agentic Call Control”, execute o comando correspondente ao provedor que você configurou:
- OpenAI: yarn start:openai
- xAI: yarn start:xai
- Gemini: yarn start:gemini
- Qwen: yarn start:alibaba-qwen
- Aguarde até que o terminal indique a conexão com o PABX e o estado “pronto”.
- Ligue para o ID do Cliente do Principal de Serviço (appId) a partir do ramal de teste. Por exemplo, você disca o ID do Cliente literal “assistant” para se conectar ao agente.
- Confirme se o agente atende, reproduz sua mensagem de boas-vindas e responde a você.
- Teste uma busca de ramal ou peça a ele para encerrar a chamada para você.
- Verifique se há erros na saída do terminal.
Personalizar o Agente
Use o config.yamlpara alterar a mensagem de boas-vindas e as configurações específicas do provedor. Para alterar o comportamento padrão, edite agents/receptionist.yaml ou adicione outro perfil em agents/. Se você adicionar customMcpServers, liste os nomes exatos das ferramentas em mcpTools nesse perfil de agente. Reinicie o agente após cada alteração de configuração e faça outra chamada de teste.
Veja Também
- Controle de Chamadas Agentic 3CX
- API de Controle de Chamadas 3CX
- API de Configuração 3CX
- Especificação de Endpoint da API de Controle de Chamadas
Última Atualização
Este documento foi atualizado pela última vez em 28 de agosto de 2026
https://www.3cx.com.br/docs/agentic-call-control-ai-providers/
Copyright © 2025