Guias

Agente de voz

Um agente vale o que vale o seu prompt de sistema. Esta página mostra como escrever um, dá-lhe três exemplos prontos para copiar e explica os limites que deve ter em conta.

1Estrutura do systemPrompt

Um bom prompt tem quatro partes. Se omitir uma delas, o agente acabará por ficar preso sem saber o que fazer a seguir - ou fica em silêncio ou inventa algo.

• Quem sou - uma ou duas frases: nome da empresa, função, tom de voz. O agente tem de estabelecer esta identidade logo na primeira frase.
• O que posso fazer - as tarefas concretas que o agente realmente trata (encomendas, marcações, informações) - não um vago "posso ajudar em tudo".
• O que NUNCA faço - os limites: o que o agente nunca deve inventar, prometer ou divulgar. É a parte que mais vezes se omite e é exatamente o que separa um agente que inventa preços de um que diz com franqueza "não sei, ligue para...".
• Como terminar a chamada - quando e como encerrar a chamada (resumo, despedida) e o que fazer quando quem liga quer algo fora do âmbito.

Instruções mais longas atrasam a resposta cerca de um décimo de segundo por cada dois mil carateres - o editor do agente assinala-o a partir de 3000 carateres. O limite rígido é de 6000 carateres.

Três exemplos completos - copie-os e adapte-os ao seu caso:

Rececionista de café

É o rececionista de voz do Nula Cafe, em Vinohrady. Fala com
calma, simpatia e brevidade - como um funcionário experiente, não como
um robô.

O QUE PODE FAZER
- Aceitar encomendas para levantamento (café, chá, croissants, sandes).
- Informar sobre o horário atual: de segunda a sexta das 8h às 18h,
  ao fim de semana das 9h às 15h.
- No fim da encomenda, repetir tudo por inteiro e confirmar a hora de
  levantamento (pelo menos 15 minutos a partir de agora).

O QUE NUNCA FAZ
- Nunca inventa preços nem produtos que não estão na ementa - diz que
  o preço exato será confirmado no local pelo pessoal.
- Nunca promete entrega ao domicílio, o café não entrega.
- Nunca finge ser uma pessoa quando lhe perguntam diretamente - diz que
  é o assistente de voz do café.

COMO TERMINAR A CHAMADA
Resuma a encomenda e a hora de levantamento, deseje um bom dia e termine
a chamada. Se quem liga quiser algo que não pode tratar (reclamações,
catering), diga-lhe que volte a ligar durante o horário de atendimento
e fale diretamente com o proprietário.

Inquérito de satisfação

Está a ligar em nome da Botanika, uma loja online, para um pequeno
inquérito de satisfação depois de uma encomenda recente. É educado, vai
direto ao assunto e não prolonga a chamada.

O QUE PODE FAZER
- Perguntar se o cliente tem um minuto para três perguntas rápidas.
- Pergunta 1: como avalia a sua satisfação com a encomenda, numa escala
  de 1 a 5.
- Pergunta 2: o pacote chegou a tempo?
- Pergunta 3: há alguma coisa que possamos melhorar?
- Memorizar as respostas e resumi-las brevemente no fim da chamada.

O QUE NUNCA FAZ
- Nunca insiste com um cliente que recusa ou diz que não tem tempo -
  termina logo a chamada com cortesia.
- Nunca trata de reclamações nem de devoluções - isso pertence à linha
  de apoio ao cliente, que pode ler em voz alta se lhe pedirem.
- Nunca oferece descontos nem cupões, não tem autorização para isso.

COMO TERMINAR A CHAMADA
Agradeça o tempo e a opinião e deseje um bom dia. Se o cliente disser em
qualquer momento que não quer continuar, termine logo a chamada com
cortesia, sem mais perguntas.

Receção / portaria

É a receção de voz da Nordwex, um edifício de escritórios em
Pankrác. Ligam para este número estafetas, visitantes e fornecedores.

O QUE PODE FAZER
- Perceber quem está a ligar e porquê (um estafeta com uma encomenda,
  um visitante para uma reunião, um fornecedor).
- Se for um visitante, obter o nome e com quem vai reunir, e dizer-lhe
  que se anuncie na receção do rés-do-chão e aguarde até alguém o vir
  buscar.
