Jornadas: disparar para uma lista com acompanhamento

Uma jornada é o roteiro reutilizável de um disparo de WhatsApp por template. Ela reúne, num lugar só, o que acontece com cada lead depois da primeira mensagem:

• de qual número a mensagem sai e qual agente conversa com quem responder;
• a primeira mensagem: um template aprovado do número;
• o acompanhamento: mensagens automáticas para quem não respondeu;
• os resultados possíveis da conversa, que o agente ou o atendente escolhem no fim (a disposição), cada um com os campos que ele guarda;
• o que a lista de leads precisa trazer, e quanto tempo esperar antes de procurar o mesmo lead de novo.

Cada lead chega com o ID dele no seu sistema (external_lead_id), e cada passo vira um evento com esse ID, que você exporta por dia. É o que liga a conversa no WhatsApp ao resultado no seu sistema.

O disparo sem jornada continua existindo (veja Outbound): você escreve a mensagem na hora, sem acompanhamento e sem disposição. Use uma jornada quando o mesmo roteiro vai rodar para várias listas e você precisa do resultado lead a lead.

Criar uma jornada

Em Administração → Jornadas, clique em + Nova jornada. O formulário tem seis blocos. A seção Configuração completa mostra os mesmos dados no formato que a Aura e a API usam.

Básico

• Nome da jornada: é por ele que você e a Aura se referem à jornada.
• Número: só números da conta oficial (Cloud API ou Twilio). Um número conectado por QR Code aparece na lista, mas desabilitado, porque disparo não sai por conexão não oficial.
• Agente: quem conversa com os leads desta jornada. Com jornada, é sempre este agente que responde, e não o agente padrão do número.

Primeira mensagem

• Template: escolhido da lista de templates aprovados do número. O idioma e a categoria vêm do próprio template. Jornada é sempre por template; texto livre só sai em disparo sem jornada feito pela Aura. Se o número ainda não tem template aprovado, crie um em Canais → o número → Templates (veja Templates do WhatsApp).
• Variáveis do corpo: cada variável do corpo do template vem de uma coluna da lista de leads (por exemplo, {{1}} ← nome). Cabeçalho e botões do template não têm variável: são fixos.

A prévia do texto mostra o corpo do template escolhido.

Acompanhamento (opcional)

Mensagens automáticas para quem não respondeu (cadence). São até 10 passos (steps), e cada um tem:

• depois de quantas horas do envio anterior (delay_hours, de 1 a 2.160) ele sai. O 1º passo conta a partir da primeira mensagem, e os seguintes a partir do passo anterior;
• o template do passo, também da lista de aprovados do número, com as variáveis dele.

O acompanhamento de um lead para sozinho quando ele responde, quando pede para sair, ou quando a conversa é encerrada.

Resultados da conversa

• Resultados (disposition.codes): a lista fechada de como uma conversa desta jornada pode terminar, por exemplo <resultado-positivo> ou <resultado-negativo>. É no mínimo 1 e no máximo 30 resultados, com até 48 caracteres no nome de cada um. Quem escolhe os nomes é você.
• Campos do resultado (fields): dados que a conversa precisa registrar junto com o resultado, por exemplo o motivo de uma recusa. São até 10 campos por resultado. Veja os tipos de campo.

Quatro nomes são reservados e não podem ser cadastrados: no_response, abandoned, undetermined e opt_out. A plataforma os preenche sozinha. Veja quando cada um aparece.

Encerramento

Encerrar sozinha após quantas horas sem resposta (auto_close): de 1 a 2.160 horas. Quando o lead não responde, a conversa é encerrada depois desse prazo, contado da última mensagem enviada a ele (a primeira ou um passo do acompanhamento), com o resultado no_response. Escolha um prazo maior que o intervalo do último passo, para o acompanhamento sair inteiro.

Com o campo vazio, a jornada não tem prazo próprio e vale o tempo de sessão do número, configurado em Canais.

Depois de encerrada

Quando o atendimento daquele lead é encerrado, o que acontece se ele voltar a escrever? A jornada decide, no campo Se o cliente escrever depois de encerrada, com duas opções:

Opção	O que acontece
O agente atende de novo, com o histórico (padrão)	O cliente que escreve abre um atendimento novo, e o agente já sabe do atendimento anterior.
Responder sempre com esta mensagem	O cliente recebe o texto que você configurou, sem abrir atendimento e sem chamar o agente.

A segunda opção serve para números que só existem para aquela jornada — por exemplo, um número que só encaminha o cliente para outro canal. No texto, escreva o que a pessoa deve fazer dali em diante; o campo é obrigatório, com até 1.000 caracteres e até 10 quebras de linha.

