Crie um Agente de Voz Realtime do Grok xAI

Introdução

O exemplo grokvoiceagent.cs conecta uma chamada recebida no 3CX a uma sessão de voz em tempo real do xAI Grok. O agente pode atender chamadas, pesquisar no diretório aprovado da empresa, conectar chamadas, oferecer correio de voz ou chat e salvar o contexto do chamador, quando configurado.

O exemplo 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 Edição 3CX IA, uma versão do PABX com o Update 10 e uma conta de API xAI.

Crie o Script de Chamada no 3CX

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

• Escolha grokvoiceagent.cs.

• Digite o nome do script em letras minúsculas e sem espaços; por exemplo, grokreception.
• Escolha como o script será executado e atribua o DID, a rota de tronco ou o destino interno necessários.
• Atribua o roteiro a um departamento.
• Passe para o editor de código.

Configure o xAI e o Script

Adicione os seguintes parâmetros protegidos ao PABX:

• GROK_API_KEY — a chave de API da sua conta xAI.
• GROK_REALTIME_MODEL — o modelo de voz Grok Realtime.

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

Não insira a chave da API do Grok 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 e, normalmente, deve ser usado apenas para testes temporários.

Em seguida, verifique essas configurações do cliente na parte superior do script:

Antes da produção, defina AllowAllVisibilityForTesting como false e exponha apenas os objetos de diretório necessários.

Para ativar o exemplo de ferramenta opcional, verifique seu manipulador e remova o comentário:

RegisterExampleCustomTool();



Selecione Salvar e confirme que a compilação foi bem-sucedida na saída do Script.

Como Funciona

• A pessoa que liga chega ao script.
• O script cria uma lista de visibilidade restrita de diretórios.
• O 3CX prepara o canal de mídia e inicia a sessão de voz em tempo real do Grok.
• O agente conversa com a pessoa que ligou e utiliza as funções aprovadas do 3CX.
• As transferências são realizadas por meio de ferramentas, e não por meio de promessas verbais.
• Em caso de falha do provedor ou do meio de comunicação, a chamada é encaminhada para o recurso alternativo configurado.

Teste o Script

• Confirme a voz do Grok selecionada e o comportamento multilíngue.
• Pesquise ramais permitidos e ocultos.
• Confirme se o atendente realiza a transferência após a confirmação do chamador.
• Teste o correio de voz e o chat quando um usuário estiver indisponível.
• Diga adeus e verifique se a sessão é encerrada normalmente.
• Falha do provedor de testes e comportamento de fallback.

Solução de Problemas

• A sessão falha imediatamente: verifique o GROK_API_KEY, o modelo compatível, a licença, a versão do PABX e a conectividade com o provedor de saída.
• A transferência é anunciada, mas não é executada: confirme se as instruções personalizadas ainda exigem a ferramenta de conexão e se não foram sobrescritas.
• A pesquisa no diretório retorna resultados em excesso: desative o AddAll() e restrinja a visibilidade.
• O fallback falha: verifique as permissões do destino e do departamento.
• O prompt está ausente: confirme se ERROR existe no conjunto de prompts ativo.

Veja Também

• Crie 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/grok-ai-voice-agent/