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

# Payloads de webhooks

> Exemplos reais dos payloads entregues pelos webhooks da EZ API.

## Visão geral

Todos os webhooks da EZ API são enviados via `POST` com `Content-Type: application/json`.

O evento mais flexível é o `ReceivedCallback`. Ele sempre mantém o mesmo envelope base e adiciona blocos específicos conforme o tipo do conteúdo recebido, como `text`, `image`, `video`, `document`, `poll`, `hydratedTemplate` e outros.

<Note>
  Os exemplos abaixo foram alinhados ao shape real do mapper da EZ API. Quando um tipo não possui bloco próprio, a API usa `notification` e `notificationParameters`.
</Note>

## Envelope base do `ReceivedCallback`

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "3EB047ED70306656281B34",
  "phone": "5511988887777",
  "connectedPhone": "5511999999999",
  "fromMe": false,
  "momment": 1736200000000,
  "status": "RECEIVED",
  "chatName": "Carlos Silva",
  "senderName": "Carlos Silva",
  "senderPhoto": "https://cdn.ezapi.dev/profiles/carlos.jpg",
  "photo": "https://cdn.ezapi.dev/chats/carlos.jpg",
  "senderLid": "81896604192873@lid",
  "chatLid": "81896604192873@lid",
  "isGroup": false,
  "isNewsletter": false,
  "broadcast": false,
  "forwarded": false,
  "viewOnce": false,
  "waitingMessage": false,
  "text": {
    "message": "Olá, preciso de ajuda com a minha compra."
  }
}
```

| Campo                    | Descrição                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `type`                   | Sempre `ReceivedCallback` para mensagens recebidas e notificações derivadas de mensagem.             |
| `instanceId`             | Identificador da instância que disparou o webhook.                                                   |
| `messageId`              | ID da mensagem recebida no WhatsApp.                                                                 |
| `phone`                  | Telefone do remetente ou do chat principal.                                                          |
| `connectedPhone`         | Número conectado na instância que recebeu o evento.                                                  |
| `momment`                | Timestamp em milissegundos. O campo mantém a grafia real do payload.                                 |
| `fromMe`                 | `true` quando a mensagem é da própria instância.                                                     |
| `isGroup`                | `true` quando o evento veio de grupo.                                                                |
| `isNewsletter`           | `true` quando o evento veio de canal.                                                                |
| `broadcast`              | `true` quando o evento veio de lista de transmissão.                                                 |
| `referenceMessageId`     | ID da mensagem referenciada, quando houver resposta, reação, fixação, enquete ou evento relacionado. |
| `viewOnce`               | Indica que o conteúdo original usa envelope de visualização única.                                   |
| `waitingMessage`         | Também fica `true` quando o payload veio de wrapper `viewOnceMessage`.                               |
| `notification`           | Nome da notificação sistêmica quando não existe bloco específico de conteúdo.                        |
| `notificationParameters` | Lista de parâmetros extras da notificação.                                                           |

<Note>
  O envelope também pode incluir `participantPhone`, `participantLid`, `profileName`, `updatedPhoto`, `callId`, `requestMethod`, `externalAdReply`, `code` e `expiresAt`, dependendo do caso.
</Note>

## Texto

### Texto simples

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_TEXT_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200000000,
  "text": {
    "message": "Quero falar com o financeiro."
  }
}
```

### Texto com URL, título e descrição

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_TEXT_2",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200005000,
  "text": {
    "message": "Veja este link",
    "description": "Página de cobrança da EZ API",
    "descritpion": "Página de cobrança da EZ API",
    "title": "Cobrança",
    "url": "https://app.ezapi.dev/payments/123",
    "thumbnailUrl": "https://cdn.ezapi.dev/thumbs/payment.png"
  }
}
```

<Note>
  Quando há descrição, a EZ API envia os campos `description` e `descritpion`. A duplicação segue o payload real atual.
</Note>

### Texto vindo de anúncio ou CTA para WhatsApp

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_TEXT_AD_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200010000,
  "text": {
    "message": "Tenho interesse",
    "description": "Campanha Março",
    "descritpion": "Campanha Março",
    "title": "Promoção EZ API",
    "url": "https://ezapi.dev/oferta",
    "thumbnailUrl": "https://cdn.ezapi.dev/ads/oferta-marco.jpg"
  },
  "externalAdReply": {
    "title": "Promoção EZ API",
    "body": "Campanha Março",
    "sourceType": "ad",
    "sourceId": "campaign_marco_2026",
    "ctwaClid": "ctwa-123456",
    "sourceUrl": "https://ezapi.dev/oferta",
    "mediaType": 1,
    "thumbnailUrl": "https://cdn.ezapi.dev/ads/oferta-marco.jpg",
    "containsAutoReply": false,
    "renderLargerThumbnail": true,
    "showAdAttribution": true
  }
}
```