- Se for um estafeta, dizer-lhe que deixe o pacote na receção e escreva
  nele o nome da empresa e o destinatário.
- Anotar uma mensagem curta quando a pessoa procurada não estiver
  disponível de momento.

O QUE NUNCA FAZ
- Nunca divulga os telemóveis privados dos funcionários - propõe
  transferir para a receção ou anotar uma mensagem.
- Nunca deixa ninguém subir "sozinho" - todos os visitantes passam pela
  receção.
- Nunca revela quem está atualmente no edifício nem quando - diz que
  têm de consultar a receção.

COMO TERMINAR A CHAMADA
Repita o que ficou combinado (mensagem, espera na receção, transferência),
deseje um bom dia e termine a chamada.

2Modelos por setor

Não quer escrever um prompt de raiz? O site tem modelos prontos para seis setores (clínica dentária, oficina automóvel, restaurante, loja online, imobiliária, profissionais de ofícios) - um prompt de sistema completo, um diálogo de exemplo e um exemplo do que custaria um rececionista assim. Copie e ajuste, tal como os exemplos acima.

Ver os modelos por setor

3firstMessage

firstMessage é a primeira frase que o cliente ouve - logo após atender, numa chamada recebida, ou logo após a pessoa chamada atender, numa chamada efetuada.

• Português falado e curto - como uma pessoa o diria, não como escreveria um e-mail.
• Diga logo quem liga ou atende - o cliente tem de saber com quem fala em três segundos.
• Termine com uma pergunta aberta ("em que posso ajudar", "tem um minuto") - não com um longo monólogo.
• Leia-a em voz alta - um texto que parece bem por escrito pode soar desajeitado quando dito.
• Em chamadas efetuadas, apresente-se e diga o motivo da chamada logo no início - as pessoas desconfiam de números desconhecidos.

4Ferramentas

Uma ferramenta é o endereço da sua API, que o agente chama a meio de uma chamada e cuja resposta usa de imediato na conversa. Sem ferramenta, o agente só sabe falar; com uma, pode verificar uma encomenda, encontrar uma vaga livre ou registar uma reserva.

As ferramentas criam-se no portal em /pt/agent/tools (ou através de POST /v1/tools) e depois ativam-se num agente com uma caixa de seleção na sua página de detalhe (o campo toolIds na API). Uma ferramenta pertence à conta, não a um agente - a mesma ferramenta pode ser usada por vários agentes. Para ela indica quatro coisas:

• Nome - legível ("Verificar encomenda"). O nome que o modelo vê deriva-se dele automaticamente (overit_objednavku) e aparece por baixo do campo.
• Quando o agente a deve usar - a única coisa em que o modelo se baseia para decidir chamar a ferramenta. Escreva-a como uma instrução: "Usar quando quem liga perguntar onde está a sua encomenda."
• Endereço e método - apenas https, acessível publicamente. GET envia os parâmetros na query string, POST no corpo JSON. Mais os cabeçalhos, tipicamente Authorization.
• Parâmetros - para cada um indica de onde vem o valor: o modelo extrai-o da chamada, o número de quem liga ou do número chamado é preenchido automaticamente, ou é um valor fixo.

É assim que se apresenta o pedido que chega ao seu endpoint durante a chamada:

POST https://api.yourapp.com/orders
Content-Type: application/json
Authorization: Bearer your_key

{
  "order_number": "A-42",
  "phone": "+420777123456"
}

E esta é a resposta com que o agente consegue trabalhar - um JSON curto que ele pode transformar numa única frase:

{
  "status": "shipped",
  "delivery": "amanhã de manhã"
}

5Transferência para uma pessoa

O agente pode transferir a chamada para o seu número quando quem liga pede uma pessoa ou encontra algo que o agente não consegue resolver. Ativa-se na página de detalhe do agente (o campo transferTo na API); a condição escreve-a como uma instrução ao modelo em transferCondition. Sem ela, usamos uma frase por defeito.

No motor de voz próprio da volai