Como o texto fixo funciona:

• a resposta sai, no máximo, uma vez a cada 60 minutos para o mesmo contato — o intervalo vem da configuração da jornada e a tela mostra qual é na descrição da opção: de 1 minuto a 24 horas. As mensagens seguintes dentro dessa janela ficam registradas na conversa e não recebem resposta;
• a resposta não usa o agente e não abre atendimento: a mensagem do cliente e a resposta ficam na conversa já encerrada, marcadas como "após encerramento", fora da fila do Atendimento e fora da contagem de "aguardando resposta". Na tela, a resposta aparece rotulada "RESPOSTA FIXA", para não ser confundida com uma fala do agente;
• vale para conversa encerrada por qualquer caminho — pela atendente, pelo próprio agente ou automaticamente (pela leitura do resultado ou pelo encerramento por inatividade) — e só quando a mensagem chega no número que fez o disparo;
• o campo só aparece em jornada que usa WhatsApp (no primeiro contato ou em algum passo); numa jornada só de voz ele não existe;
• um novo disparo da jornada para aquele contato volta ao funcionamento normal: o cliente é atendido pelo agente como qualquer outro.

Lista de leads

• ID do lead: a lista precisa de uma coluna chamada exatamente external_lead_id. O nome é fixo e não se configura.
• Atributos obrigatórios: até 30 colunas que a lista precisa ter para a jornada aceitar o lead, com até 64 caracteres no nome de cada uma.
• Atributos no relatório (export.attributes, opcional): até 20 colunas da lista que vão para o relatório de eventos, com até 64 caracteres no nome de cada uma.
• Não mandar de novo para o mesmo lead antes de quantas horas: de 0 a 2.160 horas (90 dias). Vale para todas as jornadas da organização: um lead procurado por uma jornada espera esse prazo antes de entrar em outra.

A janela de horário de contato não é da jornada: ela fica nas regras de contato do Outbound.

Ao salvar, a jornada fica ativa. Cada edição guarda quem editou e quando; o histórico aparece no detalhe da jornada.

A lista de leads

A lista é um .csv com cabeçalho: o telefone, o external_lead_id, os atributos obrigatórios e as colunas que as variáveis do template usam.

telefone;external_lead_id;nome;protocolo
19991234567;lead-001;Ana Paula;A-1029
21988887777;lead-002;Bruno;A-1030

• A coluna de ID precisa se chamar exatamente external_lead_id. Uma coluna de ID com outro nome (id, lead_id, external_reference_id) faz a lista ser recusada, em vez de o envio sair sem jornada.
• Um lead com o ID vazio não entra.
• Um lead sem um atributo obrigatório, ou sem o valor de uma variável do template, fica pulado, e os demais seguem normalmente.
• Um lead que ainda está na fila de outro disparo com jornada da organização não entra de novo até sair dessa fila.
• Um lead dentro do prazo de "não mandar de novo" fica de fora.
• Um lead bloqueado pelo ID fica de fora. O bloqueio acontece quando ele pede para sair, ou quando você bloqueia o ID pela API ou pela Aura.
• Um telefone na lista de não perturbe nunca entra.

O que o agente já sabe quando o lead responde

Quando o lead responde, o agente recebe todas as colunas da linha dele no CSV — não só as que o template usou — e o texto da última mensagem enviada a ele. Assim ele continua a conversa sabendo o que estava na sua lista, mesmo que o template não mostrasse aquilo: o plano, o vencimento, o protocolo.

Um exemplo e os tetos dessa passagem estão em Outbound — Quando o contato responde.

Disparar com jornada

Pela tela

No Novo disparo, o passo Destinatários tem a escolha da jornada, ou Sem jornada (disparo avulso). Com uma jornada escolhida:

• a tela mostra o acompanhamento e o encerramento dela, e a lista de colunas que ela espera no CSV, marcando as que faltam;
• o passo não avança sem a coluna external_lead_id ou sem um atributo obrigatório;
• o número, o agente e o template vêm da jornada.

Jornada padrão do número

Quando um número tem uma única jornada ativa, ela vira a padrão do número (selo "padrão do número" na lista de jornadas). Um disparo feito pela tela sem escolher jornada, por esse número, usa a jornada padrão, mas só quando a lista traz a coluna external_lead_id. Para disparar sem jornada por esse número, tire essa coluna da lista.

Com duas ou mais jornadas ativas no mesmo número, nenhuma é padrão. A lista mostra o aviso "Sem padrão para este número — há mais de uma jornada ativa", e um disparo sem jornada escolhida sai sem jornada.