## Mídia

### Imagem

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_IMAGE_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200020000,
  "image": {
    "caption": "Comprovante do pagamento",
    "imageUrl": "https://cdn.ezapi.dev/media/proof.jpg",
    "thumbnailUrl": "https://cdn.ezapi.dev/media/proof-thumb.jpg",
    "mimeType": "image/jpeg",
    "viewOnce": false,
    "width": 1080,
    "height": 1350
  }
}
```

### Áudio

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_AUDIO_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200030000,
  "audio": {
    "audioUrl": "https://cdn.ezapi.dev/media/audio.ogg",
    "mimeType": "audio/ogg; codecs=opus",
    "ptt": true,
    "seconds": 18,
    "viewOnce": false
  }
}
```

### Vídeo

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_VIDEO_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200040000,
  "video": {
    "caption": "Segue o vídeo da entrega",
    "videoUrl": "https://cdn.ezapi.dev/media/delivery.mp4",
    "mimeType": "video/mp4",
    "thumbnailUrl": "https://cdn.ezapi.dev/media/delivery-thumb.jpg",
    "seconds": 27,
    "viewOnce": false,
    "width": 720,
    "height": 1280
  }
}
```

### GIF e PTV

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_VIDEO_2",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200045000,
  "video": {
    "videoUrl": "https://cdn.ezapi.dev/media/loop.mp4",
    "mimeType": "video/mp4",
    "thumbnailUrl": "https://cdn.ezapi.dev/media/loop-thumb.jpg",
    "seconds": 6,
    "viewOnce": false,
    "width": 480,
    "height": 480
  }
}
```

<Note>
  GIFs e PTVs não possuem bloco separado na EZ API. Ambos chegam normalizados em `video`.
</Note>

### Documento ou arquivo

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_DOC_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200050000,
  "document": {
    "mimeType": "application/pdf",
    "fileName": "contrato.pdf",
    "title": "Contrato 2026",
    "pageCount": 4,
    "thumbnailUrl": "https://cdn.ezapi.dev/media/contrato-preview.jpg",
    "documentUrl": "https://cdn.ezapi.dev/media/contrato.pdf",
    "fileLength": 482193
  }
}
```

### Sticker

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_STICKER_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200060000,
  "sticker": {
    "mimeType": "image/webp",
    "stickerUrl": "https://cdn.ezapi.dev/media/sticker.webp"
  }
}
```

### Resposta a status com imagem

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_STATUS_REPLY_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200065000,
  "referenceMessageId": "STATUS_ABC123",
  "statusImage": {
    "imageUrl": "https://cdn.ezapi.dev/media/status.jpg",
    "thumbnailUrl": "https://cdn.ezapi.dev/media/status-thumb.jpg",
    "caption": "",
    "mimetype": "image/jpeg",
    "viewOnce": false,
    "width": 1080,
    "height": 1920
  }
}
```

<Note>
  Em `statusImage`, o campo de MIME chega como `mimetype`, não `mimeType`.

  Se a resposta ao status for somente texto, o payload continua vindo em `text` com `referenceMessageId`. O bloco `statusImage` só aparece quando existe imagem referenciada no status respondido.
</Note>

## Contato e localização

### Contato

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_CONTACT_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200070000,
  "contact": {
    "displayName": "Marina Costa",
    "vCard": "BEGIN:VCARD\nVERSION:3.0\nFN:Marina Costa\nTEL;type=CELL;waid=5511912345678:+55 11 91234-5678\nEND:VCARD",
    "phones": [
      "5511912345678"
    ]
  }
}
```