No motor de voz próprio da volai, a transferência é feita por ponte: o agente diz que está a ligar, quem liga ouve o toque e a pessoa no seu número vê o número do agente. Assim que atender, o agente fica em silêncio e a chamada continua entre os dois através da volai. Se um de vós desligar, a chamada termina para ambos. Se não atender em 25 segundos, o agente pede desculpa a quem liga, propõe anotar uma mensagem e continua.

Não pode transferir para um número volai seu - a chamada entraria em ciclo consigo própria até o saldo acabar. As linhas de tarifa majorada (90x) estão proibidas pelo mesmo motivo.

Um agente que usa um número para chamadas e SMS só transfere para números checos (+420): as chamadas a partir desse número seguem apenas para números checos, por isso um número de transferência fora de +420 não é guardado para esse agente e a API devolve destination_not_allowed.

6Dados recolhidos das chamadas

Em vez de ler a transcrição completa, pode indicar exatamente o que quer de uma chamada - um nome, uma quantidade, se é urgente. O agente preenche-o depois da chamada e recebe-o de volta em JSON.

Cada campo tem uma chave, um tipo e uma descrição. Até dez campos por agente:

• Chave (key) - letras minúsculas, dígitos e carateres de sublinhado, até 40 carateres - tem de começar por uma letra minúscula. Encontra o valor com este nome no resultado.
• Tipo (type) - string, number ou boolean.
• Descrição (description) - exatamente o que o modelo deve extrair, de 5 a 500 carateres. Diga também o que deve fazer quando a chamada não o menciona.
• Opções (enumValues) - uma lista opcional, só para campos de texto. O modelo escolhe então apenas entre os valores oferecidos, pelo que o resultado pode ser filtrado diretamente. No máximo 20 opções, cada uma até 60 carateres.

curl -X PATCH https://volai.eu/v1/agents/ag_kx91fa2b \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataFields": [
      {"key": "name", "type": "string", "description": "O nome de quem ligou, tal como o indicou. Deixar vazio se não o mencionou."},
      {"key": "coffee_count", "type": "number", "description": "Quantos cafés encomendou quem ligou."},
      {"key": "urgency", "type": "string", "description": "Quão urgente era o pedido.", "enumValues": ["low", "normal", "high"]}
    ]
  }'

O resultado aparece em três sítios: na página de detalhe da chamada no portal, num cartão "Dados recolhidos", no campo data da chamada (tanto em GET /v1/calls como em GET /v1/calls/{id}) e no corpo do webhook call.completed.

{
  "call": {
    "id": "c_8f2ac1d4",
    "status": "completed",
    "hasRecording": true,
    "data": {
      "name": "Joana Silva",
      "coffee_count": 2,
      "urgency": "normal"
    }
  }
}

Um valor null significa "não mencionado na chamada" - o mesmo se aplica se o modelo devolver uma cadeia vazia. Se um agente não tiver campos configurados, a chave data nem sequer aparece na resposta.

7Objetivo do agente e avaliação

Um objetivo é uma frase que descreve o que a chamada deve alcançar - "marcar uma visita", "descobrir se o cliente está interessado na oferta". Preenche-o no campo "Objetivo do agente" no portal (ao criar o agente ou mais tarde, ao editá-lo), ou através da API REST e do MCP, com o campo goal em POST/PATCH /v1/agents e create_agent/update_agent (até 300 carateres).

O objetivo chega ao agente como critério para avaliar a chamada: quando a chamada termina, um modelo lê a transcrição em função dele e decide se o objetivo foi cumprido, não cumprido ou se não é possível determiná-lo a partir da chamada. Vê o resultado na chamada no portal - na página de detalhe da chamada e na lista de chamadas - e também no e-mail após a chamada, junto ao resumo.

O que o agente sabe (material de apoio)

Além das instruções, pode dar ao agente material de apoio - horário, tabela de preços, perguntas frequentes. Preencha-o no campo "O que o agente sabe" no portal (secção Avançado), ou no campo knowledge em POST/PATCH /v1/agents. O texto é acrescentado ao fim do prompt, cabe em 20000 carateres e um PATCH com um valor vazio apaga-o. Ao contrário de uma ferramenta, este material nunca muda durante a chamada - tudo o que muda (estado de uma encomenda, vagas livres) pertence a uma ferramenta, não aqui.

8E-mail após a chamada

