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

# Configurar Webhook

> Receba eventos em tempo real da sua instância via Webhook.

# Webhook da Instância

Gerencie a configuração para receber notificações de mensagens, conexões e outros eventos em tempo real no seu servidor.

## 🧪 Ferramentas de Teste

Antes de integrar, recomendamos testar o recebimento dos dados. Utilize uma dessas ferramentas para inspecionar o payload:

<CardGroup cols={3}>
  <Card href="https://webhook.cool/" title="Webhook.cool">
    <img src="https://icons.duckduckgo.com/ip3/webhook.cool.ico" width="40" className="mb-4" />

    **Recomendado.** Sem rate limit e interface super limpa.
  </Card>

  <Card href="https://svix.com/play" title="SVIX">
    <img src="https://icons.duckduckgo.com/ip3/svix.com.ico" width="40" className="mb-4" />

    Boa alternativa. Confiável e com baixo rate limit.
  </Card>

  <Card href="https://webhook.site/" title="Webhook.site">
    <img src="https://icons.duckduckgo.com/ip3/webhook.site.ico" width="40" className="mb-4" />

    Evite se possível. Possui rate limits muito agressivos.
  </Card>
</CardGroup>

***

## 🚀 Modo Simples (Recomendado)

Esta é a forma mais fácil de configurar. O sistema gerencia automaticamente um único webhook por instância, criando ou atualizando conforme necessário.

**Regras:**

1. Não inclua `action` nem `id` no payload.
2. Sempre use filtros para evitar loops infinitos.

<Warning>
  **Prevenção de Loops**

  Se você utiliza automações, **sempre** inclua `"excludeMessages": ["wasSentByApi"]`. Isso impede que mensagens enviadas pelo seu próprio robô disparem novos eventos, criando um loop infinito.
</Warning>

### Exemplo de Payload

```json theme={null}
{
  "url": "[https://meusite.com/webhook](https://meusite.com/webhook)",
  "events": [
    "messages",
    "connection"
  ],
  "excludeMessages": [
    "wasSentByApi"
  ]
}
```

***

## ⚙️ Modo Avançado

Utilize este modo apenas se precisar registrar **múltiplos webhooks** para a mesma instância (ex: um webhook para mensagens e outro para status de conexão).

<Tip>
  **Dica Pro:** Mesmo precisando de múltiplos endpoints, considere usar o recurso de **Parâmetros de URL** (veja no final da página) com o Modo Simples. É mais fácil de manter.
</Tip>

### Gerenciamento Manual

Para controlar múltiplos webhooks, você deve enviar o campo `action`.

<CodeGroup>
  ```json Criar (Add) theme={null}
  {
    "action": "add",
    "url": "[https://api.site.com/webhook-1](https://api.site.com/webhook-1)",
    "events": ["messages"]
    // O sistema gera um ID automaticamente
  }
  ```

  ```json Atualizar (Update) theme={null}
  {
    "action": "update",
    "id": "ID_DO_WEBHOOK", // Obrigatório
    "url": "[https://api.site.com/nova-url](https://api.site.com/nova-url)",
    "events": ["messages", "call"]
  }
  ```

  ```json Deletar (Delete) theme={null}
  {
    "action": "delete",
    "id": "ID_DO_WEBHOOK" // Apenas o ID é necessário
  }
  ```
</CodeGroup>

***

## Eventos Disponíveis

Selecione quais tipos de notificação você deseja receber no array `events`.

<AccordionGroup>
  <Accordion title="Mensagens e Conversas" icon="message">
    | Evento            | Descrição                                          |
    | :---------------- | :------------------------------------------------- |
    | `messages`        | Novas mensagens recebidas.                         |
    | `messages_update` | Atualização de status (entregue, lido) ou edição.  |
    | `history`         | Recebimento do histórico de mensagens ao conectar. |
    | `chats`           | Eventos relacionados à lista de conversas.         |
    | `chat_labels`     | Alterações em etiquetas de conversas.              |
  </Accordion>

  <Accordion title="Sistema e Conexão" icon="server">
    | Evento       | Descrição                                                |
    | :----------- | :------------------------------------------------------- |
    | `connection` | Alterações no estado (QR Code, Conectado, Desconectado). |
    | `presence`   | Alterações no status de presença (online, digitando).    |
    | `contacts`   | Atualizações na agenda de contatos.                      |
    | `groups`     | Modificações em grupos (título, participantes).          |
    | `blocks`     | Bloqueios e desbloqueios de contatos.                    |
    | `call`       | Eventos de chamadas de voz/vídeo.                        |
  </Accordion>

  <Accordion title="Marketing e Leads" icon="bullhorn">
    | Evento   | Descrição                                   |
    | :------- | :------------------------------------------ |
    | `leads`  | Atualizações de leads.                      |
    | `labels` | Gerenciamento de etiquetas.                 |
    | `sender` | Atualizações de campanhas (início/término). |
  </Accordion>
</AccordionGroup>

## Filtros de Exclusão (`excludeMessages`)

Use o campo `excludeMessages` para ignorar mensagens específicas e economizar processamento.

| Filtro            | Descrição                                                   |
| :---------------- | :---------------------------------------------------------- |
| `wasSentByApi`    | **Importante:** Ignora mensagens enviadas pela própria API. |
| `wasNotSentByApi` | Ignora mensagens que NÃO foram enviadas pela API.           |
| `fromMeYes`       | Ignora mensagens enviadas pelo próprio usuário (celular).   |
| `fromMeNo`        | Ignora mensagens recebidas de outras pessoas.               |
| `isGroupYes`      | Ignora mensagens vindas de grupos.                          |
| `isGroupNo`       | Ignora mensagens de conversas privadas (PV).                |

***

## Parâmetros de URL (Rotas Dinâmicas)

Você pode fazer com que a API adicione informações diretamente na URL do seu webhook, facilitando o roteamento no seu backend (ex: usar Node.js/Express ou Laravel Routes).

### Opções Disponíveis

<CardGroup cols={2}>
  <Card title="addUrlEvents" icon="bolt">
    Adiciona o **evento** na URL.
    `.../webhook/{evento}`
  </Card>

  <Card title="addUrlTypesMessages" icon="envelope-open-text">
    Adiciona o **tipo da mensagem** na URL.
    `.../webhook/{tipo}`
  </Card>
</CardGroup>

### Exemplos de Resultados

Suponha que sua URL base seja `https://api.example.com/webhook`:

1. **Apenas Eventos (`addUrlEvents: true`):**
   * `https://api.example.com/webhook/message`
   * `https://api.example.com/webhook/connection`

2. **Apenas Tipos (`addUrlTypesMessages: true`):**
   * `https://api.example.com/webhook/conversation` (texto)
   * `https://api.example.com/webhook/image` (mídia)

3. **Ambos Ativos (Combinação):**
   A ordem é sempre: `{URL_BASE}/{EVENTO}/{TIPO_MENSAGEM}`
   * `https://api.example.com/webhook/message/conversation`
   * `https://api.example.com/webhook/message/audio`

<Note>
  Certifique-se de que seu backend esteja configurado para aceitar **parâmetros dinâmicos** (wildcards) na rota para processar essas URLs corretamente.
</Note>