### Localização

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_LOCATION_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200075000,
  "location": {
    "thumbnailUrl": "https://cdn.ezapi.dev/media/location-thumb.jpg",
    "longitude": -46.633308,
    "latitude": -23.55052,
    "url": "https://maps.google.com/?q=-23.55052,-46.633308",
    "name": "Escritório EZ API",
    "address": "Av. Paulista, 1000 - São Paulo/SP"
  }
}
```

## Respostas interativas

### Resposta de botão

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_BUTTON_REPLY_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200080000,
  "referenceMessageId": "MSG_BUTTON_ORIGINAL",
  "buttonsResponseMessage": {
    "buttonId": "financeiro",
    "message": "Falar com financeiro"
  }
}
```

### Resposta de lista

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_LIST_REPLY_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200085000,
  "referenceMessageId": "MSG_LIST_ORIGINAL",
  "listResponseMessage": {
    "message": "Plano com recursos avançados",
    "title": "Plano Pro",
    "selectedRowId": "plano-pro"
  }
}
```

## Templates, botões e carrossel

### Template de texto com botões rápidos, link e telefone

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_TEMPLATE_TEXT_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200090000,
  "hydratedTemplate": {
    "header": {},
    "message": "Seu código de acesso é 123456.",
    "footer": "Código válido por 5 minutos",
    "title": "Validação EZ API",
    "templateId": "otp_template_01",
    "hydratedButtons": [
      {
        "index": 0,
        "quickReplyButton": {
          "displayText": "Copiar código",
          "id": "otp_copy"
        }
      },
      {
        "index": 1,
        "urlButton": {
          "displayText": "Abrir portal",
          "url": "https://app.ezapi.dev/login"
        }
      },
      {
        "index": 2,
        "callButton": {
          "displayText": "Ligar no suporte",
          "phoneNumber": "551140028922"
        }
      }
    ]
  }
}
```

<Note>
  Templates de OTP, botão PIX, botão de link e botão de ligação chegam todos dentro de `hydratedTemplate.hydratedButtons`. O tipo do botão é definido por `quickReplyButton`, `urlButton` ou `callButton`.
</Note>

### Template com cabeçalho de imagem

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_TEMPLATE_IMAGE_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200095000,
  "hydratedTemplate": {
    "header": {
      "image": {
        "imageUrl": "https://cdn.ezapi.dev/media/banner.jpg",
        "thumbnailUrl": "https://cdn.ezapi.dev/media/banner-thumb.jpg",
        "mimeType": "image/jpeg",
        "caption": "",
        "viewOnce": false,
        "width": 1200,
        "height": 630
      }
    },
    "message": "Confira a oferta disponível hoje.",
    "footer": "Oferta sujeita a disponibilidade",
    "title": "Oferta do dia",
    "templateId": "promo_image_01",
    "hydratedButtons": [
      {
        "index": 0,
        "quickReplyButton": {
          "displayText": "Quero saber mais",
          "id": "offer_more"
        }
      }
    ]
  }
}
```

### Template com cabeçalho de vídeo

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_TEMPLATE_VIDEO_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200100000,
  "hydratedTemplate": {
    "header": {
      "video": {
        "videoUrl": "https://cdn.ezapi.dev/media/demo.mp4",
        "mimeType": "video/mp4",
        "caption": "",
        "viewOnce": false,
        "width": 720,
        "height": 1280,
        "seconds": 22
      }
    },
    "message": "Veja como ativar a instância.",
    "footer": "Tutorial rápido",
    "title": "Ativação",
    "templateId": "tutorial_video_01",
    "hydratedButtons": [
      {
        "index": 0,
        "urlButton": {
          "displayText": "Abrir documentação",
          "url": "https://docs.ezapi.dev"
        }
      }
    ]
  }
}
```