Depois de terminar uma chamada com o agente, a volai envia-lhe um e-mail com o resumo e uma ligação para o detalhe da chamada no portal - o mesmo resumo que vê na API no campo summary. É enviado para agentes que correm no motor de voz próprio da volai (provider: "engine"); um agente na ElevenLabs (provider: "elevenlabs") ainda não o recebe.

O interruptor "E-mail após cada chamada" está na página de Definições - desativá-lo pára o e-mail de imediato para toda a conta. Para o parar para um único agente, use a caixa "Enviar-me um e-mail após cada chamada" na página de detalhe desse agente (o campo notifyEmail: false na API). Recebe no máximo um e-mail por chamada, e uma chamada sem nada a reportar (sem resumo, sem dados recolhidos e sem motivo de fim) não o desencadeia.

9Gravações

As chamadas do agente são gravadas e pode ouvi-las diretamente na página de detalhe da chamada no portal - um clique na transcrição salta para o ponto correspondente da gravação. Para a descarregar ou reproduzir noutro sítio, use GET /v1/calls/{id}/recording (com a mesma chave de API) - o formato segue o cabeçalho content-type da resposta: audio/mpeg (MP3) para um agente na ElevenLabs, atualmente audio/ogg para um agente no motor da volai. O campo hasRecording indica se uma chamada tem gravação.

• Guardamo-las durante 90 dias após a chamada e depois eliminamo-las. A transcrição e o resumo são guardados em separado e não são eliminados juntamente com a gravação. Passados noventa dias, o endpoint devolve recording_expired.
• Pode desativá-la por agente com um interruptor na sua página de detalhe, ou o campo recordCalls: false na API. Não é feita gravação das chamadas iniciadas a partir desse momento; uma chamada que já está a tocar ou em curso segue a definição do momento em que começou (uma chamada efetuada, do momento em que foi marcada), pelo que ainda é gravada.
• Só são gravadas as chamadas tratadas pelo agente integrado. Uma ponte direta entre dois números, uma chamada de relay e uma chamada SIP nunca são gravadas.

Cada erro da API traz cause (quem o resolve) e action (o que fazer) - ver Formato de erro na referência da API REST.

10Limites

• Uma chamada dura no máximo 10 minutos (600 segundos), depois o próprio agente termina-a.
• Se quem liga ficar em silêncio durante 20 segundos, o agente considera-o o fim da chamada e desliga.
• O agente responde cerca de 1 segundo depois de terminar de falar - em tráfego real isto varia ligeiramente com a carga.

11Idiomas

O agente pode falar cinco idiomas - checo (o predefinido), eslovaco, inglês, alemão e polaco - o idioma define-se na página de detalhe do agente (o campo language em POST/PATCH /v1/agents, create_agent/update_agent). Uma voz dedicada para cada idioma (Cartesia) só está disponível num agente que corre no motor próprio da volai (ver o capítulo Vozes abaixo) - um agente que fica na ElevenLabs fala o idioma escolhido com a voz Anet.

12Chamada de teste

O botão "Ligue-me para um teste" na página de detalhe do agente no portal faz o agente efetuar uma chamada real para o número que indicar - uma verificação rápida de como soa e de como reage ao seu prompt de sistema, sem ter de marcar o número dele à mão.

Faturada como uma chamada efetuada normal com o agente, suplemento de agente incluído (ver o capítulo Preços abaixo) - sem desconto, sem tarifa especial.

Um agente no motor de voz próprio da volai pode fazer uma chamada de teste mesmo sem número próprio - sai pela linha volai partilhada, pelo que o destinatário vê no ecrã o número da volai e não o do agente. Um agente na ElevenLabs sem número próprio não pode iniciar uma chamada de teste enquanto não lhe atribuir um.

No máximo 3 tentativas de chamada de teste por conta e por dia, em todos os agentes - conta cada tentativa que chegou realmente a ligar, mesmo que ninguém tenha atendido; uma tentativa que falhou antes de poder ligar (saldo insuficiente, linha ocupada) não conta para o limite. As chamadas normais através de POST /v1/calls não têm este limite mais estrito.

13Vozes

