WEBHOOKS

Eventos & Webhooks

A WAME API envia notificações em tempo real para a sua URL sempre que algo acontece na instância — mensagens recebidas, status de entrega, conexão, chamadas e mais. Os exemplos abaixo são carregados diretamente da API.

REST API Índice de exemplos

Introdução

Configure as URLs de webhook da instância pela REST API. Cada tipo de evento pode ter a sua própria URL — deixe em branco para usar a URL padrão (webhookMessage). A entrega é feita via POST com corpo JSON.

Formato webhookFormat: "meta"

O foco deste modelo é seguir o mesmo padrão do webhook oficial do WhatsApp — o WhatsApp Cloud API da Meta. Ao definir "webhookFormat": "meta" os payloads chegam no mesmo envelope da Cloud API, então você reaproveita o mesmo parser da integração oficial. Ver referência da Meta

curl

curl -X PUT "https://us.api-wa.me/YOUR_KEY/instance" \
  -H "Content-Type: application/json" \
  -d '{
    "allowWebhook": true,
    "allowNumber": "all",
    "webhookFormat": "meta",
    "webhookMessage": "https://seu-servidor.com/webhook",
    "webhookGroup": "",
    "webhookConnection": "",
    "webhookQrCode": "",
    "webhookMessageFromMe": "",
    "webhookHistory": ""
  }'

Responda com 200 OK o mais rápido possível. Falhas e reenvios podem ser acompanhados em GET /{key}/instance/webhook/statistics.

Estrutura do payload

Com webhookFormat: "meta" os webhooks seguem o mesmo formato do WhatsApp Cloud API da Meta . O envelope é sempre o mesmo; o que muda é o campo changes[].field e o conteúdo de value.

object — sempre "wame".
entry[].id — identificador da instância.
entry[].changes[].field — tipo do evento: messages, presence, connection, qrcode, call, groups, health.
entry[].changes[].value — dados do evento.

Mensagens

field: messages

Mensagens recebidas e status de entrega.

Mensagem de texto

message-text

Texto simples enviado por um contato.

