Modo Expert do VoiceAgent

Este artigo explica como utilizar o Modo Expert para ver, editar e importar a configuração completa do seu VoiceAgent através do separador Avançado.

Nível de utilizador: Admin

O Modo Expert dá-lhe acesso direto à configuração completa do seu VoiceAgent como um ficheiro JSON. Desbloqueia o separador Avançado nas definições do VoiceAgent, onde pode ver, editar e importar configurações com acesso a campos e opções de otimização que não estão disponíveis no separador Formulário.

O que pode fazer com o Modo Expert

O Modo Expert é útil quando precisa de atualizar uma definição que não está disponível no separador Formulário, como mudar para um modelo de IA específico, ajustar o comportamento da voz ou otimizar a gestão de chamadas. Abra o separador Avançado, localize o campo relevante, atualize o valor e guarde.

Como o Modo Expert se relaciona com o separador Formulário

O separador Formulário e o separador Avançado apresentam a mesma configuração de duas formas diferentes. Qualquer definição que configure no separador Formulário também está presente no JSON, e as alterações feitas num separador são refletidas no outro. O Modo Expert vai além do que o separador Formulário oferece. O separador Avançado expõe campos adicionais para otimizar o comportamento do modelo de IA, a qualidade de voz e a gestão de chamadas que não aparecem no separador Formulário.

Campos disponíveis em ambos os separadores

Os seguintes campos podem ser configurados no separador Formulário ou no separador Avançado. Personalidade

Etiqueta do separador Formulário	Campo JSON	O que define
Nome	`agentName`	O nome de exibição do VoiceAgent
Direção da chamada	`direction`	Se o agente processa chamadas de entrada ou de saída. Valores aceites: `"inbound"` ou `"outbound"`.
Idioma	`language`	O idioma que o VoiceAgent fala
Idiomas adicionais	`secondaryLanguages`	Idiomas adicionais que o VoiceAgent consegue detetar e para os quais pode mudar durante uma chamada. Opcional.
Voz	`voice`	A voz utilizada pelo VoiceAgent
Saudação	`greeting`	A frase de abertura exata que o VoiceAgent diz no início de uma chamada. Se for deixado vazio, os agentes de chamadas de entrada recorrem a uma predefinição genérica; os agentes de chamadas de saída começam com silêncio.

Fontes de Conhecimento

Etiqueta do separador Formulário	Campo JSON	O que define
Bases de conhecimento	`knowledgeBaseIds`	Bases de conhecimento que o VoiceAgent pode utilizar para responder a perguntas

Comportamento

Etiqueta do separador Formulário	Campo JSON	O que define
Prompt de objetivo	`goalPrompt`	As instruções principais que definem o comportamento do VoiceAgent durante uma chamada
Competências	`skills`	Capacidades estruturadas: Transferir para humano, Registrar recado, Extrair Informação, Responder a Perguntas, Marcação de Compromissos
Cenários	`scenarios`	Como o VoiceAgent responde a situações específicas, incluindo terminar chamadas
Guardrails	`guardrails`	Respostas fixas para situações que exigem uma resposta consistente, independentemente do contexto

Campos exclusivos do Modo Expert

Os seguintes campos só estão acessíveis através do separador Avançado.

Estilo de conversa

Estes dois campos controlam a forma como o VoiceAgent fala. São opcionais: se não os definir, a CloudTalk aplica predefinições que correspondem ao comportamento atual do VoiceAgent. Após a próxima gravação, ambos os campos aparecem automaticamente no JSON com os respetivos valores predefinidos. Isto é esperado.

Campo	O que define	Valores
`tone`	Como o VoiceAgent soa. Uma lista de predefinições de estilo; podem ser combinadas, mas uma ou duas funcionam melhor (cada predefinição adicional dilui as restantes). A ordem não importa, os duplicados são removidos automaticamente e não são aceites valores de texto livre.	`"professional"`, `"friendly"`, `"casual"`, `"calm"`, `"empathetic"`, `"direct"`.Opcional; predefinição `["friendly", "direct"]`.
`verbosity`	Quanto o VoiceAgent diz em cada resposta. `"concise"` = a resposta útil mais curta possível. `"standard"` = uma a duas frases, oferecendo mais se necessário. `"thorough"` = respostas mais completas com contexto útil (ainda assim breve; isto é uma chamada telefónica).	`"concise"` / `"standard"` / `"thorough"`. Opcional; predefinição `"standard"`.

