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

# Referência dos Webhooks

> Guia completo sobre os eventos, payloads e campos enviados pelos webhooks da Zatten.

<Note>
  Nesta seção, você encontrará detalhes sobre os eventos que a Zatten pode enviar para a sua aplicação via webhook. Configure uma URL no seu painel para começar a receber esses eventos em tempo real.
</Note>

## Como funcionam os Webhooks?

Quando ocorrem ações específicas na plataforma, como a criação de um lead ou o recebimento de uma mensagem, enviamos uma requisição `POST` para a URL que você configurou. O corpo dessa requisição contém um payload JSON com todas as informações relevantes sobre o evento.

***

## Eventos de Conversa e Lead

### LEAD\_CREATED

Enviado sempre que um **novo lead é criado** no sistema, seja por uma interação inicial ou manualmente.

```json theme={null}
{
  "type": "LEAD_CREATED",
  "lead": {
    "id": "lead_abc123def456",
    "name": "Cliente Potencial",
    "wa_id": "5511987654321",
    "thread_id": "thr_external_xyz789",
    "last_interaction": null,
    "conversation_expires_in": null,
    "created_at": "2025-10-09T20:00:00.000Z",
    "ai_response_block_until": null,
    "tags": [],
    "tenant_id": "tenant_acme_corp_789",
    "unread_messages": 1,
    "column_id": "col_new_lead_111",
    "notes": null,
    "metadata": null,
    "assigned_to_user": null,
    "assigned_to_team": null,
    "zatten_thread_id": "zt-thread-internal-123"
  },
  "attendant": {
    "id": "attendant_ia_pro_333",
    "meta_number_id": "102030405060708",
    "name": "Assistente Virtual"
  },
  "timestamp": "2025-10-09T20:00:00.000Z"
}
```

**Campos do Payload:**

* **type**: `string` - Tipo do evento (`LEAD_CREATED`).
* **lead**: `object` - Objeto contendo os dados do lead.
  * **id**: `string` - Identificador único do lead.
  * **name**: `string | null` - Nome do lead.
  * **wa\_id**: `string` - Número de WhatsApp do lead (E.164).
  * **thread\_id**: `string | null` - ID da thread externa (se aplicável).
  * **last\_interaction**: `string | null` - Data da última interação (ISO 8601).
  * **conversation\_expires\_in**: `string | null` - Data de expiração da janela de conversa (ISO 8601).
  * **created\_at**: `string` - Data de criação do lead (ISO 8601).
  * **ai\_response\_block\_until**: `string | null` - Data até a qual a IA está bloqueada de responder.
  * **tags**: `string[] | null` - Array com os IDs das tags do lead.
  * **tenant\_id**: `string` - ID da sua organização (tenant).
  * **unread\_messages**: `number | null` - Quantidade de mensagens não lidas.
  * **column\_id**: `string | null` - ID da coluna do Kanban onde o lead se encontra.
  * **notes**: `string | null` - Anotações sobre o lead.
  * **metadata**: `object | null` - Objeto com dados personalizados do lead.
  * **assigned\_to\_user**: `string | null` - ID do usuário para o qual o lead está atribuído.
  * **assigned\_to\_team**: `string | null` - ID da equipe para a qual o lead está atribuído.
  * **zatten\_thread\_id**: `string | null` - ID da thread interna da Zatten.
* **attendant**: `object` - Objeto com dados do atendente.
  * **id**: `string` - Identificador único do atendente.
  * **meta\_number\_id**: `string | null` - ID do número de telefone da Meta.
  * **name**: `string | null` - Nome do atendente.
* **timestamp**: `string` - Data e hora do evento (ISO 8601).

***

### LEAD\_INTERACTION

Enviado quando um **lead envia uma nova mensagem**.

