Crie um Agente de Voz OpenAI Realtime

Introdução

O exemplo openaivoiceagent.cs conecta uma chamada recebida no 3CX a uma sessão de voz com o OpenAI Realtime. Ele pode cumprimentar os chamadores, responder a perguntas gerais, pesquisar as entradas permitidas na lista de contatos do 3CX, conectar chamadores, oferecer correio de voz ou chat e salvar informações úteis sobre o chamador quando esse recurso estiver ativado.

O script também inclui uma ferramenta personalizada get_department_hours desativada, que demonstra como registrar uma função segura que pode ser chamada pela IA.

Este script requer uma licença da Edição IA 3CX, uma versão do PABX com o Update 10 e uma conta na API da OpenAI.

Crie o Script de Chamada no 3CX

• Faça login no Console de Admin 3CX.
• Acesse Integrações > Scripts de Chamada.
• Selecione +Adicionar da Loja.

• Selecione o arquivo openaivoiceagent.cs.

• Digite o nome do script em letras minúsculas e sem espaços; por exemplo, openaireception.
• Selecione como o script será executado; no caso de uma recepcionista, atribua um número DID exclusivo ou encaminhe as chamadas de entrada correspondentes para o script.
• Selecione o departamento responsável pelo script.
• Confirme a seleção para abrir o editor de código.

Configure o OpenAI e o Script

Adicione os seguintes parâmetros ao PABX:

• OPENAI_API_KEY — a chave de API do seu projeto OpenAI.
• OPENAI_REALTIME_MODEL — o modelo OpenAI Realtime.

Deixe os campos ApiKeyOverride e ModelOverride em branco no script. Quando esses valores estão em branco, o script lê automaticamente a chave da API e o modelo a partir dos parâmetros do PABX.

Não insira a chave da API da OpenAI diretamente no script, especialmente se o script for compartilhado, exportado ou publicado. Um valor configurado em ApiKeyOverride ou ModelOverride tem precedência sobre o parâmetro correspondente do PABX.

Em seguida, verifique estas configurações do cliente na parte superior do arquivo openaivoiceagent.cs:

O AddAll() é prático para um teste inicial, mas normalmente deve ser desativado antes da entrada em produção. Defina AllowAllVisibilityForTesting como false e, em seguida, configure apenas os números, departamentos e funções de que o agente precisa.

Para habilitar a ferramenta personalizada de amostra, verifique sua resposta estática e remova o comentário:

RegisterExampleCustomTool();



Substitua o exemplo por uma fonte de dados confiável antes de utilizá-lo com informações reais de clientes.

Selecione Salvar para compilar. Confirme se a saída do script indica que a compilação foi bem-sucedida antes de direcionar o tráfego de produção.

Como Funciona

• Uma chamada recebida é encaminhada ao ponto de encaminhamento do script.
• O script limpa e recria a lista de visibilidade do diretório IA.
• O 3CX prepara o canal de mídia.
• O script inicia uma sessão de voz do OpenAI Realtime.
• O agente utiliza apenas as funções integradas do 3CX e quaisquer ferramentas personalizadas registradas explicitamente.
• Uma transferência bem-sucedida encaminha a chamada para o destino 3CX selecionado.
• Se a configuração da mídia ou a sessão do provedor falhar, o script tenta o plano alternativo configurado e, em seguida, reproduz a mensagem de ERRO caso o encaminhamento também falhe.

Teste o Script

• Ligue para o número DID atribuído e confirme a saudação e a voz selecionada.
• Pesquise um ramal permitido por nome e número.
• Confirme se os ramais ocultos não podem ser pesquisados nem selecionados.
• Teste uma correspondência ambígua de diretório.
• Comportamento de transferência de chamadas de teste, correio de voz para usuários indisponíveis e mensagens de chat.
• Utilize uma chave de provedor inválida em um ambiente de teste e verifique o encaminhamento de fallback.
• Encerre a conversa de forma natural e confirme a limpeza da sessão.

Solução de Problemas

• Falha na sessão do provedor: Verifique o OPENAI_API_KEY, o modelo em tempo real compatível, o acesso à rede, o licenciamento e a versão do PABX de destino.
• O agente não consegue localizar um usuário: Verifique as opções AllowAllVisibilityForTesting, VisibleNumbers, VisibleDepartments e VisibleRoles.
• Estão visíveis os objetos errados: Chame Clear() antes de adicionar a lista de visibilidade de produção e evite usar AddAll().
• O mecanismo de fallback não funciona: Verifique se o destino existe e se pode ser acessado a partir do departamento designado.
• Não é ouvida nenhuma mensagem de erro: Confirme se existe “ERROR” no conjunto de mensagens ativo.

Veja Também

• Criar um Script de Processamento de Chamadas
• Exemplo de Script de Processamento de Chamadas para PIN
• Manual de Administração do 3CX

Última Atualização

Este guia foi atualizado pela última vez em 30 de julho de 2026

https://www.3cx.com.br/docs/open-ai-voice-agent/