Guia de predefinições de tom:

Predefinição	Efeito
`professional`	Comedido, preciso e respeitoso
`friendly`	Caloroso e simpático
`casual`	Descontraído e informal, como um colega prestável
`calm`	Estável, sem pressa e paciente
`empathetic`	Reconhece os sentimentos do interlocutor antes de avançar para soluções
`direct`	Vai direto à resposta e reduz as formalidades ao mínimo

Independentemente do tom e da verbosidade, o VoiceAgent mantém-se sempre breve em momentos operacionais: confirmações, repetições de informação, despedidas e passos de transferência ou marcação. Definir um valor não suportado mostra uma mensagem de validação com os valores permitidos e a configuração não é guardada.

Modelo de IA

Campo	O que define
`llmOverride`	Fixa um modelo de IA específico em vez de utilizar a seleção automática. Consulte a lista de modelos suportados abaixo.
`providerOverride`	Força um fornecedor de voz específico (`"elevenlabs"` ou `"deepgram"`). Na maioria dos casos, não é necessário definir isto manualmente, uma vez que o idioma determina o fornecedor automaticamente.
`temperature`	Controla a variedade das respostas do VoiceAgent. Aceita valores entre `0.0` e `1.0`. Para agentes profissionais ou estruturados, recomenda-se um valor entre `0.1` e `0.3`. Obrigatório.

Modelos suportados para llmOverride

Modelo	Valor
GPT-4o Mini	`openai - gpt-4o-mini`
GPT-4o	`openai - gpt-4o`
GPT-4.1	`openai - gpt-4.1`
GPT-4.1 Mini	`openai - gpt-4.1-mini`
GPT-4.1 Nano	`openai - gpt-4.1-nano`
GPT-5	`openai - gpt-5`
GPT-5 Mini	`openai - gpt-5-mini`
GPT-5 Nano	`openai - gpt-5-nano`
GPT-5.1	`openai - gpt-5.1`
Claude 3 Haiku	`anthropic - claude-3-haiku`
Claude Haiku 4.5	`anthropic - claude-haiku-4-5`
Claude 3.7 Sonnet	`anthropic - claude-3-7-sonnet`
Gemini 2.0 Flash Lite	`google - gemini-2.0-flash-lite`
Gemini 1.5 Pro	`google - gemini-1.5-pro`

Ajuste de voz

Campo	O que define	Valores
`stability`	Controla a consistência da voz do VoiceAgent ao longo da chamada. Valores mais altos produzem uma voz mais estável.	`0.0`–`1.0`. Obrigatório.
`similarity`	Controla a proximidade entre a voz e o modelo de voz original.	`0.0`–`1.0`. Obrigatório.
`optimizeStreamingLatency`	Troca qualidade de voz por menor latência de resposta. Valores mais altos reduzem a latência, mas podem afetar a qualidade. Não defina este valor como `4`, pois desativa a normalização de texto, o que faz com que números e datas sejam pronunciados incorretamente.	`0`–`4`. Obrigatório.

Comportamento da chamada

Campo	O que define	Valores
`maxCallDuration`	Define um limite máximo para a duração da chamada, em minutos.	Recomendado: 3–5 para chamadas de saída, 15–30 para chamadas de entrada. Obrigatório.
`dialTime`	Durante quanto tempo o VoiceAgent aguarda por uma resposta em chamadas de saída antes de desistir.	`5`–`120` segundos. Opcional.

Ajuste avançado do ElevenLabs

Estas definições aplicam-se apenas quando o seu VoiceAgent utiliza o ElevenLabs, que é a predefinição para a maioria das configurações de idioma.