POSTwebhook payload · message-text.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_TEXT",
                "timestamp": "1700000000",
                "type": "text",
                "text": {
                  "body": "Olá!"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Mensagem de imagem

message-image

Imagem com legenda opcional.

POSTwebhook payload · message-image.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_IMG",
                "timestamp": "1700000000",
                "type": "image",
                "image": {
                  "id": "WAMID_IMG",
                  "url": "https://us.api-wa.me/your-instance-id/message/WAMID_IMG/media",
                  "mime_type": "image/jpeg",
                  "sha256": "YWJj",
                  "caption": "foto"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Mensagem de áudio

message-audio

Áudio ou mensagem de voz (PTT).

POSTwebhook payload · message-audio.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_AUD",
                "timestamp": "1700000000",
                "type": "audio",
                "audio": {
                  "id": "WAMID_AUD",
                  "url": "https://us.api-wa.me/your-instance-id/message/WAMID_AUD/media",
                  "mime_type": "audio/ogg",
                  "sha256": "YWJj",
                  "voice": true
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Mensagem de vídeo

message-video

Vídeo com legenda opcional.

POSTwebhook payload · message-video.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_VID",
                "timestamp": "1700000000",
                "type": "video",
                "video": {
                  "id": "WAMID_VID",
                  "url": "https://us.api-wa.me/your-instance-id/message/WAMID_VID/media",
                  "mime_type": "video/mp4",
                  "sha256": "YWJj",
                  "caption": "v"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Mensagem de documento

message-document

Arquivo/documento (PDF, planilha, etc.).

POSTwebhook payload · message-document.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_DOC",
                "timestamp": "1700000000",
                "type": "document",
                "document": {
                  "id": "WAMID_DOC",
                  "url": "https://us.api-wa.me/your-instance-id/message/WAMID_DOC/media",
                  "mime_type": "application/pdf",
                  "sha256": "YWJj",
                  "filename": "orcamento.pdf",
                  "caption": "PDF"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Figurinha (sticker)

message-sticker

Sticker estático ou animado.

POSTwebhook payload · message-sticker.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_STK",
                "timestamp": "1700000000",
                "type": "sticker",
                "sticker": {
                  "id": "WAMID_STK",
                  "url": "https://us.api-wa.me/your-instance-id/message/WAMID_STK/media",
                  "mime_type": "image/webp",
                  "sha256": "YWJj",
                  "animated": false
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Localização

message-location

Coordenadas de latitude e longitude.

POSTwebhook payload · message-location.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_LOC",
                "timestamp": "1700000000",
                "type": "location",
                "location": {
                  "latitude": -25.4,
                  "longitude": -49.2,
                  "name": "Curitiba",
                  "address": "PR"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Contatos

message-contacts

Um ou mais contatos compartilhados (vCard).

POSTwebhook payload · message-contacts.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_CON",
                "timestamp": "1700000000",
                "type": "contacts",
                "contacts": [
                  {
                    "name": {
                      "formatted_name": "Beltrano"
                    },
                    "vcard": "BEGIN:VCARD..."
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Reação

message-reaction

Emoji de reação a uma mensagem existente.

POSTwebhook payload · message-reaction.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_RCT",
                "timestamp": "1700000000",
                "type": "reaction",
                "reaction": {
                  "message_id": "ORIG1",
                  "emoji": "👍"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Message Reaction Removed

message-reaction-removed

POSTwebhook payload · message-reaction-removed.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_RCT2",
                "timestamp": "1700000000",
                "type": "reaction",
                "reaction": {
                  "message_id": "ORIG1"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Resposta de botão

message-button

Retorno da interação com um botão.

POSTwebhook payload · message-button.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_BTN",
                "timestamp": "1700000000",
                "type": "button",
                "button": {
                  "text": "Sim",
                  "payload": "btn_yes"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Resposta de lista

message-interactive-list

Item selecionado em uma lista interativa.

POSTwebhook payload · message-interactive-list.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_LST",
                "timestamp": "1700000000",
                "type": "interactive",
                "interactive": {
                  "type": "list_reply",
                  "list_reply": {
                    "id": "row_1",
                    "title": "Opção A",
                    "description": "desc"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Message Interactive Button

message-interactive-button

POSTwebhook payload · message-interactive-button.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_TBTN",
                "timestamp": "1700000000",
                "type": "interactive",
                "interactive": {
                  "type": "button_reply",
                  "button_reply": {
                    "id": "btn_1",
                    "title": "Confirmar"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Mensagem não suportada

message-unsupported

Tipo de mensagem ainda não tratado.

POSTwebhook payload · message-unsupported.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_UNS",
                "timestamp": "1700000000",
                "type": "unsupported",
                "errors": [
                  {
                    "code": 131051,
                    "title": "Unsupported message type",
                    "message": "Message type pollCreationMessageV3 is not supported",
                    "error_data": {
                      "details": "pollCreationMessageV3"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Resposta (reply)

message-reply-context

Mensagem citando outra mensagem (contexto).

POSTwebhook payload · message-reply-context.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_RPL",
                "timestamp": "1700000000",
                "type": "text",
                "text": {
                  "body": "respondendo"
                },
                "context": {
                  "from": "5511777776666",
                  "id": "QUOTED1"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Referral (anúncio)

message-referral

Mensagem originada de um anúncio Click-to-WhatsApp.

POSTwebhook payload · message-referral.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511999998888"
              }
            ],
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_ADS",
                "timestamp": "1700000000",
                "type": "text",
                "text": {
                  "body": "vim do anúncio"
                },
                "referral": {
                  "source_url": "https://fb.me/x",
                  "source_id": "AD123",
                  "source_type": "ad",
                  "headline": "Promo",
                  "body": "Fale conosco",
                  "media_type": "image",
                  "thumbnail_url": "https://cdn/t.jpg",
                  "ctwa_clid": "CLID9"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Mensagem de grupo

message-group

Mensagem enviada dentro de um grupo.

POSTwebhook payload · message-group.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Fulano"
                },
                "wa_id": "5511777776666"
              }
            ],
            "messages": [
              {
                "from": "5511777776666",
                "group_id": "16479379001-1580667835@g.us",
                "id": "WAMID_GRP",
                "timestamp": "1700000000",
                "type": "text",
                "text": {
                  "body": "oi grupo"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Mensagem enviada por você

message-from-me

Eco de uma mensagem enviada pela própria instância.

POSTwebhook payload · message-from-me.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Eu"
                },
                "wa_id": "5566996852025"
              }
            ],
            "messages": [
              {
                "from": "5566996852025",
                "id": "WAMID_OUT",
                "timestamp": "1700000000",
                "type": "text",
                "text": {
                  "body": "msg minha"
                },
                "from_me": true
              }
            ]
          }
        }
      ]
    }
  ]
}

Message Edit

message-edit

POSTwebhook payload · message-edit.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "messages": [
              {
                "from": "5511999998888",
                "id": "WAMID_ORIG",
                "timestamp": "1700000000",
                "type": "edit",
                "edit": {
                  "original_message_id": "WAMID_ORIG",
                  "message": {
                    "type": "text",
                    "text": {
                      "body": "mensagem corrigida"
                    }
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Status: enviada

status-sent

Mensagem foi enviada ao servidor.

POSTwebhook payload · status-sent.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "statuses": [
              {
                "id": "WAMID_TEXT",
                "status": "sent",
                "timestamp": "1700000000",
                "recipient_id": "5511999998888",
                "conversation": {
                  "id": null,
                  "expiration_timestamp": null,
                  "origin": {
                    "type": null
                  }
                },
                "pricing": {
                  "billable": null,
                  "pricing_model": null,
                  "type": null,
                  "category": null
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Status: entregue

status-delivered

Mensagem entregue no dispositivo do destinatário.

POSTwebhook payload · status-delivered.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "statuses": [
              {
                "id": "WAMID_TEXT",
                "status": "delivered",
                "timestamp": "1700000000",
                "recipient_id": "5511999998888",
                "conversation": {
                  "id": null,
                  "expiration_timestamp": null,
                  "origin": {
                    "type": null
                  }
                },
                "pricing": {
                  "billable": null,
                  "pricing_model": null,
                  "type": null,
                  "category": null
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Status: lida

status-read

Mensagem lida pelo destinatário.

POSTwebhook payload · status-read.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "statuses": [
              {
                "id": "WAMID_TEXT",
                "status": "read",
                "timestamp": "1700000000",
                "recipient_id": "5511999998888",
                "conversation": {
                  "id": null,
                  "expiration_timestamp": null,
                  "origin": {
                    "type": null
                  }
                },
                "pricing": {
                  "billable": null,
                  "pricing_model": null,
                  "type": null,
                  "category": null
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Status Played

status-played

POSTwebhook payload · status-played.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "statuses": [
              {
                "id": "WAMID_AUD",
                "status": "played",
                "timestamp": "1700000000",
                "recipient_id": "5511999998888",
                "conversation": {
                  "id": null,
                  "expiration_timestamp": null,
                  "origin": {
                    "type": null
                  }
                },
                "pricing": {
                  "billable": null,
                  "pricing_model": null,
                  "type": null,
                  "category": null
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Status Group

status-group

POSTwebhook payload · status-group.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "statuses": [
              {
                "id": "WAMID_GRP",
                "status": "delivered",
                "timestamp": "1700000000",
                "recipient_id": "16479379001-1580667835@g.us",
                "recipient_type": "group",
                "recipient_participant_id": "5511999998888",
                "conversation": {
                  "id": null,
                  "expiration_timestamp": null,
                  "origin": {
                    "type": null
                  }
                },
                "pricing": {
                  "billable": null,
                  "pricing_model": null,
                  "type": null,
                  "category": null
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Status: falha

status-failed

Falha ao entregar a mensagem.

POSTwebhook payload · status-failed.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "statuses": [
              {
                "id": "WAMID_TEXT",
                "status": "failed",
                "timestamp": "1700000000",
                "recipient_id": "5511999998888",
                "conversation": {
                  "id": null,
                  "expiration_timestamp": null,
                  "origin": {
                    "type": null
                  }
                },
                "pricing": {
                  "billable": null,
                  "pricing_model": null,
                  "type": null,
                  "category": null
                },
                "errors": [
                  {
                    "code": 463,
                    "title": "Conta restringida",
                    "message": "Conta restringida",
                    "error_data": {
                      "details": "463"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Recibo (receipt)

receipt

Confirmação de recebimento/leitura.

POSTwebhook payload · receipt.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "statuses": [
              {
                "id": "WAMID_TEXT",
                "status": "read",
                "timestamp": "1700000005",
                "recipient_id": "5511777776666",
                "conversation": {
                  "id": null,
                  "expiration_timestamp": null,
                  "origin": {
                    "type": null
                  }
                },
                "pricing": {
                  "billable": null,
                  "pricing_model": null,
                  "type": null,
                  "category": null
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Presença

field: presence

Digitando, gravando, online/offline.

Presença

presence

Estado de presença de um contato.

POSTwebhook payload · presence.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "presence",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "presence": {
              "wa_id": "160301265768606",
              "status": "available"
            }
          }
        }
      ]
    }
  ]
}

Conexão

field: connection

Abertura e encerramento da conexão da instância.

Conexão aberta

connection-open

A instância conectou-se ao WhatsApp.

POSTwebhook payload · connection-open.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "connection",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "connection": {
              "status": "open",
              "code": 200
            }
          }
        }
      ]
    }
  ]
}

Conexão encerrada

connection-close

A instância desconectou-se.

POSTwebhook payload · connection-close.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "connection",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "connection": {
              "status": "close",
              "code": 1004,
              "reason": "disconnected"
            }
          }
        }
      ]
    }
  ]
}

QR Code

field: qrcode

Novo QR Code gerado para pareamento.

QR Code

qrcode

Novo QR Code disponível para leitura.

POSTwebhook payload · qrcode.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "qrcode",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "qrcode": {
              "code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
            }
          }
        }
      ]
    }
  ]
}

Chamadas

field: call

Chamadas recebidas de voz e vídeo.

Chamada

call

Chamada recebida de voz ou vídeo.

POSTwebhook payload · call.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "call",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "calls": [
              {
                "id": "CALL1",
                "from": "5511999998888",
                "status": "offer",
                "is_video": false,
                "is_group": false,
                "timestamp": "1700000000"
              }
            ]
          }
        }
      ]
    }
  ]
}

Grupos

field: groups

Alterações em participantes e metadados de grupos.

Participantes do grupo

group-participants

Entrada, saída, promoção ou remoção de membros.

POSTwebhook payload · group-participants.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "groups",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "groups": {
              "event": "participants_updated",
              "id": "16479379001-1580667835@g.us",
              "action": "add",
              "participants": [
                "5511999998888@s.whatsapp.net"
              ]
            }
          }
        }
      ]
    }
  ]
}

Atualização de grupo

group-update

Alteração de nome, descrição ou configurações.

POSTwebhook payload · group-update.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "groups",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "groups": {
              "event": "update",
              "data": [
                {
                  "id": "16479379001-1580667835@g.us",
                  "subject": "Novo nome"
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Health

field: health

Sinal de saúde da instância.

Health check

health

Batimento de saúde emitido pela instância.

POSTwebhook payload · health.json

{
  "object": "wame",
  "entry": [
    {
      "id": "wame.eW91ci1pbnN0YW5jZS1pZA",
      "changes": [
        {
          "field": "health",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5566996852025",
              "phone_number_id": "your-instance-id"
            },
            "health": {
              "status": "restricted",
              "previous": "healthy",
              "reason": "many 463",
              "should_pause": true,
              "should_rotate": false
            }
          }
        }
      ]
    }
  ]
}

Contexto para AI

Arquivos .md prontos para colar em assistentes de AI (Claude, ChatGPT, Copilot, Cursor). Eles descrevem os webhooks e a API em formato otimizado para que a AI te ajude a integrar.

Webhooks (llms/webhook)

Referência completa dos eventos de webhook e formatos (native, meta, both).

Abrir no Claude Visualizar

API completa (llms)

Contexto de toda a REST API: endpoints, parâmetros e exemplos.

Abrir no Claude Visualizar

WAME API — Eventos & Webhooks

Começar Agora