### Template com cabeçalho de documento

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_TEMPLATE_DOC_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200105000,
  "hydratedTemplate": {
    "header": {
      "document": {
        "documentUrl": "https://cdn.ezapi.dev/media/tabela-precos.pdf",
        "mimeType": "application/pdf",
        "fileName": "tabela-precos.pdf",
        "title": "Tabela de preços",
        "pageCount": 2,
        "caption": "Arquivo atualizado"
      }
    },
    "message": "Segue a tabela atualizada.",
    "footer": "Equipe comercial",
    "title": "Tabela 2026",
    "templateId": "pricing_doc_01",
    "hydratedButtons": [
      {
        "index": 0,
        "quickReplyButton": {
          "displayText": "Recebi",
          "id": "doc_ack"
        }
      }
    ]
  }
}
```

### Template com cabeçalho de localização

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_TEMPLATE_LOCATION_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200110000,
  "hydratedTemplate": {
    "header": {
      "location": {
        "longitude": -46.633308,
        "latitude": -23.55052,
        "address": "Av. Paulista, 1000 - São Paulo/SP",
        "name": "Escritório EZ API",
        "url": "https://maps.google.com/?q=-23.55052,-46.633308"
      }
    },
    "message": "Estamos neste endereço.",
    "footer": "Horário comercial: 09h às 18h",
    "title": "Nosso escritório",
    "templateId": "location_template_01",
    "hydratedButtons": [
      {
        "index": 0,
        "urlButton": {
          "displayText": "Abrir no mapa",
          "url": "https://maps.google.com/?q=-23.55052,-46.633308"
        }
      }
    ]
  }
}
```

### Mensagem de botões com imagem

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_BUTTONS_IMAGE_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200115000,
  "buttonsMessage": {
    "imageUrl": "https://cdn.ezapi.dev/media/planos.jpg",
    "videoUrl": null,
    "message": "Escolha uma opção de atendimento",
    "buttons": [
      {
        "buttonId": "sales",
        "type": 1,
        "buttonText": {
          "displayText": "Comercial"
        }
      },
      {
        "buttonId": "support",
        "type": 1,
        "buttonText": {
          "displayText": "Suporte"
        }
      }
    ]
  }
}
```

### Mensagem de botões com vídeo

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_BUTTONS_VIDEO_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200120000,
  "buttonsMessage": {
    "imageUrl": null,
    "videoUrl": "https://cdn.ezapi.dev/media/tutorial.mp4",
    "message": "Quer ativar agora?",
    "buttons": [
      {
        "buttonId": "activate_now",
        "type": 1,
        "buttonText": {
          "displayText": "Ativar"
        }
      },
      {
        "buttonId": "talk_team",
        "type": 1,
        "buttonText": {
          "displayText": "Falar com time"
        }
      }
    ]
  }
}
```

### Carrossel

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_CAROUSEL_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200125000,
  "carouselMessage": {
    "text": "Escolha o plano ideal para sua operação",
    "cards": [
      {
        "title": "Plano Start",
        "message": "Até 1 número conectado",
        "footer": "Ideal para validação",
        "header": {
          "image": {
            "imageUrl": "https://cdn.ezapi.dev/media/start.jpg",
            "thumbnailUrl": "https://cdn.ezapi.dev/media/start-thumb.jpg",
            "mimeType": "image/jpeg",
            "caption": "",
            "viewOnce": false,
            "width": 1200,
            "height": 630
          }
        },
        "hydratedButtons": [
          {
            "index": 0,
            "quickReplyButton": {
              "displayText": "Quero Start",
              "id": "plan_start"
            }
          }
        ]
      },
      {
        "title": "Plano Pro",
        "message": "Mais throughput e automação",
        "footer": "Para operação em produção",
        "header": {
          "image": {
            "imageUrl": "https://cdn.ezapi.dev/media/pro.jpg",
            "thumbnailUrl": "https://cdn.ezapi.dev/media/pro-thumb.jpg",
            "mimeType": "image/jpeg",
            "caption": "",
            "viewOnce": false,
            "width": 1200,
            "height": 630
          }
        },
        "hydratedButtons": [
          {
            "index": 0,
            "quickReplyButton": {
              "displayText": "Quero Pro",
              "id": "plan_pro"
            }
          }
        ]
      }
    ]
  }
}
```

## Reações e enquetes

### Reação

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_REACTION_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200130000,
  "referenceMessageId": "MSG_TEXT_1",
  "reaction": {
    "reactionBy": "5511988887777",
    "referencedMessage": {
      "messageId": "MSG_TEXT_1",
      "fromMe": false,
      "phone": "5511999999999",
      "participant": null
    },
    "value": "👍",
    "time": 1736200129990
  }
}
```