A escolha do fornecedor na criação tem três estados: useForOutboundTasks: true em POST /v1/agents ou create_agent seleciona o motor de voz próprio da volai, false começa na ElevenLabs mesmo com transferência, e a omissão usa o predefinido da instalação, que depende da disponibilidade do motor, da sua ativação e dos idiomas configurados. Escolher apenas cs ou sk não garante o motor; quando o predefinido do motor está desativado, a criação começa na ElevenLabs. Quando um false explícito se sobrepõe ao predefinido de motor do idioma, a resposta de criação traz o aviso elevenlabs_by_explicit_choice, pelo que deve criar sem o campo um agente destinado apenas a chamadas recebidas. Quando ativa transferTo num agente ElevenLabs, a volai tenta movê-lo para o motor depois de guardar. A tentativa pode estar suspensa, indisponível ou falhar, pelo que deve verificar o resultado com um GET /v1/agents/{id} posterior na REST ou no agente devolvido no MCP. O campo provider indica em que plataforma corre um agente; a transferência não funciona enquanto permanecer na ElevenLabs. Uma mudança bem-sucedida pode alterar a sua voz. A mesma tentativa segue-se a uma alteração de language num agente ElevenLabs de um idioma em que os novos agentes começam na ElevenLabs (hoje en, de, pl) para um em que começam no motor (cs, sk); o agente recebe então a voz de motor predefinida do novo idioma (Milena, Katarina). Uma mudança entre cs e sk não move nada. As restantes mudanças entre plataformas são feitas pelo apoio da volai. A ElevenLabs só aceita do catálogo katty ou um id de voz ElevenLabs em bruto; as outras vozes do catálogo exigem o motor.

voiceId em create_agent/update_agent (e o campo com o mesmo nome em POST/PATCH /v1/agents) escolhe a voz do agente. A listagem GET /v1/voices sem filtro (MCP list_voices sem o argumento provider) não mostra a voz ElevenLabs katty - a REST só a devolve com ?provider=elevenlabs, o MCP com o argumento provider: "elevenlabs". As vozes Cartesia (Milena, Jan e as vozes de outros idiomas) destinam-se a agentes no motor próprio da volai, a Katty a agentes na ElevenLabs (a nota acima explica em que plataforma corre um agente). A voz mais antiga anet fica apenas nos agentes que já a têm - desde 12 set. 2026 a ElevenLabs já não a atribui a novos agentes e a volai rejeita esse pedido com uma explicação. Na criação com useForOutboundTasks: true explícito, uma voz do catálogo reconhecida mas indisponível no motor, incluindo katty, é substituída pela predefinida do motor para o idioma escolhido; quando um campo omitido seleciona o motor através do predefinido da instalação, a mesma voz incompatível é rejeitada. Um id ElevenLabs em bruto é sempre rejeitado para o motor. Sem voiceId, o agente recebe a voz predefinida do seu fornecedor - Milena no motor, a voz do modelo (Katty) na ElevenLabs.

O catálogo oferece pelo menos uma voz feminina e uma masculina por idioma (hoje quatro para checo): cs: Milena, Jan, Tereza, Marek; sk: Katarina, Peter; en: Skylar, Daniel; de: Alina, Lukas; pl: Ewa, Kacper; nl: Ariel, Alexander; pt: Christine, Filipe; sl: Sarah, Daniel; ro: Mikidutza, Oliver; da: Isabella, Søren; et: Alice, Chris; lv: Matilda, George; bg: Yoana, Peter K; fi: Soili, Jussi; el: Crhysa, Iordanis; fr: Natasha, Max; it: Rossana, Marco; hu: Zsófia, Gábor; lt: Sarah, Daniel; sv: Sanna, Filip. O portal só oferece vozes no idioma escolhido para o agente - mudam em conjunto (ver o capítulo Idiomas acima).

Todas as vozes da tabela pertencem ao motor de voz próprio da volai. Para um agente na ElevenLabs, a API rejeita-as com um 400 - esse agente aceita apenas katty (que a listagem sem filtro não mostra) e um id de voz ElevenLabs em bruto.

voiceId também aceita um ID ElevenLabs em bruto, mas apenas para um agente na plataforma padrão (provider: "elevenlabs"). Use um id de voz do catálogo para um agente no motor. Um valor desconhecido ou incompatível com o fornecedor devolve um erro com a lista das opções válidas.

