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

[]

{}

Parâmetros

[
  {
    "name": "webhook_key",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^[a-f0-9]{48}
quot;
    },
    "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

{
  "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

{
  "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

CanalCompatívelObservação
WhatsApp (Web)Sim
WhatsApp (API oficial)Sim
InstagramSim
MessengerSim
TelegramSim

Eventos que esta rota gera

O que chega no seu webhook (ou em GET /events) depois desta rota.

message.sent: cada mensagem que o fluxo envia (sent_by: automation, automation.flow_id)

{
  "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

{
  "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

{
  "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 · O que funciona em cada canal · O que muda da uazapi