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

# Recebendo Mensagens

> Configure webhooks para receber mensagens de APIs externas na Conexão Universal

A aba **Recebimento** é onde você configura como o Datacrazy recebe mensagens do serviço externo via webhook.

## URL do Webhook

Após criar a instância, o Datacrazy gera automaticamente uma **URL do Webhook** exibida na aba **Recebimento**. Configure essa URL no painel do serviço externo como destino dos webhooks.

> ⚠️ **Importante:** O endpoint sempre retorna `{ "success": true }` com HTTP 200, independentemente do resultado do processamento interno. Isso evita que o serviço externo faça retentativas desnecessárias.

***

## Habilitando o recebimento

Ative o toggle **Habilitar recebimento de mensagens** para começar a processar webhooks recebidos.

***

## Mapeamento de Campos

A seção **Mapeamento de Campos** define como extrair os dados relevantes do payload JSON enviado pelo serviço externo. Preencha cada campo com o caminho usando **dot notation** (notação de ponto).

### Campos obrigatórios

| Campo                            | Descrição                                | Exemplo de caminho |
| -------------------------------- | ---------------------------------------- | ------------------ |
| **Caminho do ID do Contato**     | ID único do remetente                    | `message.from.id`  |
| **Caminho do Corpo da Mensagem** | Conteúdo da mensagem                     | `message.text`     |
| **Caminho do ID da Mensagem**    | ID único da mensagem (para idempotência) | `update_id`        |

### Campos opcionais

| Campo                                 | Descrição                  | Exemplo de caminho           |
| ------------------------------------- | -------------------------- | ---------------------------- |
| **Caminho do Nome do Contato**        | Nome do remetente          | `message.from.first_name`    |
| **Caminho do Timestamp**              | Data/hora da mensagem      | `message.date`               |
| **Caminho da URL do Anexo**           | URL do anexo recebido      | `message.document.file_path` |
| **Caminho do Tipo do Anexo**          | Tipo MIME do anexo         | `message.document.mime_type` |
| **Caminho do ID Externo da Mensagem** | ID alternativo da mensagem | `message.message_id`         |

### Exemplo

Considerando que o serviço externo envia um payload como:

```json theme={null}
{
  "update_id": 123456,
  "message": {
    "message_id": 789,
    "from": {
      "id": 111222333,
      "first_name": "João"
    },
    "text": "Olá!",
    "date": 1700000000
  }
}
```

Preencha os campos:

* **Caminho do ID do Contato:** `message.from.id`
* **Caminho do Nome do Contato:** `message.from.first_name`
* **Caminho do Corpo da Mensagem:** `message.text`
* **Caminho do ID da Mensagem:** `update_id`
* **Caminho do Timestamp:** `message.date`

***

## Validação do Webhook

A seção **Validação do Webhook** permite verificar se os webhooks recebidos são legítimos. O Datacrazy verifica o header especificado usando o algoritmo configurado.

| Campo                    | Descrição                                                 |
| ------------------------ | --------------------------------------------------------- |
| **Header de Assinatura** | Nome do header que contém a assinatura (case-insensitive) |
| **Algoritmo**            | Algoritmo de validação (selecione no dropdown)            |
| **Segredo de Validação** | Chave secreta para validação                              |

### Algoritmos disponíveis

| Algoritmo     | Descrição                                                      |
| ------------- | -------------------------------------------------------------- |
| `static`      | Comparação direta do valor do header com o segredo configurado |
| `sha256`      | Hash SHA-256 do corpo da requisição                            |
| `sha1`        | Hash SHA-1 do corpo da requisição                              |
| `hmac-sha256` | HMAC-SHA256 do corpo com o segredo (suporta prefixo `sha256=`) |

> ⚠️ **Nota:** Se o **Segredo de Validação** não for preenchido, o sistema tenta usar a credencial `webhookSecret` como fallback.

***

## Filtros

A seção **Filtros** permite ignorar mensagens indesejadas antes do processamento.

| Campo                          | Descrição                                                                                |
| ------------------------------ | ---------------------------------------------------------------------------------------- |
| **Campo Obrigatório**          | Caminho do campo que deve existir e ser truthy no payload para a mensagem ser processada |
| **Ignorar Mensagens Próprias** | Caminho do campo booleano que, se `true`, faz a mensagem ser ignorada                    |

**Exemplo para o Telegram:**

* **Campo Obrigatório:** `message.text` — ignora updates sem texto (como edições de grupo)
* **Ignorar Mensagens Próprias:** `message.from.is_bot` — ignora mensagens enviadas por bots

***

## Processamento

O processamento dos webhooks recebidos inclui:

* **Fila assíncrona** com concorrência de 10 mensagens em paralelo
* **Idempotência** via cache Redis com TTL de 1 hora — mensagens com o mesmo ID não são processadas duas vezes
* **Lock distribuído** por ID de mensagem para evitar condições de corrida
* **Detecção automática de anexo** baseada no MIME type:

| Padrão MIME | Tipo detectado |
| ----------- | -------------- |
| `image/*`   | IMAGE          |
| `video/*`   | VIDEO          |
| `audio/*`   | AUDIO          |
| Outros      | FILE           |

***

## Logs

A aba **Logs** exibe o histórico de todas as operações da Conexão Universal. Você pode filtrar usando os dropdowns **Filtrar por tipo** e **Filtrar por status**.

### Tipos de log

| Tipo            | Descrição                           |
| --------------- | ----------------------------------- |
| **Envio**       | Mensagem enviada para a API externa |
| **Recebimento** | Webhook recebido do serviço externo |
| **Teste**       | Teste de conexão executado          |

### Status

| Status      | Significado                       |
| ----------- | --------------------------------- |
| **Sucesso** | Operação concluída com sucesso    |
| **Erro**    | Operação falhou                   |
| **Timeout** | Requisição excedeu o tempo limite |

Cada log exibe os detalhes da **Requisição** e da **Resposta**, incluindo headers, body e código de status.

> ⚠️ **Nota:** Os logs possuem TTL de 1 hora e são removidos automaticamente após esse período.