VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: fluxos do bot

Testar um fluxo

Simula uma conversa num fluxo e descobre para onde uma mensagem real cairia.

Antes de ativar (ou quando o bot "não responde"), use estas duas rotas. A simulação roda o fluxo que você escolher com uma mensagem fictícia. A sonda diz qual fluxo a plataforma escolheria para um telefone real.

Simular uma conversa

Roda uma rodada do fluxo com uma mensagem de cliente fictícia e devolve tudo o que o bot responderia. Nada é enviado à Meta e nenhum cliente real é afetado. Cada chamada é uma mensagem: para uma conversa de várias falas, chame de novo com o mesmo phone_number.

POST/api/v1/admin/whatsapp/flows/{id}/simulateAdmin

Simula uma mensagem de cliente num fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Corpo da requisição

user_messagestring
Texto que o cliente fictício envia. Use este, ou button_id, ou list_reply_id, ou form_payload.
button_idstring
Id do botão tocado (por exemplo option_0). Tem prioridade sobre os demais campos.
list_reply_idstring
Id da linha de lista escolhida.
form_payloadobject
Respostas de um formulário, enviadas ao bot como texto JSON.
phone_numberstring
Telefone sintético. A plataforma o coloca sempre no espaço +sim- e acrescenta um sufixo do seu usuário, para dois administradores não se misturarem. Omitido, usa um derivado do fluxo.
reset_sessionbooleanpadrão: false
true descarta a sessão sintética e começa do bloco inicial.

Exemplo de requisição (Simular uma conversa)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/flows/fa4b0c91-2883-43c6-94ef-86e5b540a2aa/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "oi",
    "reset_session": true
  }'

Resposta (Simular uma conversa)

200Rodada simulada
json
{
  "session_id": "0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10",
  "phone_number": "+sim-fa4b0c91-a1a25b87",
  "events": [
    {
      "kind": "inbound",
      "at": "2026-10-11T14:40:00.100Z",
      "text": "oi",
      "payload": {
        "user_message": "oi"
      }
    },
    {
      "kind": "state_change",
      "at": "2026-10-11T14:40:00.090Z",
      "text": "session created",
      "payload": {
        "session_id": "0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10",
        "state": "active",
        "current_block_id": "5cf73b43-5e23-480c-8037-7a7385251a22"
      }
    },
    {
      "kind": "outbound",
      "at": "2026-10-11T14:40:00.300Z",
      "text": "Oi! Bem-vindo à nossa loja.",
      "payload": {
        "kind": "send_text",
        "body": "Oi! Bem-vindo à nossa loja."
      }
    },
    {
      "kind": "state_change",
      "at": "2026-10-11T14:40:00.310Z",
      "text": "waiting for input",
      "payload": {
        "state": "waiting_for_input"
      }
    }
  ]
}

Campos da resposta

session_iduuid
Sessão sintética usada. Estável entre chamadas para o mesmo telefone sintético, até você pedir reset_session.
phone_numberstring
Telefone sintético (sempre começa com +sim-). Reenvie-o para continuar a mesma conversa.
eventsarray

Eventos desta rodada, em ordem.

kindstring
inboundoutboundstate_changeflow_transitionerror
Tipo do evento.
atstring
Momento do evento (RFC 3339).
textstring
Texto legível do evento.
payloadobject
Dados do evento. Nos outbound é a ação do bot: kind (send_text, send_media, send_cta_url, send_buttons, send_list, wait_for_input, complete, handoff_to_human), body, media_url, buttons, items.

Erros (Simular uma conversa)

StatusQuandoCorpo
400Corpo que não é JSON, fluxo inexistente, ou fluxo sem start_block_id.{"error":"whatsapp/simulator: flow ... has no start_block_id"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Erros do bot aparecem como evento

Se um bloco estiver mal configurado, a resposta continua sendo 200 e traz um evento error no transcript. Olhe sempre os eventos.

Deixa rastro

A simulação cria uma sessão (com telefone +sim-) que aparece na lista de sessões. Ela nunca é usada por clientes reais.

Sondar o caminho real de uma mensagem

Responde à pergunta "se este telefone escrevesse agora, o que o bot faria?", olhando as conversas e sessões reais. Só lê: não grava, não responde ao cliente e não fala com a Meta. A simulação acima roda o fluxo que você escolher; a sonda mostra qual fluxo (ou sessão) a plataforma escolheria sozinha.

GET/api/v1/admin/whatsapp/inbound-probeAdmin

Mostra para onde uma mensagem de um telefone cairia

Parâmetros de consulta

phonestringobrigatório
Telefone do cliente. Obrigatório. Só os dígitos importam.
textstring
Texto da mensagem hipotética.
vendor_iduuid
Seller. Omitido, usa o da conversa do telefone.

Exemplo de requisição (Sondar uma mensagem)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/inbound-probe?phone=5511999990000&text=oi" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Sondar uma mensagem)

200Sem fluxo para a mensagem
json
{
  "phone": "5511999990000",
  "body": "oi",
  "bot_enabled": true,
  "verdict": "nenhum flow casa: a mensagem cai no atendimento por LLM, sem flow",
  "session_stale": false,
  "warnings": [
    "sem flow inbound_default ativo para este vendedor"
  ]
}

Campos da resposta

phonestring
O telefone consultado.
bodystring
O texto consultado.
vendor_iduuid
Seller da conversa encontrada, ou o enviado. Ausente quando não há.
thread_iduuid
Conversa encontrada para o telefone. Ausente quando não há.
bot_enabledboolean
false quando o bot está desligado nessa conversa: nenhuma resposta automática sai.
verdictstring
Frase em português dizendo o que aconteceria com a mensagem.
session_iduuid
Sessão ativa encontrada, se houver.
session_flow_iduuid
Fluxo da sessão encontrada.
session_block_namestring
Bloco em que a sessão está.
session_statestring
Estado da sessão encontrada.
session_expires_atstring
Quando a sessão vence (RFC 3339).
session_staleboolean
Hoje sempre false: uma sessão vencida é abandonada e recriada na próxima mensagem.
trigger_flow_iduuid
Fluxo que atenderia uma sessão nova.
trigger_flow_namestring
Nome desse fluxo.
warningsarray
Avisos sobre o que está torto, mesmo que a mensagem seja respondida.

Erros (Sondar uma mensagem)

StatusQuandoCorpo
400phone ausente.{"error":"telefone obrigatório"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Use quando o bot não responde

Os motivos mais comuns aparecem aqui: bot desligado na conversa (bot_enabled: false), nenhum fluxo inbound_default ativo, ou fluxo sem bloco inicial. O texto de verdict e de warnings é devolvido em português.

Telefone sem conversa

Se o telefone nunca escreveu, não há conversa: a sonda usa só o vendor_id que você enviou (ou nenhum) para achar o fluxo do gatilho.

Veja também

  • Sessões
  • Ler fluxos
Anterior
Ligações
Próxima
Sessões de fluxo
Nesta página
  • Simular uma conversa
  • Exemplo de requisição (Simular uma conversa)
  • Resposta (Simular uma conversa)
  • Erros (Simular uma conversa)
  • Sondar o caminho real de uma mensagem
  • Exemplo de requisição (Sondar uma mensagem)
  • Resposta (Sondar uma mensagem)
  • Erros (Sondar uma mensagem)
  • Veja também