Campo	O que define	Valores
`speculativeTurn`	O VoiceAgent começa a preparar a resposta antes de o interlocutor terminar de falar, reduzindo a latência de resposta percebida.	`true` / `false`
`turnEagerness`	Controla a rapidez com que o VoiceAgent toma a vez quando o interlocutor faz uma pausa.	`"patient"` / `"normal"` / `"eager"`
`turnModel`	Define a versão do modelo de deteção de vez utilizado.	`"turn_v2"` / `"turn_v3"`
`vad`	Filtra o ruído de fundo para que não desencadeie uma resposta não intencional.	`true` / `false`
`asrKeywords`	Palavras ou expressões a priorizar no reconhecimento de voz. Útil para nomes de produtos ou terminologia técnica.	Lista de strings
`interruptionIgnoreTerms`	Reconhecimentos curtos do interlocutor (por exemplo, sons de concordância) que não devem contar como interrupção, para que o VoiceAgent continue a falar apesar deles. Escritos no idioma do interlocutor.	Lista de strings. Opcional.
`interruptionIgnoreTermLanguages`	Os idiomas em que os termos a ignorar são correspondidos.	Lista de códigos de idioma. Opcional.
`backgroundSound`	Reproduz um som ambiente de fundo por baixo da fala do VoiceAgent.	Objeto: `preset` (obrigatório quando backgroundSound está definido; um de `"office"`, `"office2"`, `"restaurant"`, `"city"`, `"typing"`, `"elevator"`, `"elevator2"`, `"elevator3"`, `"elevator4"`), `volume` (`0.0`–`1.0`, opcional), `crossfadeLoop` (`true`/`false`, opcional; repete o som de forma contínua).

No separador Avançado, estes campos devem ser colocados dentro de um objeto elevenLabsSettings. Não devem ficar ao nível raiz da configuração. Segue-se um exemplo de como os aninhar:

{
  "agentName": "Clinic Reception",
  "direction": "inbound",
  "language": "es",
  "temperature": 0.2,
  "elevenLabsSettings": {
    "speculativeTurn": true,
    "turnEagerness": "patient",
    "turnModel": "turn_v3",
    "vad": true,
    "asrKeywords": ["Capil Clinic", "injerto capilar", "Barcelona"],
    "interruptionIgnoreTerms": ["vale", "sí", "ajá"],
    "interruptionIgnoreTermLanguages": ["es"],
    "backgroundSound": {
      "preset": "office",
      "volume": 0.3,
      "crossfadeLoop": true
    }
  }
}

Quando uma configuração guardada inclui elevenLabsSettings, o objeto enviado substitui o que estava guardado. Para limpar um único subcampo, omita-o do objeto enviado. Omitir elevenLabsSettings por completo mantém as definições guardadas.

Estes campos devem ser colocados dentro de elevenLabsSettings; ao nível raiz não são reconhecidos e a gravação falha com um erro de validação.

Importar e exportar configurações

Pode exportar uma configuração a partir do separador Avançado e importá-la para um VoiceAgent diferente, ou partilhá-la com outro utilizador para que a importe na respetiva conta. A maioria das configurações é importada de imediato, sem necessidade de configuração adicional. A exceção é quando uma configuração faz referência a recursos específicos da sua conta, como uma base de conhecimento, uma ferramenta personalizada, um número de telefone ou uma integração de calendário. Estas ligações têm de ser configuradas manualmente após a importação. Após qualquer importação bem-sucedida, guarde o VoiceAgent duas vezes. Um conjunto conhecido de casos limite só aparece após a segunda gravação. As configurações exportadas agora incluem tone e verbosity. Se uma configuração importada contiver um valor não suportado para estes (ou quaisquer outros) campos, a importação é rejeitada com uma mensagem que indica o campo e os valores permitidos.

Precisa de ajuda ou tem alguma dúvida? Contacte-nos através do nosso Portal de Suporte — estamos aqui para o ajudar.

Primeiros passos

Números e portabilidade

IA

AI Sales Dialer

CloudTalk Phone e Go

Mensagens

Dashboard

Integrações

Faturação e subscrição

Notícias e atualizações técnicas

Dashboard antigo

O que pode fazer com o Modo Expert

Como o Modo Expert se relaciona com o separador Formulário

Campos disponíveis em ambos os separadores

Campos exclusivos do Modo Expert

Estilo de conversa

Modelo de IA

Ajuste de voz

Comportamento da chamada

Ajuste avançado do ElevenLabs

Importar e exportar configurações

​O que pode fazer com o Modo Expert

​Como o Modo Expert se relaciona com o separador Formulário

​Campos disponíveis em ambos os separadores

​Campos exclusivos do Modo Expert

​Estilo de conversa

​Modelo de IA

​Ajuste de voz

​Comportamento da chamada

​Ajuste avançado do ElevenLabs

​Importar e exportar configurações

O que pode fazer com o Modo Expert

Como o Modo Expert se relaciona com o separador Formulário

Campos disponíveis em ambos os separadores

Campos exclusivos do Modo Expert

Estilo de conversa

Modelo de IA

Ajuste de voz

Comportamento da chamada

Ajuste avançado do ElevenLabs

Importar e exportar configurações