Roteiros

Como um roteiro começa

• Pelo Quando usar: a IA reconhece o assunto e começa o roteiro.
• Pela palavra-chave: a mensagem que é só a palavra (sem diferença de maiúsculas e acentos) começa o roteiro na hora, sem passar pela IA.
• Um roteiro por conversa. A palavra-chave de outro roteiro, ou a IA começando outro porque a pessoa mudou de assunto, troca o que estava aberto.

No painel: chatbot → aba Roteiros, com 5 modelos prontos (orçamento, pedido de agendamento, troca e devolução, segunda via e rastreio), que também ficam no Catálogo, aba Habilidades, para instalar num chatbot. Roteiro sem ação não precisa de desenvolvedor; o passo de ação faz parte do pacote Integrações.

Passos

Destinos de cada passo, botão ou resultado: o próximo passo, outro passo, encerrar o roteiro ou chamar atendente. A IA nunca pula nem inventa passos.

Passo de ação

Os parâmetros da ação com o mesmo nome de uma variável do roteiro vão preenchidos pelo BoaVoz, com o valor conferido, e a IA nem vê esses parâmetros. O formato é o mesmo em toda ação:

Resultado → destino: ok (2xx), nao_encontrado (404) e erro (o resto: falha, demora ou incerta), mais os resultados que a ação declara no cadastro e devolve em "outcome": "sem_debito". Resultado não declarado segue o destino de erro. Ação que não está disponível na conversa (desativada, sem o pacote, abaixo do nível mínimo) também segue o de erro.

Só no roteiro: marcada no cadastro da ação, a IA só recebe a ação no passo dela, de um roteiro ligado; desligar o roteiro tira a ação junto. Desmarcada, a IA usa a ação sempre que a conversa precisar, com ou sem roteiro.

Identificar a pessoa

A ação do passo pode dizer quem é a pessoa: devolva identity junto do data. Quantos dados pedir para identificar (CPF, CEP de um endereço, data de nascimento) é decisão do seu sistema: o roteiro pede, a sua ação decide.

{
  "data": { "cliente": "Ana Souza", "contas": 2 },
  "identity": {
    "external_id": "cli_123",
    "name": "Ana",
    "accounts": [
      { "label": "Rua das Flores, 10", "context": { "uc": "1001" } },
      { "label": "Av. Brasil, 200", "context": { "uc": "1002" } }
    ]
  }
}

• A identidade só vale vinda do passo de ação de um roteiro em andamento. A do token do site e a do pareamento vencem.
• A conversa fica identificada por 24 horas, já na mesma resposta: as próximas ações recebem contact.level usuario, verified_by routine, o external_id e o display, e context: {source: "routine", data} da conta escolhida.
• Com 2 contas ou mais, o roteiro espera a pessoa escolher pelos botões das contas. Depois, ela troca pedindo (“é sobre a outra conta”).
• Passos de dado e de ação marcados Pular se a pessoa já estiver identificada ficam para trás quando a conversa já tem a pessoa (número lembrado e confirmado, pareamento ou token): use nos dados que servem só para identificar.

Lembrar o número

No WhatsApp e no Instagram, depois da identificação, o BoaVoz pede licença com os botões Lembrar este número e Não lembrar, logo depois da primeira resposta sem botões. Sem a licença, a identificação vale só para a conversa.

• Com o número lembrado, toda conversa nova começa por “Estou falando com Ana?”, com Sim, sou eu e Sou outra pessoa. A mensagem que chegou espera a resposta e é respondida depois. “Sou outra pessoa” esquece o número: o titular pode ter mudado.
• “desconectar” no chat também esquece o número e tira a identificação da conversa.
• A loja pode desligar em Roteiros → Lembrar o número depois da identificação: o BoaVoz deixa de perguntar e esquece os números já lembrados do chatbot. A mesma pergunta vale para quem foi conectado pelo código do pareamento (Confirmar quem foi conectado pelo código, ao lado), mas lá “Sou outra pessoa” não desfaz o vínculo.
• Seu sistema recebe contact.linked com "source": "routine" (um por conta) e contact.unlinked com o motivo (other_person, chat, remember_off…). Veja Webhooks.

Pedir uma foto

• Só no WhatsApp e no Instagram, pela leitura de fotos. No site, ou no modo dados sensíveis (sem leitura de fotos), o passo é pulado.
• O BoaVoz confere se a foto mostra o que o passo pede. Se mostra, o passo anda sozinho e a descrição vai para a variável (e para a ação com um parâmetro do mesmo nome). Se não, conta tentativa (3, como no dado), e a IA pede outra dizendo o que faltou.
• A ação recebe a descrição, não o arquivo. A equipe vê a foto no painel.
• Documento pessoal, cartão, comprovante de pagamento e foto de saúde não são lidos (vão para a equipe com um texto fixo), e o editor recusa o passo que pede esses tipos.
• Cada foto lida conta como uma resposta do atendimento.

Fim do roteiro

Os dados que o roteiro juntou são apagados do BoaVoz no fim; o webhook leva antes.

Webhooks

routine.completed quando o roteiro chega ao fim, e routine.abandoned quando acaba antes, com o reason da tabela acima. Os dois levam o roteiro, a execução (started_by: keyword ou ai; o passo em que acabou) e as variables: os dados que o roteiro juntou, cada um com type e value, no formato que as ações recebem (no abandonado, o que deu tempo de juntar). É o caminho para o seu sistema receber os dados de um roteiro sem ação, como um cadastro.

{
  "id": "evt_q8m2c4…",
  "type": "routine.completed",
  "created_at": "2026-10-19T15:03:12.511Z",
  "bot": { "id": "bot_8c1e…", "name": "Bar do Zé" },
  "client": { "id": "cli_51a0…", "external_id": null },
  "conversation": { "id": "conv_14a2…", "channel": "whatsapp" },
  "contact": { "id": "ctc_77d0…", "whatsapp_user_id": null, "phone": "5511999990000", "instagram_id": null, "display": { "name": "Ana" } },
  "data": {
    "routine": { "id": "rtn_3b9e…", "name": "Segunda via" },
    "run": { "id": "run_7f21…", "started_by": "keyword", "started_at": "2026-10-19T15:01:40.118Z", "ended_at": "2026-10-19T15:03:12.511Z", "step": 2, "steps_total": 3 },
    "variables": {
      "documento": { "type": "cpf", "value": "52998224725" }
    }
  }
}

Limites

• 10 roteiros por chatbot e 12 passos por roteiro.
• 5 palavras-chave por roteiro, de até 3 palavras. Palavras de descadastro, confirmação e atendimento (SAIR, PARAR, STOP, sim, não, ok, cancelar, atendente, menu, oi…) nunca são palavra-chave.
• Botões: de 2 a 10 opções, com até 20 caracteres cada (o limite do WhatsApp e do Instagram).
• 3 tentativas por dado ou foto; 24 horas sem mensagem do contato; 4 mensagens seguidas sem o roteiro andar.