> ## Documentation Index
> Fetch the complete documentation index at: https://developer.wabox.me/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Wabox é uma API não-oficial de WhatsApp (aparelho vinculado). Tudo é snake_case; a base é https://api.wabox.me/instances/{instance_id}/token/{token}.
> Envios respondem { id, message_id, wabox_id, status: "queued" } na hora; o resultado real chega no webhook delivery. Envios não são idempotentes: confira GET /queue antes de repetir.
> Sempre verifique X-Wabox-Signature (HMAC-SHA256 de "<t>.<corpo cru>") nos webhooks e deduplique por event_id.
> Botões, listas, carrossel e catálogo são best effort e não renderizam no WhatsApp Web/Desktop. Não existem: chamadas, listas de transmissão, histórico de mensagens, instância mobile.
> Não invente endpoints ou campos: use o OpenAPI em https://api.wabox.me/openapi.json.

# Typebot

> Envie mensagens pelo Wabox a partir de um fluxo do Typebot e entenda o que é preciso para receber mensagens do WhatsApp nele.

Há dois cenários, e eles são bem diferentes:

* **Enviar** uma mensagem de WhatsApp a partir de um fluxo do Typebot: funciona direto, com o bloco de requisição HTTP chamando o `send-text`.
* **Receber** mensagens do WhatsApp dentro de um fluxo do Typebot: exige um intermediário, porque o Typebot não recebe webhooks arbitrários.

<Note>
  Base das rotas: `https://api.wabox.me/instances/{instance_id}/token/{token}` (credenciais no dashboard › instância). O header `Client-Token` só é necessário se estiver ativado no workspace ([Client-Token](/security/client-token)).
</Note>

## Enviar mensagem a partir do fluxo

Use o bloco de requisição HTTP do Typebot — dependendo da versão ele aparece como **HTTP request** ou **Webhook** no painel de blocos de integração; é o mesmo bloco.

<Steps>
  <Step title="Colete o telefone em uma variável">
    Antes do bloco HTTP, tenha o número em uma variável do fluxo (por exemplo `{{Telefone}}`), só dígitos com DDI e DDD: `5511988887777`. O Typebot tem um bloco de entrada de telefone; remova `+`, espaços e traços antes de enviar, ou use `phone-exists` para validar — veja [Identificadores](/guides/identifiers).
  </Step>

  <Step title="Configure o bloco HTTP">
    * **Método**: `POST`
    * **URL**: `https://api.wabox.me/instances/{instance_id}/token/{token}/send-text`
    * **Headers**: `Content-Type: application/json` e, se ativado, `Client-Token`
    * **Body** (JSON), usando as variáveis do fluxo:

    ```json theme={"system"}
    {
      "phone": "{{Telefone}}",
      "message": "Olá {{Nome}}, recebemos seu pedido. Já já retornamos por aqui."
    }
    ```

    Execute o teste do bloco para conferir a resposta.
  </Step>

  <Step title="Salve o id da mensagem (opcional)">
    A resposta é:

    ```json theme={"system"}
    { "id": "3EB0A9C6D2F1E4B5A7D0", "message_id": "3EB0A9C6D2F1E4B5A7D0", "wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01", "status": "queued" }
    ```

    Na opção do bloco que salva campos da resposta em variáveis, aponte `message_id` (ou `id`, que é alias) para uma variável se você for cruzar com o webhook [delivery](/webhooks/delivery) depois. `status: "queued"` indica que a mensagem entrou na fila; o resultado do envio chega no `delivery`.
  </Step>
</Steps>

<Tip>
  Mensagens com botões e listas (`send-button-list`, `send-option-list`) também podem ser disparadas do mesmo bloco, mas nem todo cliente do WhatsApp renderiza esses formatos. Confira [O que renderiza onde](/guides/rendering-support) antes de usar.
</Tip>

## Receber mensagens do WhatsApp no Typebot

O Typebot executa fluxos a partir da própria interface de chat (ou da integração nativa dele com a API oficial do WhatsApp). Ele não expõe uma URL genérica em que o Wabox possa postar o webhook `received` e ver o fluxo avançar. Para conversar com um Typebot via Wabox, você precisa de um intermediário que faça três coisas:

1. Receber o webhook `received` do Wabox.
2. Falar com a API de chat do Typebot (os endpoints que iniciam uma sessão e continuam uma sessão existente com a mensagem do usuário), mantendo a sessão por telefone.
3. Enviar cada resposta do Typebot de volta pelo `send-text` (ou pela rota do tipo de conteúdo correspondente).

Esse intermediário pode ser um workflow no [n8n](/integrations/n8n) ou no [Make](/integrations/make), ou um backend seu ([integração HTTP genérica](/integrations/http)).

<Steps>
  <Step title="Configure o webhook received">
    Aponte `received_url` da instância para o intermediário:

    ```bash theme={"system"}
    curl -X PUT "https://api.wabox.me/instances/{instance_id}/token/{token}/webhooks" \
      -H "Content-Type: application/json" \
      -d '{ "received_url": "https://SEU-INTERMEDIARIO/wabox" }'
    ```

    Responda `2xx` em até 10 s e ignore eventos com `from_me: true` ou sem `text` — veja [Webhook received](/webhooks/received).
  </Step>

  <Step title="Mapeie telefone → sessão">
    Guarde, por `phone`, o id da sessão devolvido pelo Typebot ao iniciar o chat. Na próxima mensagem daquele número, continue a sessão em vez de iniciar outra. Sessões expiram no Typebot; ao receber erro de sessão inexistente, inicie uma nova.
  </Step>

  <Step title="Devolva as respostas pelo Wabox">
    A API de chat do Typebot responde com a lista de mensagens do bot (texto, imagem, etc.) e, quando o fluxo espera uma entrada, o tipo de entrada esperado. Para cada mensagem de texto, chame `send-text` com o `phone` do cliente; para imagens, `send-image`, e assim por diante. Se o fluxo pedir uma escolha entre opções, você pode mandá-las como texto numerado ou como `send-option-list`, e mapear a resposta do cliente de volta para a opção.
  </Step>
</Steps>

<Warning>
  Cada mensagem do cliente vira uma chamada ao Typebot e uma ou mais chamadas de envio. Trate o `429` da API (com `Retry-After`) e o `409 instance_not_connected` no intermediário — veja [Rate limit e erros](/guides/rate-limits-and-errors). E deduplique por `event_id`: em caso de reentrega, o mesmo evento chega mais de uma vez.
</Warning>