14Estatísticas

O ecrã de detalhe do agente no portal mostra o número de chamadas atendidas, a sua duração média e máxima e quantas ocorreram nos últimos 30 dias - não existe uma API dedicada para isto, mas pode calcular os mesmos números a partir de GET /v1/calls.

15Preços

O agente de voz é faturado em cima do preço da chamada, ao segundo - sem arredondamento para minutos inteiros. As tarifas não incluem IVA, tal como toda a tabela de preços.

Os preços completos, com exemplos, estão na página de preços.

16Transcrições e webhook

Quando uma chamada termina, obtenha a transcrição e o resumo através de GET /v1/calls/{id} (campos transcript e summary) - ou a volai pode enviá-los para o seu URL como um evento call.completed, assim que estiver pronto. O formato da transcrição, a verificação da assinatura e o tratamento de erros estão na página de webhooks.

17Motor de voz da volai

Alguns agentes correm hoje no motor de voz próprio da volai em vez de na ElevenLabs. A mudança altera o encaminhamento das chamadas e toda a configuração do agente muda com ele - instruções, frase de abertura, campos de dados, objetivo da chamada, conhecimento, ferramentas e transferência de chamadas. O que muda e o que não muda:

• Vozes um agente que tinha uma voz ElevenLabs selecionada (Katty, ou a mais antiga Anet) recebe a voz predefinida do motor para o seu idioma quando muda - Milena para checo. O motor não oferece uma voz ElevenLabs como voz principal, a ElevenLabs fica apenas como reserva para uma falha da Cartesia. As definições do agente permitem então escolher qualquer outra voz do catálogo para o idioma do agente, incluindo Jan para checo. Uma voz que o agente já tenha do catálogo do motor é deixada como está.
• Tempo de resposta mantém-se igual ao da ElevenLabs - cerca de 1 segundo depois de terminar de falar.
• Gravações sem alteração - continuam a ser guardadas durante 90 dias e podem ser desativadas da mesma forma na página de detalhe do agente.
• Aviso de gravação sem alteração - com o aviso de gravação ativado para o agente (`recordingNotice`), a volai acrescenta também aqui à primeira mensagem do agente uma frase curta a dizer que a chamada é gravada (ver a secção Gravações acima). Sem essa opção, ou com a gravação desativada, a frase não é de todo acrescentada.
• Informação de IA sem alteração - a frase de abertura segue para o fornecedor exatamente como a escreveu. Não a impomos: se a frase não disser que quem liga está a falar com um assistente digital, apenas o avisamos (Regulamento da IA da UE, artigo 50.º), e guardar continua a ser possível. A informação continua a ser da sua responsabilidade com qualquer dos fornecedores.
• Ferramentas e transferência de chamadas mudam com o agente - uma mudança bem-sucedida envia ao motor as suas ferramentas e a transferência configurada para uma pessoa, pelo que não tem de as configurar de novo. No motor de voz próprio da volai, a transferência funciona por ponte (como na secção Transferência para uma pessoa acima) - a ponte está comprovada na operação diária e o portal mostra o formulário de transferência completo para um agente no motor. Ativar a transferência num agente na plataforma padrão (ElevenLabs) desencadeia uma tentativa de mudança imediata após guardar; verifique o resultado em `provider`, porque uma tentativa suspensa, um motor indisponível ou uma falha podem deixá-lo na ElevenLabs, onde a transferência não funciona. Uma mudança bem-sucedida pode alterar a sua voz para a predefinida do motor. A migração em massa de números por vagas ignora, por isso, os agentes com transferência configurada.
• Deteção de caixa de correio de voz em chamadas efetuadas só o motor de voz próprio da volai a consegue fazer - em poucos segundos após o atendimento reconhece uma caixa de correio de voz em vez de uma pessoa e, consoante a definição, apenas a assinala, desliga ou espera pelo sinal sonoro e lê uma mensagem. Define-se no detalhe do agente (só agentes do motor), com o campo `voicemail` através da API e do MCP. A lista de chamadas mostra então "Caixa de correio de voz atendeu" para uma chamada efetuada com caixa de correio de voz em vez do resultado habitual. A plataforma padrão (ElevenLabs) não tem esta deteção.
• Lembrete de silêncio só o motor de voz próprio da volai o reproduz - quando quem liga fica em silêncio durante algum tempo, o agente pergunta uma vez se ainda lá está. A definição (ligada/desligada, de 3 a 25 segundos) é guardada para qualquer dos fornecedores - num agente na plataforma padrão (ElevenLabs) o campo no detalhe do agente aparece a cinzento e o valor é ouvido quando o agente passar para o motor. A sua própria frase de lembrete (`silencePromptText`, até 80 carateres, em vez do lembrete predefinido para o idioma do agente, que em inglês é "Are you still there?") é guardada da mesma forma.
• Proteção da primeira frase só o motor de voz próprio da volai a consegue fazer, e apenas em chamadas efetuadas: enquanto a primeira frase é reproduzida (o número de segundos que definir, de 0 a 20), uma reação curta de quem atendeu ("Estou?", "Sim?") não a interrompe: uma resposta sem palavra interruptora (por exemplo pare, não, espere) é descartada na janela protegida, pelo que não interrompe a frase, não consta da transcrição e o agente não reage a ela, ao passo que uma palavra interruptora interrompe-a sempre. As palavras interruptoras seguem o idioma do agente: um agente em inglês é interrompido por stop, no, wait ou hold. O campo `firstMessageProtectSecs` é guardado para qualquer dos fornecedores sem predefinição forçada - para um agente na plataforma padrão (ElevenLabs) aparece a cinzento no detalhe do agente e é ouvido quando o agente passar para o motor. Na transcrição da chamada, uma intervenção do agente que quem liga interrompeu leva a marca `interrupted`.
• Riso do agente só o motor de voz próprio da volai consegue rir de volta quando você ou quem liga se ri ou brinca durante a chamada - e apenas com uma voz Cartesia checa (Milena, Jan e o resto do catálogo). A plataforma padrão (ElevenLabs) não o consegue de todo, mesmo com o campo definido. Nas definições do agente escolhe Automático (o motor desliga o riso por si em temas sensíveis, como cobrança de dívidas, saúde, autoridades ou serviços funerários), Ligado (anula essa deteção) ou Desligado. A alteração produz efeito a partir da chamada seguinte.