### Enquete

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_POLL_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200135000,
  "poll": {
    "question": "Qual plano você quer testar?",
    "pollMaxOptions": 1,
    "options": [
      "Start",
      "Pro",
      "Enterprise"
    ]
  }
}
```

### Resposta de enquete

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_POLL_VOTE_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200140000,
  "referenceMessageId": "MSG_POLL_1",
  "pollVote": {
    "pollMessageId": "MSG_POLL_1",
    "options": [
      "Pro"
    ]
  }
}
```

## Catálogo, carrinho, pedidos e pagamentos

### Produto

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_PRODUCT_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200145000,
  "product": {
    "productImage": "https://cdn.ezapi.dev/catalog/produto-1.jpg",
    "businessOwnerJid": "5511999999999@s.whatsapp.net",
    "currencyCode": "BRL",
    "productId": "PROD_1",
    "description": "Conector oficial EZ API",
    "productImageCount": 3,
    "price": 199900,
    "url": "https://app.ezapi.dev/catalog/produto-1",
    "retailerId": "SKU-001",
    "firstImageId": "IMG-001",
    "title": "Plano Pro"
  }
}
```

### Carrinho ou pedido simples

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_ORDER_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200150000,
  "order": {
    "itemCount": 2,
    "orderId": "ORDER_123",
    "message": "Pedido enviado pelo catálogo",
    "orderTitle": "Pedido EZ API",
    "sellerJid": "5511999999999@s.whatsapp.net",
    "thumbnailUrl": "https://cdn.ezapi.dev/catalog/order-thumb.jpg",
    "token": "token-order-123",
    "currency": "BRL",
    "total": 299800,
    "subTotal": 299800,
    "products": [
      {
        "name": "Plano Pro",
        "quantity": 1,
        "price": 199900,
        "currencyCode": "BRL",
        "productId": "PROD_1",
        "retailerId": "SKU-001"
      },
      {
        "name": "Suporte assistido",
        "quantity": 1,
        "price": 99900,
        "currencyCode": "BRL",
        "productId": "PROD_2",
        "retailerId": "SKU-002"
      }
    ]
  }
}
```

### Pedido de pagamento

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_REQUEST_PAYMENT_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200155000,
  "requestPayment": {
    "value": 299800,
    "currencyCode": "BRL",
    "expiration": 1736804955000,
    "requestPhone": "5511999999999",
    "paymentInfo": {
      "receiverPhone": "5511999999999",
      "value": 299800,
      "currencyCode": "BRL",
      "status": "WAITING_FOR_PAYER",
      "transactionStatus": "PENDING_SETUP"
    }
  }
}
```

### Pagamento recebido ou enviado

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_SEND_PAYMENT_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200160000,
  "sendPayment": {
    "paymentInfo": {
      "receiverPhone": "5511988887777",
      "value": 299800,
      "currencyCode": "BRL",
      "status": "COMPLETE",
      "transactionStatus": "COMPLETED"
    }
  }
}
```

