# Conexão da instância

**Evento:** `connection` · **Transporte:** POST para o seu receptor

Acompanhe mudanças do ciclo de conexão da instância. Use `instance.status` para atualizar a interface e decidir quando consultar `/instance/status`.

## Quando é enviado

Conexão estabelecida e transições de desconexão notificadas pelo ciclo da sessão. Uma queda transitória de socket pode ser suprimida durante recuperação; não conte com um webhook para cada tentativa interna de reconexão.

## Como interpretar

- `event_id` identifica a notificação produzida pelo fluxo de conexão.
- `instance.status` descreve o estado informado; `lastDisconnectReason` ajuda no diagnóstico.
- `type`, quando presente, pode indicar a origem da transição, como `Disconnected` ou `TemporaryBan`.
- Campos como `temporaryBan` só aparecem quando aplicáveis. Consulte o estado atual se eventos chegarem atrasados.

## Habilitar este evento

Adicione `connection` à lista `events` do webhook da instância. Preserve os outros eventos de que sua integração precisa.

```json
{
  "enabled": true,
  "url": "https://seu-sistema.example/hooks/whatsapp",
  "events": [
    "connection"
  ]
}
```

Envie essa configuração para [POST /webhook](/reference/updateWebhook.md), usando o header `token`. O JSON acima configura a assinatura; os exemplos de entrega abaixo são o que seu servidor recebe.

## Campos do payload

O envelope comum vem na raiz. Campos condicionais podem estar ausentes ou nulos conforme o evento; não use a tabela como obrigação de presença de todos os campos.

| Campo | Tipo | Significado |
|---|---|---|
| `EventType` | string | **Obrigatório.** Tipo de evento, por exemplo connection ou messages. |
| `owner` | string | **Obrigatório.** Consulte o objeto ou exemplo correspondente. |
| `token` | string | **Obrigatório.** Token da instância; dado sensível. |
| `BaseUrl` | string | **Obrigatório.** Consulte o objeto ou exemplo correspondente. |
| `instanceName` | string | Consulte o objeto ou exemplo correspondente. |
| `event_id` | string | Identificador da notificação de conexão; não é um campo universal dos outros eventos. |
| `instance` | object | Estado da instância. |
| `instance.name` | string | Nome da instância. |
| `instance.status` | string | Estado da conexão informado pelo evento. |
| `instance.lastDisconnectReason` | string | Motivo disponível da desconexão; pode ser unknown. |
| `instance.lastDisconnect` | string | Data textual da última desconexão. |
| `type` | string | Origem/tipo da transição, quando disponível. |

## Exemplos de entrega

Exemplos ilustrativos com identificadores fictícios. O conteúdo específico e os campos opcionais variam.

### Conexão estabelecida

```json
{
  "EventType": "connection",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "event_id": "f51310de-8e2b-4ef5-8065-dcd67e764c65",
  "instance": {
    "name": "Atendimento",
    "status": "connected"
  }
}
```

### Desconexão notificada

```json
{
  "EventType": "connection",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "event_id": "4d42a099-7921-43ec-9774-da72901bbf13",
  "type": "Disconnected",
  "instance": {
    "name": "Atendimento",
    "status": "disconnected",
    "lastDisconnectReason": "unknown",
    "lastDisconnect": "2026-09-08 12:00:00.000Z"
  }
}
```

## Responder ao webhook

Seu receptor deve aceitar o POST JSON e devolver uma resposta `2xx` rapidamente, após validar e registrar o recebimento. O corpo da resposta não é um comando para a API. Processe trabalho demorado separadamente.

O worker não repete automaticamente uma entrega HTTP malsucedida. Consulte [diagnóstico de webhooks](/docs/integrations-webhooks#diagnostico) e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.

## Referências

- [Introdução, configuração e catálogo](/docs/integrations-webhooks)
- [Autenticação](/docs/authentication)
- [Contrato OpenAPI completo](/openapi-bundled.json)