18Calendário e marcações

Um agente no motor de voz próprio da volai pode verificar uma vaga livre no seu calendário Google ou Apple durante a própria chamada e marcar logo a consulta - diz a quem liga se uma hora está livre, propõe as vagas livres mais próximas e marca a consulta depois de confirmar um nome. Ative-o no separador Calendário do editor do agente: escolha a ligação (Dados e integrações), o calendário concreto e as regras de disponibilidade.

• Regras de disponibilidade janelas por dia da semana (quando o agente oferece marcações), duração da marcação, intervalo entre marcações, antecedência mínima antes da hora marcada e o horizonte - até onde o agente procura. O editor preenche valores predefinidos, mas cada agente pode ter os seus.
• Ferramentas integradas o calendário usa duas ferramentas integradas, check_availability e book_appointment - ao contrário das ferramentas personalizadas do capítulo Ferramentas acima, não se criam à mão, ativam-se juntamente com o calendário e não contam para o limite de ferramentas da conta.
• Só no motor próprio da volai funciona apenas para um agente no motor de voz próprio da volai. Se ativar o calendário para um agente na plataforma padrão (ElevenLabs), a definição é guardada e o agente tenta passar para o motor da volai logo após guardar - tal como na transferência para uma pessoa.
• O que o agente diz e não diz o agente nunca lê em voz alta o que está escrito no calendário - apenas se uma determinada hora está livre. O número de telefone de quem liga só é acrescentado ao evento quando o agente o conhece (um número oculto significa que o evento fica sem número de telefone).
• Também fora de uma chamada a mesma pesquisa de vagas livres e marcação de consultas funciona também fora de uma chamada, através da REST (POST /v1/integrations/{id}/availability, POST /v1/integrations/{id}/events) e do MCP (find_free_slots, create_calendar_event) - ver a secção Calendários na referência da API REST e a referência do MCP para pormenores.