```json theme={null}
{
  "type": "LEAD_INTERACTION",
  "lead": {
    "id": "lead_abc123def456",
    "name": "Cliente Potencial",
    "wa_id": "5511987654321",
    "thread_id": "thr_external_xyz789",
    "last_interaction": "2025-10-09T21:30:15.123Z",
    "conversation_expires_in": "2025-10-10T21:30:15.123Z",
    "created_at": "2025-10-09T20:00:00.000Z",
    "ai_response_block_until": null,
    "tags": ["tag_vip_123", "tag_followup_456"],
    "tenant_id": "tenant_acme_corp_789",
    "unread_messages": 2,
    "column_id": "col_negotiation_xyz",
    "notes": "Demonstrou interesse no plano Enterprise.",
    "metadata": {
      "origem": "webinar-outubro",
      "score_venda": 85
    },
    "assigned_to_user": "user_joao_silva_111",
    "assigned_to_team": "team_vendas_sp_222",
    "zatten_thread_id": "zt-thread-internal-123"
  },
  "attendant": {
    "id": "attendant_ia_pro_333",
    "meta_number_id": "102030405060708",
    "name": "Assistente Virtual"
  },
  "message": {
    "messages": ["Olá, bom dia!", "Gostaria de agendar uma demonstração."]
  },
  "timestamp": "2025-10-09T21:30:15.123Z"
}
```

**Campos do Payload:**

* **type**: `string` - Tipo do evento (`LEAD_INTERACTION`).
* **lead**: `object` - Objeto contendo os dados do lead.
  * **id**: `string` - Identificador único do lead.
  * **name**: `string | null` - Nome do lead.
  * **wa\_id**: `string` - Número de WhatsApp do lead (E.164).
  * **thread\_id**: `string | null` - ID da thread externa (se aplicável).
  * **last\_interaction**: `string | null` - Data da última interação (ISO 8601).
  * **conversation\_expires\_in**: `string | null` - Data de expiração da janela de conversa (ISO 8601).
  * **created\_at**: `string` - Data de criação do lead (ISO 8601).
  * **ai\_response\_block\_until**: `string | null` - Data até a qual a IA está bloqueada de responder.
  * **tags**: `string[] | null` - Array com os IDs das tags do lead.
  * **tenant\_id**: `string` - ID da sua organização (tenant).
  * **unread\_messages**: `number | null` - Quantidade de mensagens não lidas.
  * **column\_id**: `string | null` - ID da coluna do Kanban onde o lead se encontra.
  * **notes**: `string | null` - Anotações sobre o lead.
  * **metadata**: `object | null` - Objeto com dados personalizados do lead.
  * **assigned\_to\_user**: `string | null` - ID do usuário para o qual o lead está atribuído.
  * **assigned\_to\_team**: `string | null` - ID da equipe para a qual o lead está atribuído.
  * **zatten\_thread\_id**: `string | null` - ID da thread interna da Zatten.
* **attendant**: `object` - Objeto com dados do atendente.
  * **id**: `string` - Identificador único do atendente.
  * **meta\_number\_id**: `string | null` - ID do número de telefone da Meta.
  * **name**: `string | null` - Nome do atendente.
* **message**: `object` - Objeto com o conteúdo da mensagem.
  * **messages**: `string[]` - Array com as mensagens enviadas pelo lead.
* **timestamp**: `string` - Data e hora do evento (ISO 8601).

***

### AI\_RESPONSE

Enviado sempre que a **inteligência artificial responde** a um lead.

```json theme={null}
{
  "type": "AI_RESPONSE",
  "lead": {
    "id": "lead_abc123def456",
    "name": "Cliente Potencial",
    "wa_id": "5511987654321",
    "thread_id": "thr_external_xyz789",
    "last_interaction": "2025-10-09T21:30:20.456Z",
    "conversation_expires_in": "2025-10-10T21:30:15.123Z",
    "created_at": "2025-10-09T20:00:00.000Z",
    "ai_response_block_until": null,
    "tags": ["tag_vip_123", "tag_followup_456"],
    "tenant_id": "tenant_acme_corp_789",
    "unread_messages": 0,
    "column_id": "col_negotiation_xyz",
    "notes": "Demonstrou interesse no plano Enterprise.",
    "metadata": {
      "origem": "webinar-outubro",
      "score_venda": 85
    },
    "assigned_to_user": "user_joao_silva_111",
    "assigned_to_team": "team_vendas_sp_222",
    "zatten_thread_id": "zt-thread-internal-123"
  },
  "attendant": {
    "id": "attendant_ia_pro_333",
    "meta_number_id": "102030405060708",
    "name": "Assistente Virtual"
  },
  "message": {
    "messages": ["Olá! Claro, qual o melhor horário para você?"]
  },
  "timestamp": "2025-10-09T21:30:20.456Z"
}
```

