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

# Entrega de eventos

> O blü envia um `POST` com o evento para cada endpoint de webhook ativo
inscrito naquele tipo. Responda com um status `2xx` em até 10 segundos;
entregas que falham são repetidas com intervalos crescentes por até 3 dias.

Confira o cabeçalho `Blu-Signature` antes de confiar no conteúdo. Ele tem
o formato `t=<segundos unix>,v1=<assinatura>`, em que a assinatura é o
HMAC-SHA256 em hexadecimal de `<t>.<corpo bruto da requisição>`, usando o
`secret` do endpoint como chave. Rejeite eventos com `t` de mais de 5 minutos atrás.




## OpenAPI

````yaml /api/openapi.yaml webhook event
openapi: 3.1.0
info:
  title: API do blü
  version: '2026-10-11'
  summary: >-
    Envie e receba mensagens no WhatsApp, faça campanhas e gerencie agentes de
    IA.
  description: >
    A API do blü segue o modelo REST. Ela usa URLs previsíveis e orientadas a

    recursos, recebe corpos de requisição em JSON, devolve respostas em JSON e

    usa códigos de status, autenticação e métodos HTTP padrão.


    ## Vocabulário


    A API usa os mesmos termos do WhatsApp. Um **número** é um número de

    WhatsApp conectado à sua conta. Um **contato** é uma pessoa, única por conta

    e por `wa_id`. Uma **conversa** liga um dos seus números a um `wa_id` e

    reúne as **mensagens** trocadas entre eles. Uma **campanha** envia uma

    mensagem para vários contatos.


    ## Tipos de plataforma


    Os números usam a API do WhatsApp Cloud, da Meta, e são conectados no

    painel do blü. O campo `capabilities` do número informa o que ele permite,

    e a API devolve um `whatsapp_error` com um `code` específico quando a

    requisição não segue uma regra.


    ## Convenções


    - **Ids** são opacos e começam com um prefixo do tipo de objeto, como `pn_`,
    `chat_` ou `msg_`.

    - Todo objeto tem `id`, `object` e `created` (em segundos Unix).

    - `POST` cria e atualiza; `DELETE` exclui. Ações são verbos no recurso,
      como `POST /v1/broadcasts/{id}/send`.
    - **Listas** são paginadas por cursor com `limit`, `starting_after` e
      `ending_before`, e devolvem um objeto de lista com `has_more`.
    - **Expansão**: campos que guardam um id podem ser trocados pelo objeto
      completo com `expand[]`, como `expand[]=contact` em uma conversa.
    - **Idempotência**: envie o cabeçalho `Idempotency-Key` em qualquer `POST`
      para repetir a requisição com segurança. As chaves ficam guardadas por 24 horas.
    - **Versionamento**: o cabeçalho `Blu-Version` escolhe a versão da API. Sem
      ele, vale a versão fixada na sua conta no primeiro uso.
    - **Metadados**: contatos, conversas, mensagens, campanhas e endpoints de
      webhook aceitam até 50 pares de chave e valor seus, em texto.
  contact:
    name: blü
    url: https://blu.direct/api
servers:
  - url: https://api.blu.direct
security:
  - secretKey: []
tags:
  - name: Conta
    description: A conta à qual sua chave de API pertence.
  - name: Números
    description: Números de WhatsApp conectados à sua conta e a conexão deles.
  - name: Contatos
    description: Pessoas com quem você conversa, únicas por conta e por `wa_id`.
  - name: Conversas
    description: Conversas entre um dos seus números e um `wa_id`.
  - name: Mensagens
    description: Mensagens enviadas e recebidas em uma conversa.
  - name: Mídia
    description: Arquivos usados em mensagens, campanhas e modelos.
  - name: Etiquetas
    description: Etiquetas que organizam contatos e definem o público de campanhas.
  - name: Modelos de mensagem
    description: >-
      Mensagens reutilizáveis. Obrigatórias em números `cloud_api` fora da
      janela de atendimento.
  - name: Campanhas
    description: Uma mensagem enviada para vários contatos, com intervalos entre os envios.
  - name: Agentes
    description: Agentes de IA que respondem às conversas.
  - name: Eventos
    description: Acontecimentos na sua conta, também enviados aos endpoints de webhook.
  - name: Endpoints de webhook
    description: URLs que recebem eventos.
paths: {}
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: |
        Autentique com uma chave secreta (`sk_live_…`) ou uma chave restrita
        (`rk_live_…`) criada no painel. Chaves restritas só têm as permissões
        escolhidas na criação, como `messages:send`, `chats:read` ou
        `broadcasts:send`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.