# Webhook público do fluxo POST /chatbot/flows/hook/{webhook_key} Começa o fluxo dono da chave, **sem token**, para sistemas que só sabem mandar um POST para uma URL. Responde `202` na hora com o `run_id`. - **Corpo:** qualquer JSON até 64 KB, ou vazio. Fica em `{{webhook}}`; leia um campo com a operação `json` do bloco `set`. - **Contato:** `?to=` (opcional). Sem ele, o fluxo precisa de um bloco `set_contact`. - **Número não conferido na hora:** a resposta sai antes e sem a conversa. Número fora do WhatsApp aparece como erro na execução (`GET /chatbot/flows/runs/{run_id}`). - **Limite:** 60 começos por minuto por webhook. Quem tem a chave manda mensagens pela inbox: guarde como senha e troque (`POST /chatbot/flows/webhook`) se vazar. ## Autenticação ```json [] ``` ```json {} ``` ## Parâmetros ```json [ { "name": "webhook_key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{48}$" }, "description": "Chave do webhook: o `webhook_key` do fluxo (48 caracteres hexadecimais)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Contato: telefone com DDI, só dígitos. Sem ele, o fluxo roda sem contato até um bloco `set_contact`.", "example": "5511999999999" } ] ``` ## Corpo da requisição ```json { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Qualquer JSON (até 64 KB), lido no fluxo em `{{webhook}}`." }, "example": { "cliente": { "nome": "Ana", "telefone": "5511999999999" }, "pedido": 1234 } } } } ``` ## Respostas ```json { "202": { "description": "Execução começada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowStartResult" }, "example": { "run_id": "rr1b2c3d4e5f6a7", "chat_id": "5511999999999@s.whatsapp.net", "status": "started" } } } }, "400": { "description": "`invalid_request`: o corpo não é JSON. `number_invalid`: `to` não é telefone com DDI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "number_invalid", "message": "`to` não é telefone com DDI." } } } }, "404": { "description": "`not_found`: a chave não existe (errada, trocada ou desligada).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "not_found", "message": "A chave do webhook não existe." } } } }, "409": { "description": "`flow_not_published`: o fluxo nunca foi publicado. `chatbot_disabled`: o chatbot da inbox está desligado. `inbox_not_connected`: veio `to` e a inbox está desconectada do WhatsApp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "flow_not_published", "message": "O fluxo nunca foi publicado." } } } }, "413": { "description": "`payload_too_large`: o corpo passa de 64 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "payload_too_large", "message": "o corpo passa de 64 KB." } } } }, "429": { "description": "`rate_limited`: mais de 60 começos por minuto neste webhook; tente de novo no minuto seguinte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "rate_limited", "message": "mais de 60 começos por minuto neste webhook; tente de novo no minuto seguinte." } } } }, "500": { "description": "Falha inesperada ao gravar ou ler os dados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "internal_error", "message": "Erro interno; tente de novo." } } } }, "503": { "description": "`inbox_unavailable`: a inbox do fluxo não está rodando agora; tente de novo mais tarde.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrkesioError" }, "example": { "error": "inbox_unavailable", "message": "a inbox do fluxo não está rodando agora." } } } } } ``` **Estado:** Disponível ## Compatibilidade de canais | Canal | Compatível | Observação | |---|---|---| | WhatsApp (Web) | Sim | | | WhatsApp (API oficial) | Sim | | | Instagram | Sim | | | Messenger | Sim | | | Telegram | Sim | | ## Eventos que esta rota gera O que chega no seu webhook (ou em `GET /events`) depois desta rota. ### [`message.sent`](/webhook/message.sent): cada mensagem que o fluxo envia (`sent_by: automation`, `automation.flow_id`) ```json { "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H", "type": "message.sent", "created_at": "2026-10-17T12:00:00.000Z", "inbox": { "id": "r0269625d29bfbd", "name": "loja", "phone": "5511888888888", "channel": "whatsapp_web" }, "data": { "message": { "id": "3EB05DCE1D4036FCE241C6", "chat_id": "5511999999999@s.whatsapp.net", "author": { "id": "5511888888888@s.whatsapp.net", "name": "Loja" }, "direction": "out", "sent_by": "automation", "sent_at": "2026-10-17T12:00:00.000Z", "category": "conversation", "type": "text", "text": "Oi, Maria! Como posso ajudar?", "automation": { "flow_id": "rw1b2c3d4e5f6a7" } }, "chat": { "id": "5511999999999@s.whatsapp.net", "lid": "123456789012345@lid", "type": "direct" } } } ``` ## Antes e depois (uazapi → Orkesio) Na uazapi: `POST /chatbot/flows/hook/{key}`. - Mesmo caminho e mesmas funções; muda o formato: campos em `snake_case`, datas em ISO 8601 (`_at`) e erros em `{error, message}`. - Caminho com o id nomeado: `/chatbot/flows/hook/{key}` → `/chatbot/flows/hook/{webhook_key}`. - Contato na query renomeado: `?number=` → `?to=`. A resposta segue sem a conversa (sem `chat_id`). ## #/components/schemas/FlowStartResult ```json { "type": "object", "required": [ "run_id", "status" ], "properties": { "run_id": { "type": "string", "description": "Id da execução; o andamento fica em `GET /chatbot/flows/runs/{run_id}`." }, "chat_id": { "type": "string", "description": "Conversa da execução; vazio quando começou sem `to`. Só no `POST /chatbot/flows/start`: o webhook público não devolve." }, "status": { "type": "string", "enum": [ "started" ], "description": "Sempre `started`: a execução foi aceita e roda em seguida." } } } ``` ## #/components/schemas/OrkesioError ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP." }, "message": { "type": "string", "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`." }, "field": { "type": "string", "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)." } }, "required": [ "error", "message" ], "additionalProperties": true, "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)." } ``` ## Guias relacionados [Visão geral](/docs/overview) · [O que funciona em cada canal](/docs/canais) · [O que muda da uazapi](/docs/o-que-muda)