**Campos do Payload:**

* **type**: `string` - Tipo do evento (`AI_RESPONSE`).
* **lead**: `object` - Objeto contendo os dados do lead.
  * **id**: `string` - Identificador único do lead.
  * **name**: `string | null` - Nome do lead.
  * **wa\_id**: `string` - Número de WhatsApp do lead (E.164).
  * **thread\_id**: `string | null` - ID da thread externa (se aplicável).
  * **last\_interaction**: `string | null` - Data da última interação (ISO 8601).
  * **conversation\_expires\_in**: `string | null` - Data de expiração da janela de conversa (ISO 8601).
  * **created\_at**: `string` - Data de criação do lead (ISO 8601).
  * **ai\_response\_block\_until**: `string | null` - Data até a qual a IA está bloqueada de responder.
  * **tags**: `string[] | null` - Array com os IDs das tags do lead.
  * **tenant\_id**: `string` - ID da sua organização (tenant).
  * **unread\_messages**: `number | null` - Quantidade de mensagens não lidas.
  * **column\_id**: `string | null` - ID da coluna do Kanban onde o lead se encontra.
  * **notes**: `string | null` - Anotações sobre o lead.
  * **metadata**: `object | null` - Objeto com dados personalizados do lead.
  * **assigned\_to\_user**: `string | null` - ID do usuário para o qual o lead está atribuído.
  * **assigned\_to\_team**: `string | null` - ID da equipe para a qual o lead está atribuído.
  * **zatten\_thread\_id**: `string | null` - ID da thread interna da Zatten.
* **attendant**: `object` - Objeto com dados do atendente.
  * **id**: `string` - Identificador único do atendente.
  * **meta\_number\_id**: `string | null` - ID do número de telefone da Meta.
  * **name**: `string | null` - Nome do atendente.
* **message**: `object` - Objeto com o conteúdo da mensagem.
  * **messages**: `string[]` - Array com as mensagens enviadas pelo lead.
* **timestamp**: `string` - Data e hora do evento (ISO 8601).

***

### ERROR

Enviado quando ocorre um **erro ao processar ou enviar uma mensagem**.

```json theme={null}
{
  "type": "ERROR",
  "lead": {
    "id": "lead_abc123def456",
    "name": "Cliente Potencial",
    "wa_id": "5511987654321",
    "thread_id": "thr_external_xyz789",
    "last_interaction": "2025-10-09T21:30:20.456Z",
    "conversation_expires_in": "2025-10-10T21:30:15.123Z",
    "created_at": "2025-10-09T20:00:00.000Z",
    "ai_response_block_until": "2035-10-09T21:30:20.456Z",
    "tags": ["tag_vip_123", "tag_followup_456"],
    "tenant_id": "tenant_acme_corp_789",
    "unread_messages": 2,
    "column_id": "col_negotiation_xyz",
    "notes": "Demonstrou interesse no plano Enterprise.",
    "metadata": {
      "origem": "webinar-outubro",
      "score_venda": 85
    },
    "assigned_to_user": "user_joao_silva_111",
    "assigned_to_team": "team_vendas_sp_222",
    "zatten_thread_id": "zt-thread-internal-123"
  },
  "attendant": {
    "id": "attendant_ia_pro_333",
    "meta_number_id": "102030405060708",
    "name": "Assistente Virtual"
  },
  "message": {
    "error": "Failed to send message: Recipient is outside of the 24-hour conversation window.",
    "code": "ERROR_META_REENGAGEMENT - 131047"
  },
  "timestamp": "2025-10-11T22:15:00.000Z"
}
```

**Campos do Payload:**

