Payloads de webhooks

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.

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.

Envelope base do `ReceivedCallback`

{
  "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.

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

Texto

Texto simples

{
  "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

{
  "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"
  }
}

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

Texto vindo de anúncio ou CTA para WhatsApp

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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
  }
}

GIFs e PTVs não possuem bloco separado na EZ API. Ambos chegam normalizados em video.

Documento ou arquivo

{
  "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

{
  "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

{
  "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
  }
}

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.

Contato e localização

Contato

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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"
        }
      }
    ]
  }
}

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.

Template com cabeçalho de imagem

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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
}

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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`

{
  "phone": "5511999999999",
  "messageId": "3EB047ED70306656281B34",
  "id": "3EB047ED70306656281B34",
  "type": "DeliveryCallback",
  "instanceId": "INSTANCE_1"
}

Em falha de envio, o evento pode incluir:

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

`ConnectedCallback`

{
  "type": "ConnectedCallback",
  "connected": true,
  "momment": 1736200240000,
  "instanceId": "INSTANCE_1",
  "phone": "5511999999999"
}

`DisconnectedCallback`

{
  "momment": 1736200245000,
  "error": "connection lost",
  "disconnected": true,
  "type": "DisconnectedCallback",
  "instanceId": "INSTANCE_1"
}

`MessageStatusCallback`

{
  "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`

{
  "type": "PresenceChatCallback",
  "phone": "5511999999999",
  "status": "COMPOSING",
  "lastSeen": 1736200255,
  "instanceId": "INSTANCE_1"
}

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

Introdução

Instância

Mensagens

Conversas

Contatos

Privacidade

Grupos

Status

Fila de mensagens

WhatsApp Business

Webhooks

​Visão geral

​Envelope base do ReceivedCallback

​Texto

​Texto simples

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

​Texto vindo de anúncio ou CTA para WhatsApp

​Mídia

​Imagem

​Áudio

​Vídeo

​GIF e PTV

​Documento ou arquivo

​Sticker

​Resposta a status com imagem

​Contato e localização

​Contato

​Localização

​Respostas interativas

​Resposta de botão

​Resposta de lista

​Templates, botões e carrossel

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

​Template com cabeçalho de imagem

​Template com cabeçalho de vídeo

​Template com cabeçalho de documento

​Template com cabeçalho de localização

​Mensagem de botões com imagem

​Mensagem de botões com vídeo

​Carrossel

​Reações e enquetes

​Reação

​Enquete

​Resposta de enquete

​Catálogo, carrinho, pedidos e pagamentos

​Produto

​Carrinho ou pedido simples

​Pedido de pagamento

​Pagamento recebido ou enviado

​Revisão de pedido

​Revisão e pagamento

​Canal, eventos e fixação

​Convite de admin de canal

​Mensagem fixada ou desafixada

​Evento

​Resposta de evento

​Notificações sistêmicas

​Ligação perdida de voz

​Ligação perdida de vídeo

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

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

​Solicitações revogadas pelo usuário

​Admin promovido ou removido de canal

​Alteração do nome do WhatsApp conectado

​Alteração da foto do WhatsApp conectado

​Alteração de etiquetas de um chat

​Wrapper de visualização única

​Outros eventos de webhook

​DeliveryCallback

​ConnectedCallback

​DisconnectedCallback

​MessageStatusCallback

​PresenceChatCallback

Visão geral

Envelope base do `ReceivedCallback`

Texto

Texto simples

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

Texto vindo de anúncio ou CTA para WhatsApp

Mídia

Imagem

Áudio

Vídeo

GIF e PTV

Documento ou arquivo

Sticker

Resposta a status com imagem

Contato e localização

Contato

Localização

Respostas interativas

Resposta de botão

Resposta de lista

Templates, botões e carrossel

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

Template com cabeçalho de imagem

Template com cabeçalho de vídeo

Template com cabeçalho de documento

Template com cabeçalho de localização

Mensagem de botões com imagem

Mensagem de botões com vídeo

Carrossel

Reações e enquetes

Reação

Enquete

Resposta de enquete

Catálogo, carrinho, pedidos e pagamentos

Produto

Carrinho ou pedido simples

Pedido de pagamento

Pagamento recebido ou enviado

Revisão de pedido

Revisão e pagamento

Canal, eventos e fixação

Convite de admin de canal

Mensagem fixada ou desafixada

Evento

Resposta de evento

Notificações sistêmicas

Ligação perdida de voz

Ligação perdida de vídeo

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

Solicitação de entrada em grupo adicionada por participante

Solicitações revogadas pelo usuário

Admin promovido ou removido de canal

Alteração do nome do WhatsApp conectado

Alteração da foto do WhatsApp conectado

Alteração de etiquetas de um chat

Wrapper de visualização única

Outros eventos de webhook

`DeliveryCallback`

`ConnectedCallback`

`DisconnectedCallback`

`MessageStatusCallback`

`PresenceChatCallback`