A mensagem individual que a Aura ou uma tarefa agendada manda nunca cai na jornada padrão.

Pela API

O seu sistema pode carregar leads direto numa jornada, até 1.000 por chamada, com a mesma chave pak_… da API pública. Veja Jornadas: carregar leads.

Acompanhar

O detalhe do disparo mostra a tabela de contatos e, quando o disparo tem jornada, o bloco Acompanhamento, com os passos pendentes, enviados e com falha. Três ações valem só para o acompanhamento, sem mexer no disparo:

• Pausar acompanhamento e Retomar acompanhamento. A pausa é para algumas horas: depois de 72 horas pausado, cada passo atrasado é cancelado sozinho.
• Cancelar acompanhamento pendente, que cancela todos os passos que ainda não saíram.

Resultados da conversa

Toda conversa de jornada termina com um resultado, a disposição.

• O agente escolhe o resultado sozinho quando a conversa chega a um desfecho, sempre da lista da jornada, e preenche os campos dele. Ele recebe a lista e os campos a cada conversa, sem você precisar colar no prompt.
• O atendente, quando assume a conversa pela tela de Atendimento, escolhe o resultado no fim. Ao clicar em Encerrar atendimento, a janela traz o bloco de resultado, com os campos do resultado escolhido. O resultado começa vazio, e sem escolha este atendimento fica registrado como undetermined. Encerrar atendimento fecha a conversa de vez: o cliente que escrever depois abre um atendimento novo, com o resumo do anterior (veja Depois de encerrada e Atendimento humano). Para manter a conversa com o agente, use Devolver ao agente.

Escolher de novo substitui o resultado anterior. O que vale é sempre o último, e o histórico fica nos eventos.

O agente precisa das ferramentas de conversa

É com as ferramentas de conversa e sessão que o agente registra o resultado e o pedido de saída. Um agente montado sem elas conversa normalmente, mas não registra resultado nem tira o lead da lista sozinho.

Campos do resultado

Cada campo (fields[]) tem uma chave (key), um tipo (type) e, se quiser, required: true:

Tipo	O que aceita	Atributos extras
picklist	Uma opção de uma lista fechada.	options: de 1 a 50 opções, até 64 caracteres cada. Obrigatório neste tipo.
text	Texto de até 120 caracteres, sem caracteres de controle ou formatação.	Nenhum.
integer	Número inteiro.	min e max, opcionais.
decimal	Número com casas decimais, guardado com 2 casas.	min e max, opcionais, e unit (até 8 caracteres, como a moeda).
date	Data no formato AAAA-MM-DD.	Nenhum.

A key começa com letra minúscula e segue com letras minúsculas sem acento, dígitos ou _, até 40 caracteres. Um atributo que não pertence ao tipo (options num text, unit num integer) é recusado ao salvar. Os campos de tipo text podem carregar dado pessoal: veja o aviso em Relatórios da jornada.

Registrar o resultado

Quem registra o resultado de uma conversa é o agente ou o atendente humano, pela tela de Atendimento. Só os resultados cadastrados na jornada podem ser escolhidos; os chamados reservados são registrados apenas pela própria plataforma.

Quem registrou fica guardado junto do resultado, e aparece no relatório da jornada na coluna actor_type.

Quando ninguém escolhe o resultado

Se a conversa encerra sem resultado, a plataforma preenche um automático:

Resultado	Quando
no_response	A conversa encerrou sozinha, por prazo ou inatividade, e o lead nunca respondeu.
abandoned	A conversa encerrou sozinha depois de o lead responder, ou de passar por um atendente.
undetermined	O agente ou o atendente encerrou a conversa sem escolher um resultado.
opt_out	O lead pediu para sair.

Um resultado já escolhido nunca é trocado por um automático. Quando o automático é undetermined, a plataforma ainda lê a conversa depois do encerramento (auto_disposition). Se ela mostrar com clareza um dos resultados da jornada, esse resultado passa a valer, e o evento registra que veio da avaliação automática (actor_type = auto_disposition). O grau de certeza exigido (confidence_threshold, acima de 0 e até 1, padrão 0,8) é uma escolha da jornada.

Quando o lead pede para sair

Numa conversa de WhatsApp, o agente registra o pedido de saída com as palavras que o lead usar ("não quero mais receber isso", "para de me mandar mensagem"), e não só com as palavras exatas da lista de não perturbe. No mesmo instante, a plataforma:

• põe o telefone na lista de não perturbe;
• bloqueia o ID do lead;
• cancela o acompanhamento pendente;
• encerra a conversa.

Eventos por lead