* **type**: `string` - Tipo do evento (`ERROR`).
* **lead**: `object` - Objeto contendo os dados do lead.
  * **id**: `string` - Identificador único do lead.
  * **name**: `string | null` - Nome do lead.
  * **wa\_id**: `string` - Número de WhatsApp do lead (E.164).
  * **thread\_id**: `string | null` - ID da thread externa (se aplicável).
  * **last\_interaction**: `string | null` - Data da última interação (ISO 8601).
  * **conversation\_expires\_in**: `string | null` - Data de expiração da janela de conversa (ISO 8601).
  * **created\_at**: `string` - Data de criação do lead (ISO 8601).
  * **ai\_response\_block\_until**: `string | null` - Data até a qual a IA está bloqueada de responder.
  * **tags**: `string[] | null` - Array com os IDs das tags do lead.
  * **tenant\_id**: `string` - ID da sua organização (tenant).
  * **unread\_messages**: `number | null` - Quantidade de mensagens não lidas.
  * **column\_id**: `string | null` - ID da coluna do Kanban onde o lead se encontra.
  * **notes**: `string | null` - Anotações sobre o lead.
  * **metadata**: `object | null` - Objeto com dados personalizados do lead.
  * **assigned\_to\_user**: `string | null` - ID do usuário para o qual o lead está atribuído.
  * **assigned\_to\_team**: `string | null` - ID da equipe para a qual o lead está atribuído.
  * **zatten\_thread\_id**: `string | null` - ID da thread interna da Zatten.
* **attendant**: `object` - Objeto com dados do atendente.
  * **id**: `string` - Identificador único do atendente.
  * **meta\_number\_id**: `string | null` - ID do número de telefone da Meta.
  * **name**: `string | null` - Nome do atendente.
* **message**: `object` - Objeto com o conteúdo da mensagem.
  * **messages**: `string[]` - Array com as mensagens enviadas pelo lead.
* **message**: `object` - Objeto com a descrição do erro.
  * **error**: `string` - Detalhes sobre o erro que ocorreu.
  * **code**: `string` - Detalhes sobre o código do erro que ocorreu.
* **timestamp**: `string` - Data e hora do evento (ISO 8601).

***

## Eventos de Kanban e Tags

### LEAD\_KANBAN\_UPDATED

Enviado quando o **lead muda de coluna no Kanban**.

```json theme={null}
{
  "event": "LEAD_KANBAN_UPDATED",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "previous_column_id": "col111abc123",
  "previous_column_name": "Proposta Enviada",
  "previous_column_description": null,
  "new_column_id": "col333def456",
  "new_column_name": "Lead Quente",
  "new_column_description": null,
  "timestamp": "2025-08-18T14:30:58.939Z",
  "attendant_id": "def456abc123",
  "attendant_name": "Zatten",
  "current_tags": [],
  "lead_metadata": null
}
```

**Campos do Payload:**

* **event**: `string` - Tipo do evento (`LEAD_KANBAN_UPDATED`).
* **lead\_id**: `string` - Identificador do lead.
* **lead\_name**: `string` - Nome do lead.
* **lead\_phone**: `string` - Número do lead em formato internacional (E.164).
* **previous\_column\_id**: `string` - Identificador da coluna anterior.
* **previous\_column\_name**: `string` - Nome da coluna anterior.
* **previous\_column\_description**: `string | null` - Descrição da coluna anterior.
* **new\_column\_id**: `string` - Identificador da nova coluna.
* **new\_column\_name**: `string` - Nome da nova coluna.
* **new\_column\_description**: `string | null` - Descrição da nova coluna.
* **timestamp**: `string` - Data/hora da atualização (ISO 8601).
* **attendant\_id**: `string` - Identificador do atendente vinculado.
* **attendant\_name**: `string` - Nome do atendente.
* **current\_tags**: `array` - Lista de tags atuais atribuídas ao lead.
* **lead\_metadata**: `array | null` - Lista de propriedades adicionais do lead.

***

### LEAD\_TAG\_ADDED

Enviado quando uma **tag é adicionada** a um lead.

```json theme={null}
{
  "event": "LEAD_TAG_ADDED",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "tag_id": "tag999ghi123",
  "tag_name": "Só quer conversar",
  "tag_description": null,
  "current_tags": [
    {
      "id": "tag777def890",
      "name": "Esperando Retorno",
      "description": ""
    },
    {
      "id": "tag999ghi123",
      "name": "Só quer conversar",
      "description": ""
    }
  ],
  "timestamp": "2025-08-18T14:31:19.692Z",
  "attendant_id": "def456abc123",
  "attendant_name": "Zatten",
  "kanban_column_id": "col555ghi678",
  "kanban_column_name": "Lead Frio",
  "kanban_column_description": null,
  "lead_metadata": [
    {
      "prop_name": "nome_do_chefe",
      "prop_value": "teste"
    },
    {
      "prop_name": "cpf",
      "prop_value": "12345678909"
    }
  ]
}
```