### Revisão de pedido

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_REVIEW_ORDER_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200165000,
  "reviewOrder": {
    "currency": "BRL",
    "referenceId": "REF_ORDER_1",
    "orderRequestId": "ORDER_REQ_1",
    "orderStatus": "CREATED",
    "paymentStatus": "PENDING",
    "total": 299800,
    "subTotal": 289800,
    "discount": 0,
    "shipping": 10000,
    "tax": 0,
    "products": [
      {
        "name": "Plano Pro",
        "quantity": 1,
        "isCustomItem": false,
        "productId": "PROD_1",
        "value": 199900
      },
      {
        "name": "Suporte assistido",
        "quantity": 1,
        "isCustomItem": false,
        "productId": "PROD_2",
        "value": 99900
      }
    ]
  }
}
```

### Revisão e pagamento

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_REVIEW_PAY_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200170000,
  "reviewAndPay": {
    "type": "review_and_pay",
    "currency": "BRL",
    "referenceId": "REF_ORDER_2",
    "orderRequestId": "ORDER_REQ_2",
    "orderStatus": "CONFIRMED",
    "paymentStatus": "AUTHORIZED",
    "total": 299800,
    "subTotal": 289800,
    "discount": 0,
    "shipping": 10000,
    "tax": 0,
    "products": [
      {
        "name": "Plano Pro",
        "quantity": 1,
        "isCustomItem": false,
        "productId": "PROD_1",
        "value": 199900
      }
    ]
  }
}
```

## Canal, eventos e fixação

### Convite de admin de canal

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_NEWSLETTER_INVITE_1",
  "phone": "120363321090123456",
  "fromMe": false,
  "momment": 1736200175000,
  "isNewsletter": true,
  "newsletterAdminInvite": {
    "newsletterId": "120363321090123456@newsletter",
    "newsletterName": "Ofertas EZ API",
    "text": "Você foi convidado para administrar este canal.",
    "inviteExpiration": 1736804975000
  }
}
```

### Mensagem fixada ou desafixada

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_PIN_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200180000,
  "pinMessage": {
    "action": "pin",
    "pinDurationInSecs": 604800,
    "referencedMessage": {
      "messageId": "MSG_TEXT_1",
      "fromMe": false,
      "phone": "5511999999999",
      "participant": null
    }
  }
}
```

### Evento

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_EVENT_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200185000,
  "event": {
    "name": "Demonstração EZ API",
    "description": "Sessão para onboarding técnico",
    "canceled": false,
    "joinLink": "https://meet.google.com/abc-defg-hij",
    "scheduleTime": 1736812800000,
    "location": {
      "name": "Sala virtual",
      "url": "https://meet.google.com/abc-defg-hij"
    }
  }
}
```

### Resposta de evento

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_EVENT_RESPONSE_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200190000,
  "referenceMessageId": "MSG_EVENT_1",
  "eventResponse": {
    "response": "GOING",
    "responseFrom": "5511988887777",
    "time": 1736200189990,
    "referencedMessage": {
      "messageId": "MSG_EVENT_1",
      "fromMe": false,
      "phone": "5511999999999",
      "participant": null
    }
  }
}
```

## Notificações sistêmicas

### Ligação perdida de voz

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_CALL_MISSED_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200195000,
  "notification": "CALL_MISSED_VOICE",
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": "MSG_CALL_MISSED_1"
}
```

### Ligação perdida de vídeo

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_CALL_MISSED_2",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200197000,
  "notification": "CALL_MISSED_VIDEO",
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": "MSG_CALL_MISSED_2"
}
```

### Solicitação de entrada em grupo por link de convite

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_JOIN_REQ_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200200000,
  "notification": "MEMBERSHIP_APPROVAL_REQUEST",
  "notificationParameters": [
    "5511988887777"
  ],
  "requestMethod": "invite_link",
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": null
}
```

### Solicitação de entrada em grupo adicionada por participante

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_JOIN_REQ_2",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200205000,
  "notification": "MEMBERSHIP_APPROVAL_REQUEST",
  "notificationParameters": [
    "5511988887777",
    "5511977776666"
  ],
  "requestMethod": "non_admin_add",
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": null
}
```