Cada acontecimento vira um evento com o external_lead_id, a jornada, o disparo, a conversa e o horário. São os mesmos eventos que saem no relatório, e a lista completa — o que cada um significa e as colunas que cada tipo carrega — está em Arquivo de eventos.

Exportar e agendar o relatório

Os eventos saem pela Aura, e só para administradores da organização, porque o relatório tem dados de todos os leads:

Exporte os eventos da jornada Boas-vindas de ontem em CSV.

A Aura devolve um arquivo para baixar (csv, jsonl ou parquet) — os mesmos formatos de Relatórios da jornada. As colunas dos dois arquivos (eventos e mensagens) estão em Relatórios da jornada.

Para receber todo dia, peça o agendamento:

Todo dia às 7h, gere o relatório de eventos da jornada Boas-vindas.

O relatório agendado gera os dois arquivos do dia anterior.

O dia do relatório é contado no fuso da organização, e o arquivo de um dia que ainda não fechou vem marcado como parcial. Os detalhes estão em Dia no fuso da organização e arquivo parcial.

Configuração completa

A Aura e a API descrevem a jornada num bloco config, com a mesma estrutura do formulário:

{
  "version": 2,
  "cadence": {
    "steps": [
      {
        "delay_hours": 24,
        "template": {
          "name": "<nome-do-template>",
          "language": "<idioma>",
          "variables": { "1": "<coluna-da-lista>" }
        }
      }
    ],
    "max_followups": 2
  },
  "disposition": {
    "codes": [
      {
        "name": "<resultado-com-campos>",
        "fields": [
          { "key": "<campo-de-lista>", "type": "picklist", "options": ["<opcao-1>", "<opcao-2>"], "required": true },
          { "key": "<campo-numerico>", "type": "decimal", "unit": "<moeda>", "min": 0 },
          { "key": "<campo-de-data>", "type": "date" }
        ]
      },
      { "name": "<resultado-sem-campos>" }
    ]
  },
  "auto_close": { "inactivity_hours": 72 },
  "auto_disposition": { "confidence_threshold": 0.8 },
  "after_close": { "mode": "fixed_reply", "message": "<texto>", "cooldown_minutes": 60 },
  "export": { "attributes": ["<coluna-da-lista>"] }
}

Bloco	O que é	Obrigatório
cadence.steps[].delay_hours	Horas depois do envio anterior.	Em cada passo
cadence.max_followups	Quantos passos saem, de 0 a 10. Padrão 2.	Não
disposition.codes[].fields[]	Os resultados e os campos de cada um.	Os resultados, sim
auto_close.inactivity_hours	Encerramento por falta de resposta.	Não
auto_disposition.confidence_threshold	Certeza mínima da leitura automática.	Não
after_close.mode	agent_again (o padrão) ou fixed_reply — o que fazer quando o cliente escreve depois de encerrada.	Não
after_close.message	O texto da resposta fixa. Obrigatório em fixed_reply, até 1.000 caracteres e 10 quebras de linha.	Em fixed_reply
after_close.cooldown_minutes	Com que frequência, no máximo, a resposta fixa sai para o mesmo contato: de 1 a 1.440 minutos. Padrão 60.	Não
export.attributes	Colunas da lista que vão para o relatório.	Não

Só os nomes acima são aceitos: um nome desconhecido ou fora do tipo é recusado ao salvar, com o caminho do problema (por exemplo, config.disposition.codes.0.fields.1.key).

Pela Aura

Tudo o que a tela de jornadas faz também sai conversando com a Aura, para administradores: listar, ver com o histórico, criar, editar e arquivar jornadas. Ela também confere uma lista contra uma jornada antes do envio, acompanha os disparos, pausa, retoma ou cancela o acompanhamento, e bloqueia um lead pelo ID. O disparo em si sai pela tela ou pela API.

Arquivar

Arquivar tira a jornada das listas ativas sem apagar nada: os eventos e o histórico continuam, só para leitura. Disparos sem jornada escolhida param de usá-la como padrão do número. Não há como desarquivar: para voltar a usar, crie uma jornada nova. Uma jornada arquivada também para de responder com o texto fixo de "depois de encerrada".

Limitações

• Um número, uma jornada padrão. Com duas ou mais jornadas ativas no mesmo número, nenhuma é aplicada sozinha: escolha a jornada no disparo.
• Template de marketing não chega a todos. A Meta deixa de entregar templates de marketing para uma pequena parcela dos números (cerca de 1%), que participa de um experimento dela. O envio aparece como falha, e templates de utilidade não são afetados.
• Arquivar não tem volta. Uma jornada arquivada fica só para leitura.