**Campos do Payload:**

* **event**: `string` - Tipo do evento (`LEAD_TAG_ADDED`).
* **lead\_id**: `string` - Identificador do lead.
* **lead\_name**: `string` - Nome do lead.
* **lead\_phone**: `string` - Número do lead (E.164).
* **tag\_id**: `string` - Identificador da tag adicionada.
* **tag\_name**: `string` - Nome da tag adicionada.
* **tag\_description**: `string | null` - Descrição da tag.
* **current\_tags**: `array` - Lista completa das tags atuais do lead.
* **timestamp**: `string` - Data/hora da atualização (ISO 8601).
* **attendant\_id**: `string` - Identificador do atendente.
* **attendant\_name**: `string` - Nome do atendente.
* **kanban\_column\_id**: `string` - Identificador da coluna atual do Kanban.
* **kanban\_column\_name**: `string` - Nome da coluna atual.
* **kanban\_column\_description**: `string | null` - Descrição da coluna atual.
* **lead\_metadata**: `array` - Lista de propriedades adicionais do lead.

***

### LEAD\_TAG\_REMOVED

Enviado quando uma **tag é removida** de um lead.

```json theme={null}
{
  "event": "LEAD_TAG_REMOVED",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "tag_id": "tag777def890",
  "tag_name": "Esperando Retorno",
  "tag_description": null,
  "current_tags": [],
  "timestamp": "2025-08-18T14:36:31.409Z",
  "attendant_id": "def456abc123",
  "attendant_name": "Zatten",
  "kanban_column_id": "col555ghi678",
  "kanban_column_name": "Lead Frio",
  "kanban_column_description": null,
  "lead_metadata": [
    {
      "prop_name": "nome_do_chefe",
      "prop_value": "Chefe"
    },
    {
      "prop_name": "cpf",
      "prop_value": "12345678909"
    }
  ]
}
```

**Campos do Payload:**

* **event**: `string` - Tipo do evento (`LEAD_TAG_REMOVED`).
* **lead\_id**: `string` - Identificador do lead.
* **lead\_name**: `string` - Nome do lead.
* **lead\_phone**: `string` - Número do lead (E.164).
* **tag\_id**: `string` - Identificador da tag removida.
* **tag\_name**: `string` - Nome da tag removida.
* **tag\_description**: `string | null` - Descrição da tag.
* **current\_tags**: `array` - Lista de tags restantes (pode estar vazia).
* **timestamp**: `string` - Data/hora da atualização (ISO 8601).
* **attendant\_id**: `string` - Identificador do atendente.
* **attendant\_name**: `string` - Nome do atendente.
* **kanban\_column\_id**: `string` - Identificador da coluna atual do Kanban.
* **kanban\_column\_name**: `string` - Nome da coluna atual.
* **kanban\_column\_description**: `string | null` - Descrição da coluna atual.
* **lead\_metadata**: `array` - Lista de propriedades adicionais do lead.

***

<Warning>
  **Observações Importantes**

  * **Confirmação:** Para confirmar o recebimento de um webhook, sua URL deve retornar uma resposta com status `2xx` (ex: `200` ou `204`). Qualquer outro status pode ser interpretado como uma falha.

  * **Formato de Data:** Todos os timestamps e campos de data/hora seguem o padrão **ISO 8601 UTC**.

  * **Idempotência:** Sua aplicação deve ser construída para lidar com a possibilidade de receber o mesmo evento mais de uma vez. Tornar o processamento do webhook idempotente (processar o mesmo evento múltiplas vezes sem criar resultados duplicados) é uma prática recomendada.

  * **Dados Atualizados:** O payload de cada evento sempre contém os dados mais atualizados daquele lead no momento em que a ação ocorreu.
</Warning>