### Solicitações revogadas pelo usuário

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_JOIN_REQ_3",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200210000,
  "notification": "REVOKED_MEMBERSHIP_REQUESTS",
  "notificationParameters": [
    "5511988887777"
  ]
}
```

### Admin promovido ou removido de canal

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_NEWSLETTER_ADMIN_1",
  "phone": "120363321090123456",
  "fromMe": false,
  "momment": 1736200215000,
  "isNewsletter": true,
  "notification": "NEWSLETTER_ADMIN_PROMOTE",
  "notificationParameters": [
    "5511988887777"
  ],
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": null
}
```

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_NEWSLETTER_ADMIN_2",
  "phone": "120363321090123456",
  "fromMe": false,
  "momment": 1736200216000,
  "isNewsletter": true,
  "notification": "NEWSLETTER_ADMIN_DEMOTE",
  "notificationParameters": [
    "5511988887777"
  ],
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": null
}
```

### Alteração do nome do WhatsApp conectado

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_PROFILE_NAME_1",
  "phone": "5511999999999",
  "fromMe": false,
  "momment": 1736200220000,
  "notification": "PROFILE_NAME_UPDATED",
  "profileName": "EZ API Oficial",
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": null
}
```

### Alteração da foto do WhatsApp conectado

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_PROFILE_PHOTO_1",
  "phone": "5511999999999",
  "fromMe": false,
  "momment": 1736200225000,
  "notification": "PROFILE_PICTURE_UPDATED",
  "updatedPhoto": "https://cdn.ezapi.dev/profiles/new-photo.jpg",
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": null
}
```

### Alteração de etiquetas de um chat

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_CHAT_LABEL_1",
  "phone": "5511988887777",
  "fromMe": false,
  "momment": 1736200230000,
  "notification": "CHAT_LABEL_ASSOCIATION",
  "notificationParameters": [
    {
      "phone": "5511988887777",
      "label": "vip",
      "assigned": true
    },
    {
      "phone": "5511977776666",
      "label": "financeiro",
      "assigned": false
    }
  ],
  "referenceMessageId": null,
  "externalAdReply": null,
  "expiresAt": null,
  "code": null,
  "callId": null
}
```

### Wrapper de visualização única

```json theme={null}
{
  "type": "ReceivedCallback",
  "instanceId": "INSTANCE_1",
  "messageId": "MSG_VIEW_ONCE_1",
  "phone": "5511999999999",
  "fromMe": true,
  "momment": 1736200235000,
  "viewOnce": true,
  "waitingMessage": true
}
```

## Outros eventos de webhook

### `DeliveryCallback`

```json theme={null}
{
  "phone": "5511999999999",
  "messageId": "3EB047ED70306656281B34",
  "id": "3EB047ED70306656281B34",
  "type": "DeliveryCallback",
  "instanceId": "INSTANCE_1"
}
```

Em falha de envio, o evento pode incluir:

```json theme={null}
{
  "phone": "5511999999999",
  "messageId": "3EB047ED70306656281B34",
  "id": "3EB047ED70306656281B34",
  "type": "DeliveryCallback",
  "instanceId": "INSTANCE_1",
  "status": "ERROR",
  "error": "rate limit",
  "statusCode": 429
}
```

### `ConnectedCallback`

```json theme={null}
{
  "type": "ConnectedCallback",
  "connected": true,
  "momment": 1736200240000,
  "instanceId": "INSTANCE_1",
  "phone": "5511999999999"
}
```

### `DisconnectedCallback`

```json theme={null}
{
  "momment": 1736200245000,
  "error": "connection lost",
  "disconnected": true,
  "type": "DisconnectedCallback",
  "instanceId": "INSTANCE_1"
}
```

### `MessageStatusCallback`

```json theme={null}
{
  "instanceId": "INSTANCE_1",
  "status": "READ",
  "ids": [
    "3EB047ED70306656281B34"
  ],
  "momment": 1736200250000,
  "phoneDevice": 0,
  "phone": "5511999999999",
  "type": "MessageStatusCallback",
  "isGroup": false
}
```

Valores observados para `status`: `SENT`, `RECEIVED`, `READ`, `READ_BY_ME`, `PLAYED` e `ERROR`.

### `PresenceChatCallback`

```json theme={null}
{
  "type": "PresenceChatCallback",
  "phone": "5511999999999",
  "status": "COMPOSING",
  "lastSeen": 1736200255,
  "instanceId": "INSTANCE_1"
}
```

Valores comuns para `status`: `AVAILABLE`, `UNAVAILABLE`, `COMPOSING`, `PAUSED` e `RECORDING`.