Synergy Connect

Documentação

EntrarCriar conta

Webhooks

Webhooks entregam em uma URL sua os eventos do WhatsApp, no envelope da Meta (object: "whatsapp_business_account"), assinados como a Meta assina. Uma biblioteca feita para os webhooks da Meta valida com o secret do webhook no lugar do app secret.

Configurar#

Pelo app: Configurações → API e webhooks → Webhooks. Pela API, com uma chave de escopo management:

Regras do cadastro:

  • A URL é https, pública, sem usuário e senha, e nunca um endereço da própria Synergy.
  • Ela se prova antes de valer. Padrão (verification: "ping"): um POST assinado com o evento synergy_ping que a URL responde com 2xx em até 5 s. Alternativa ("meta"): o handshake hub.challenge da Meta, que exige verifyToken.
  • fields lista os eventos. statuses filtra por status com statuses: [...] (null = todos). instanceIds: null cobre todos os números, inclusive os conectados depois.
  • Até 20 webhooks por organização, até 10 headers próprios por webhook (nunca devolvidos; só os nomes em headerNames).
  • O secret (32 caracteres hexadecimais) só aparece na criação e em POST /v1/webhooks/{hook_id}/rotate-secret.
Exemplo

curl

curl -X POST 'https://api.synergyconnect.com.br/v1/webhooks' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://hooks.example.com/synergy","fields":["messages","statuses"],"instanceIds":null}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://hooks.example.com/synergy',
    fields: ['messages', 'statuses'],
    instanceIds: null,
  }),
});
const { row, secret } = await res.json(); // guarde o secret: só aparece aqui e em rotate-secret

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={"url": "https://hooks.example.com/synergy", "fields": ["messages", "statuses"], "instanceIds": None},
)
data = res.json()  # data["secret"]: guarde, só aparece aqui e em rotate-secret

Eventos#

fieldsQuando dispara
messagesMensagem recebida de um cliente
statusesStatus de uma mensagem enviada (sai com changes[].field igual a messages)
smb_message_echoesMensagem enviada pela empresa fora da API (app WhatsApp Business ou Inbox)
synergy_conversationsUma conversa da automação mudou de mãos por ação de uma pessoa
message_template_status_update, message_template_quality_update, template_category_updateModelos de mensagem
phone_number_quality_update, phone_number_name_updateNúmero
account_update, account_alerts, business_capability_updateConta
smb_app_state_sync, history, calls, group_lifecycle_update, group_participant_update, group_settings_updateCoexistência, chamadas e grupos

Exceto synergy_conversations (definido pela Synergy), o value é o da Meta, repassado como chegou. A resposta de um WhatsApp Flow chega em messages (veja WhatsApp Flows). Exemplo de messages:

Um envio feito pela API pública não gera smb_message_echoes: foi a própria integração que enviou.

JSON
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "102290129340398",
    "time": 1767225600,
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "554430000000", "phone_number_id": "106540352242922" },
        "contacts": [{ "profile": { "name": "Teste Synergy" }, "wa_id": "5511999999999" }],
        "messages": [{ "from": "5511999999999", "id": "wamid.TEST.6f1c2a0e-3b7d-4c1a-9f52-0a8d5e7b9c11", "timestamp": "1767225600", "type": "text", "text": { "body": "Evento de teste enviado pela Synergy" } }]
      }
    }]
  }]
}

A requisição#

POST em JSON, com os headers:

HeaderValor
Content-Typeapplication/json
User-AgentSynergy-Webhooks/1.0
X-Hub-Signature-256sha256=<64 hex>, a assinatura do corpo
X-Synergy-Delivery-IdO id da entrega, igual em toda retentativa do mesmo envelope
X-Synergy-Instance-IdO id do número na Synergy. Ausente em eventos da conta (WABA), no synergy_ping e no teste sem número ativo

Responda 2xx em até 5 s. O corpo da resposta nunca é lido. Redirecionamentos (3xx) não são seguidos e contam como falha.

Validar a assinatura#

X-Hub-Signature-256 é sha256= mais o HMAC-SHA256, em hexadecimal minúsculo, dos bytes exatos do corpo, com o secret do webhook como chave (texto UTF-8, usado como está). Reserializar o JSON muda os bytes e invalida a assinatura. Compare em tempo constante; se for diferente, responda 401 e não processe.

Vetor de teste: com o secret 0123456789abcdef0123456789abcdef e o corpo

o header é sha256=b34c62852bf9eb4132dbac56d4b909a1e62d3df61b21807329b6c1f4d59ec77e.

Exemplo

JavaScript

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: os bytes EXATOS do corpo recebido (Buffer), antes de qualquer JSON.parse
export function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}

// Express: express.raw({ type: 'application/json' }) entrega req.body como Buffer
app.post('/webhooks/synergy', express.raw({ type: 'application/json' }), (req, res) => {
  if (!isValidSignature(req.body, req.get('X-Hub-Signature-256'), process.env.SYNERGY_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // responda primeiro, em até 5 s; processe depois
  const deliveryId = req.get('X-Synergy-Delivery-Id'); // descarte o que já foi processado com este id
  handle(deliveryId, JSON.parse(req.body));
});

Python

import hashlib
import hmac
import os

from flask import Flask, request

app = Flask(__name__)


def is_valid_signature(raw_body: bytes, signature_header: str | None, secret: str) -> bool:
    # raw_body: os bytes EXATOS do corpo recebido, antes de qualquer json.loads
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")


@app.post("/webhooks/synergy")
def synergy_webhook():
    raw_body = request.get_data()
    if not is_valid_signature(raw_body, request.headers.get("X-Hub-Signature-256"), os.environ["SYNERGY_WEBHOOK_SECRET"]):
        return "", 401
    delivery_id = request.headers.get("X-Synergy-Delivery-Id")  # descarte o que já foi processado com este id
    enqueue(delivery_id, raw_body)  # responda em até 5 s; processe depois
    return "", 200
Texto
{"object":"whatsapp_business_account","entry":[{"id":"0","time":1767225600,"changes":[{"field":"synergy_ping","value":{"messaging_product":"whatsapp","ping":true,"timestamp":"1767225600"}}]}]}

Retentativas#

  • Primeira tentativa: logo depois de a Synergy responder 200 à Meta.
  • Falha (fora de 2xx, erro de rede ou timeout de 5 s): o evento vai para a fila do número e é reenviado com espera crescente: 10 s, 30 s, 1 min, 5 min, 15 min e, daí em diante, 30 min.
  • degraded: três falhas em 60 s, ou um timeout, deixam o webhook degradado naquele número: os eventos novos vão direto para a fila, em ordem. Volta a healthy quando a fila esvazia.
  • Lotes: a fila sai em envelopes de até 100 eventos ou 512 KB, 6 por vez.
  • suspended: se o evento mais antigo da fila passa de 24 h, ou a fila do número passa de 200 MB, o webhook é suspenso naquele número e a fila é descartada (contada em dropped). Qualquer PATCH do webhook (inclusive {"enabled": true}) ou rotate-secret recomeça limpo.
  • Uma tentativa só: eventos da conta (WABA, como modelos, qualidade e conta), o evento de teste e o synergy_ping não têm fila nem retentativa.
  • Manual: POST /v1/webhooks/{hook_id}/retry antecipa a próxima tentativa; POST /v1/webhooks/{hook_id}/replay com {"since": <ms>} reenfileira os eventos guardados (até 5.000 por número; 7 dias de statuses e 30 dias do resto). Ecos do Inbox, synergy_conversations e eventos da conta não ficam guardados para replay.
  • Sem a feature api no plano, ou com a conta suspensa, nada é enviado nem guardado.
  • Acompanhe com GET /v1/webhooks/health (estado, fila, último erro) e GET /v1/webhooks/stats?hours=168 (entregas, falhas, latência).

Idempotência#

A entrega é ao menos uma vez: o mesmo evento pode chegar mais de uma vez, e a ordem só é garantida dentro da fila de um número. X-Synergy-Delivery-Id é derivado do conteúdo ou do fato que gerou o evento, não da tentativa: a retentativa, a reentrega da Meta e o replay chegam com o mesmo id. Guarde os ids processados e descarte os repetidos.

Quando a fila agrupa vários eventos, o id é o do primeiro seguido de +<quantidade> (por exemplo ev-3f9a…:0b9c4d1e+12). Se a primeira tentativa chegou mas estourou os 5 s, o mesmo evento pode aparecer sob dois ids: para garantia por evento, descarte também pelo messages[].id ou pelo par statuses[].id + status.

Exemplo

JavaScript

const seen = new Set(); // em produção, use um armazenamento com expiração
function handle(deliveryId, envelope) {
  if (seen.has(deliveryId)) return;
  seen.add(deliveryId);
  for (const change of envelope.entry[0].changes) {
    // processe change.field e change.value
  }
}

Python

seen = set()  # em produção, use um armazenamento com expiração


def handle(delivery_id, envelope):
    if delivery_id in seen:
        return
    seen.add(delivery_id)
    for change in envelope["entry"][0]["changes"]:
        pass  # processe change["field"] e change["value"]

Testar#

POST /v1/webhooks/{hook_id}/test envia agora um evento messages de exemplo, assinado e com os headers do webhook, com X-Synergy-Delivery-Id: test-<uuid> e uma tentativa só. É enviado mesmo que o webhook não assine messages, e mesmo desativado. Responde { "ok": true } se a URL devolveu 2xx; 502 com HTTP <status> ou timeout se não aceitou. No app, a ação "Testar" do webhook faz o mesmo.

Exemplo

curl

curl -X POST "https://api.synergyconnect.com.br/v1/webhooks/$HOOK_ID/test" \
  -H "Authorization: Bearer $SYNERGY_API_KEY"

JavaScript

const res = await fetch(`https://api.synergyconnect.com.br/v1/webhooks/${hookId}/test`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.SYNERGY_API_KEY}` },
});
console.log(res.status, await res.json());

Python

res = requests.post(
    f"https://api.synergyconnect.com.br/v1/webhooks/{hook_id}/test",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
)
print(res.status_code, res.json())

Catálogo de eventos#

31 eventos podem chegar à URL de um webhook. Os da Meta trazem o value dela, repassado como chegou; os da Synergy são montados pelo código da Synergy. O formato do envelope e a assinatura são os da Meta.

Eventos de webhook
EventoQuando chegaOrigem
messagesMensagem recebida de um clienteMeta
statusesStatus de uma mensagem enviadaMeta
smb_message_echoesMensagem enviada pela empresa fora da APIMeta ou Synergy
smb_app_state_syncContatos do aplicativo WhatsApp Business (coexistência)Meta
historyHistórico de conversas do aplicativo WhatsApp Business (coexistência)Meta
callsEventos de chamadaMeta
message_template_status_updateStatus de um modelo de mensagem mudouMeta
message_template_quality_updateQualidade de um modelo de mensagem mudouMeta
template_category_updateCategoria de um modelo de mensagem mudouMeta
phone_number_quality_updateQualidade de um número mudouMeta
phone_number_name_updateAtualização do nome de um númeroMeta
account_updateAtualização da conta do WhatsApp BusinessMeta
account_alertsAlertas da conta do WhatsApp BusinessMeta
business_capability_updateAtualização das capacidades da contaMeta
group_lifecycle_updateCiclo de vida de um grupoMeta
group_participant_updateParticipantes de um grupoMeta
group_settings_updateConfigurações de um grupoMeta
messaging_postbacksToque em botão, Ice Breaker ou item do menu (Instagram)Meta
message_reactionsReação a uma mensagem (Instagram)Meta
messaging_seenMensagem vista pelo contato (Instagram)Meta
messaging_referralConversa aberta por um link ig.me ou por um anúncio (Instagram)Meta
message_editMensagem editada pelo contato (Instagram)Meta
messaging_optinsOpt-in de notificação (Instagram)Meta
commentsComentário em uma publicação da conta (Instagram)Meta
live_commentsComentário em uma Live da conta (Instagram)Meta
mentionsMenção à conta em um comentário ou legenda (Instagram)Meta
synergy_conversationsUma conversa automatizada mudou de mãosSynergy
synergy_comment_actionsResultado de uma ação sobre um comentário (Instagram)Synergy
synergy_journeysEvento de uma JornadaSynergy
synergy_onboardingO resultado de um cadastro hospedado de númeroSynergy
synergy_pingEvento de verificação da URLSynergy

Cabeçalhos de toda entrega#

Cabeçalhos de toda entrega
NomeTipoObrigatórioDescrição
Content-TypestringobrigatórioSempre JSON.
User-AgentstringobrigatórioFixo.
X-Hub-Signature-256stringobrigatórioA assinatura do corpo, no formato que a Meta usa nos próprios webhooks.
X-Synergy-Delivery-IdstringobrigatórioO id da entrega: igual em toda retentativa do mesmo envelope. É a chave de idempotência do receptor.
X-Synergy-Instance-IdstringopcionalO id do número na Synergy (o mesmo de instanceIds). Ausente nos eventos da conta (WABA), no synergy_ping e no teste de uma organização sem número ativo.
X-Synergy-SignaturestringopcionalA assinatura com carimbo de tempo (aditiva, ao lado de X-Hub-Signature-256): HMAC-SHA256 com o secret sobre <t>.<X-Synergy-Delivery-Id>.<corpo cru>. t é o momento da tentativa (muda a cada retentativa; o id não). Confira com tolerância de 300 s e só então confie no id: fecha o replay de uma entrega capturada. Um receptor que não a conhece continua conferindo X-Hub-Signature-256.

messages#

Mensagem recebida de um cliente · origem: Meta

Dispara quando a Meta entrega uma mensagem de um cliente para o número: texto, mídia, localização, contatos, reação, toque em botão, resposta de lista ou de flow, pedido, aviso do sistema, ou uma mensagem que a Cloud API não suporta. O value sai como a Meta mandou, byte a byte — a Synergy não traduz nem completa nada; se a Meta juntou statuses no mesmo evento e o webhook não assina statuses, só eles são removidos. messages[].type diz qual objeto traz o conteúdo (veja os exemplos, um por tipo).

Assine com "messages" em fields. No envelope, changes[].field é messages.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

A mídia recebida vem só com o id: baixe com GET /{version}/{media_id}?phone_number_id=…, que devolve a url de download desta API (com a mesma chave).

Responda a uma mensagem com o id dela em context.message_id no envio. Uma confirmação de leitura usa o mesmo id (status: "read").

Repetições: a Meta pode reenviar o mesmo evento; ele chega com o mesmo X-Synergy-Delivery-Id, e messages[].id também não muda.

  • A mídia recebida vem só com o id: baixe com GET /{version}/{media_id}?phone_number_id=…, que devolve a url de download desta API (com a mesma chave).
  • Responda a uma mensagem com o id dela em context.message_id no envio. Uma confirmação de leitura usa o mesmo id (status: "read").
  • Repetições: a Meta pode reenviar o mesmo evento; ele chega com o mesmo X-Synergy-Delivery-Id, e messages[].id também não muda.

Um payload por tipo recebido. Escolha o tipo para ver os campos e o exemplo.

Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Teste Synergy"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.TEST.6f1c2a0e-3b7d-4c1a-9f52-0a8d5e7b9c11",
                "timestamp": "1767225600",
                "type": "text",
                "text": {
                  "body": "Evento de teste enviado pela Synergy"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Texto#

text

Texto.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"text"obrigatório
  • textobjectobrigatório
    • bodystringobrigatório
      O texto.
Texto
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz01AA==",
                "timestamp": "1767225600",
                "type": "text",
                "text": {
                  "body": "Vocês têm esse tênis em azul?"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
Texto em resposta a uma mensagem da empresa
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz02AA==",
                "timestamp": "1767225600",
                "type": "text",
                "text": {
                  "body": "Pode ser amanhã à tarde."
                },
                "context": {
                  "from": "554430000000",
                  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjRDNkU5QTlGNzA1RkE0QzZBAA=="
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
Primeira mensagem vinda de um anúncio (referral)
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz03AA==",
                "timestamp": "1767225600",
                "type": "text",
                "text": {
                  "body": "Olá! Quero saber mais sobre a promoção."
                },
                "referral": {
                  "source_url": "https://fb.me/3cr4Wqqkv",
                  "source_id": "120226305854810726",
                  "source_type": "ad",
                  "body": "Tênis com 25% de desconto",
                  "headline": "Fale com a gente",
                  "media_type": "image",
                  "image_url": "https://scontent.xx.fbcdn.net/v/t45.1/anuncio.jpg",
                  "ctwa_clid": "Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4_0NiNhEgpGo0AHemvuSoifXaytfTzcchptiErTKCqTrJ5nW1h7IHYeYymGb5K5J5iTROpBhWAGaIAeUzHL50",
                  "welcome_message": {
                    "text": "Olá! Como podemos ajudar?"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Imagem#

image

Imagem.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"image"obrigatório
  • imageobjectobrigatório
    • idstringobrigatório
      O id da mídia: baixe com GET /{version}/{media_id}?phone_number_id=… (a url devolvida é desta API).
    • mime_typestringobrigatório
      O tipo MIME.
    • sha256stringobrigatório
      O hash SHA-256 do arquivo.
    • captionstringopcional
      A legenda, se houver.
Imagem
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz04AA==",
                "timestamp": "1767225600",
                "type": "image",
                "image": {
                  "id": "1003383421387256",
                  "mime_type": "image/jpeg",
                  "sha256": "SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=",
                  "caption": "Este aqui"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Áudio#

audio

Áudio. voice: true = gravado no aplicativo (mensagem de voz).

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"audio"obrigatório
  • audioobjectobrigatório
    • idstringobrigatório
      O id da mídia: baixe com GET /{version}/{media_id}?phone_number_id=… (a url devolvida é desta API).
    • mime_typestringobrigatório
      O tipo MIME.
    • sha256stringobrigatório
      O hash SHA-256 do arquivo.
    • voicebooleanopcional
      Gravado como mensagem de voz.
Mensagem de voz
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz05AA==",
                "timestamp": "1767225600",
                "type": "audio",
                "audio": {
                  "id": "1003383421387257",
                  "mime_type": "audio/ogg; codecs=opus",
                  "sha256": "SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=",
                  "voice": true
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Vídeo#

video

Vídeo.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"video"obrigatório
  • videoobjectobrigatório
    • idstringobrigatório
      O id da mídia: baixe com GET /{version}/{media_id}?phone_number_id=… (a url devolvida é desta API).
    • mime_typestringobrigatório
      O tipo MIME.
    • sha256stringobrigatório
      O hash SHA-256 do arquivo.
    • captionstringopcional
      A legenda, se houver.
Vídeo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz06AA==",
                "timestamp": "1767225600",
                "type": "video",
                "video": {
                  "id": "1003383421387258",
                  "mime_type": "video/mp4",
                  "sha256": "SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI="
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Documento#

document

Documento.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"document"obrigatório
  • documentobjectobrigatório
    • idstringobrigatório
      O id da mídia: baixe com GET /{version}/{media_id}?phone_number_id=… (a url devolvida é desta API).
    • mime_typestringobrigatório
      O tipo MIME.
    • sha256stringobrigatório
      O hash SHA-256 do arquivo.
    • filenamestringopcional
      O nome do arquivo.
    • captionstringopcional
      A legenda, se houver.
Documento
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz07AA==",
                "timestamp": "1767225600",
                "type": "document",
                "document": {
                  "id": "1003383421387259",
                  "mime_type": "application/pdf",
                  "sha256": "SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=",
                  "filename": "comprovante.pdf"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Figurinha#

sticker

Figurinha.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"sticker"obrigatório
  • stickerobjectobrigatório
    • idstringobrigatório
      O id da mídia: baixe com GET /{version}/{media_id}?phone_number_id=… (a url devolvida é desta API).
    • mime_typestringobrigatório
      O tipo MIME.
    • sha256stringobrigatório
      O hash SHA-256 do arquivo.
    • animatedbooleanopcional
      Figurinha animada.
Figurinha
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz08AA==",
                "timestamp": "1767225600",
                "type": "sticker",
                "sticker": {
                  "id": "1003383421387260",
                  "mime_type": "image/webp",
                  "sha256": "SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=",
                  "animated": false
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Localização#

location

Localização enviada pelo cliente.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"location"obrigatório
  • locationobjectobrigatório
    • latitudenumberobrigatório
      Latitude.
    • longitudenumberobrigatório
      Longitude.
    • namestringopcional
      O nome do lugar, quando é um lugar.
    • addressstringopcional
      O endereço, quando é um lugar.
    • urlstringopcional
      O site do lugar, quando é um estabelecimento.
Localização
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz09AA==",
                "timestamp": "1767225600",
                "type": "location",
                "location": {
                  "latitude": -23.561414,
                  "longitude": -46.655881,
                  "name": "Loja Paulista",
                  "address": "Av. Paulista, 1000 - São Paulo, SP"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Contatos#

contacts

Cartões de contato.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"contacts"obrigatório
  • contactsobject[]obrigatório
    • nameobjectopcional
      • formatted_namestringopcional
        O nome completo.
      • first_namestringopcional
        Nome.
      • last_namestringopcional
        Sobrenome.
    • phonesobject[]opcional
      • phonestringopcional
        O telefone.
      • wa_idstringopcional
        O WhatsApp do contato, quando ele tem.
      • typestringopcional
        Tipo (CELL, HOME, WORK…).
    • emailsobject[]opcional
      • emailstringopcional
        E-mail.
      • typestringopcional
        Tipo.
    • urlsobject[]opcional
      • urlstringopcional
        Site.
      • typestringopcional
        Tipo.
    • addressesobject[]opcional
      • streetstringopcional
        Rua.
      • citystringopcional
        Cidade.
      • statestringopcional
        Estado.
      • zipstringopcional
        CEP.
      • countrystringopcional
        País.
    • orgobjectopcional
      • companystringopcional
        Empresa.
      • departmentstringopcional
        Departamento.
      • titlestringopcional
        Cargo.
    • birthdaystringopcional
      Aniversário, AAAA-MM-DD.
Cartão de contato
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz10AA==",
                "timestamp": "1767225600",
                "type": "contacts",
                "contacts": [
                  {
                    "name": {
                      "formatted_name": "João Lima",
                      "first_name": "João",
                      "last_name": "Lima"
                    },
                    "phones": [
                      {
                        "phone": "+55 11 97777-6666",
                        "wa_id": "5511977776666",
                        "type": "CELL"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Reação#

reaction

Reação a uma mensagem. Sem emoji quando o cliente remove a reação.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"reaction"obrigatório
  • reactionobjectobrigatório
    • message_idstringobrigatório
      O wamid da mensagem que recebeu a reação.
    • emojistringopcional
      O emoji.
Reação
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz11AA==",
                "timestamp": "1767225600",
                "type": "reaction",
                "reaction": {
                  "message_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjRDNkU5QTlGNzA1RkE0QzZBAA==",
                  "emoji": "❤️"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Botão de modelo#

button

Toque num botão de resposta rápida de um MODELO (template). context.id é a mensagem do modelo.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"button"obrigatório
  • buttonobjectobrigatório
    • payloadstringobrigatório
      O payload que o envio do modelo deu ao botão (ou o texto do botão, quando não deu).
    • textstringobrigatório
      O texto do botão.
Toque num botão de resposta rápida de um modelo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz12AA==",
                "timestamp": "1767225600",
                "type": "button",
                "context": {
                  "from": "554430000000",
                  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjRDNkU5QTlGNzA1RkE0QzZBAA=="
                },
                "button": {
                  "payload": "CONFIRM_42",
                  "text": "Confirmar"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Resposta interativa#

interactive

Resposta a uma mensagem interativa: botão, linha de lista ou flow.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"interactive"obrigatório
  • interactiveobjectobrigatório
    Toque num botão de interactive.type: button.
    • type"button_reply"opcional
    • button_replyobjectopcional
      • idstringobrigatório
        O id do botão tocado.
      • titlestringobrigatório
        O texto do botão.
    • list_replyobjectopcional
      • idstringobrigatório
        O id da linha escolhida.
      • titlestringobrigatório
        O título da linha.
      • descriptionstringopcional
        A descrição da linha, se tinha.
    • nfm_replyobjectopcional
      • namestringopcional
        Sempre flow.
      • bodystringopcional
        O texto que aparece na conversa (por exemplo Sent).
      • response_jsonstringobrigatório
        As respostas do formulário, como TEXTO de JSON (interprete com JSON.parse): traz o flow_token do envio e um campo por resposta.
Toque num botão de resposta (interactive button_reply)
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz13AA==",
                "timestamp": "1767225600",
                "type": "interactive",
                "context": {
                  "from": "554430000000",
                  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjRDNkU5QTlGNzA1RkE0QzZBAA=="
                },
                "interactive": {
                  "type": "button_reply",
                  "button_reply": {
                    "id": "confirm",
                    "title": "Confirmar"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
Escolha numa lista (interactive list_reply)
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz14AA==",
                "timestamp": "1767225600",
                "type": "interactive",
                "context": {
                  "from": "554430000000",
                  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjRDNkU5QTlGNzA1RkE0QzZBAA=="
                },
                "interactive": {
                  "type": "list_reply",
                  "list_reply": {
                    "id": "express",
                    "title": "Expressa",
                    "description": "1 a 2 dias"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
Resposta de um flow (interactive nfm_reply)
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz15AA==",
                "timestamp": "1767225600",
                "type": "interactive",
                "context": {
                  "from": "554430000000",
                  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjRDNkU5QTlGNzA1RkE0QzZBAA=="
                },
                "interactive": {
                  "type": "nfm_reply",
                  "nfm_reply": {
                    "name": "flow",
                    "body": "Sent",
                    "response_json": "{\"flow_token\":\"cadastro-pedido-42\",\"name\":\"Maria Souza\",\"email\":\"maria@example.com\"}"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Pedido do catálogo#

order

Pedido feito pelo carrinho do catálogo.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"order"obrigatório
  • orderobjectobrigatório
    • catalog_idstringobrigatório
      O catálogo.
    • textstringopcional
      O texto que o cliente mandou com o pedido.
    • product_itemsobject[]obrigatório
      • product_retailer_idstringobrigatório
        O produto.
      • quantityintegerobrigatório
        Quantidade.
      • item_pricenumberopcional
        O preço unitário.
      • currencystringopcional
        A moeda.
Pedido pelo carrinho do catálogo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz16AA==",
                "timestamp": "1767225600",
                "type": "order",
                "order": {
                  "catalog_id": "367025965434465",
                  "text": "",
                  "product_items": [
                    {
                      "product_retailer_id": "tenis-azul-42",
                      "quantity": 1,
                      "item_price": 299.9,
                      "currency": "BRL"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Aviso do sistema#

system

Aviso do sistema: o cliente trocou de número. Vem sem contacts.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • type"system"obrigatório
  • systemobjectobrigatório
    • bodystringobrigatório
      O aviso, em inglês.
    • typestringobrigatório
      user_changed_number.
    • wa_idstringopcional
      O novo wa_id do cliente.
Aviso do sistema: o cliente trocou de número
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz17AA==",
                "timestamp": "1767225600",
                "type": "system",
                "system": {
                  "body": "User Maria Souza changed from 5511999999999 to 5511966665555",
                  "wa_id": "5511966665555",
                  "type": "user_changed_number"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Não suportada#

unsupported

Uma mensagem que a Cloud API não entrega (por exemplo uma enquete, ou um tipo novo): só errors diz o que houve.

  • fromstringobrigatório
    O telefone do cliente, só dígitos. Pode não ser igual ao wa_id de contacts.
  • idstringobrigatório
    O wamid da mensagem: use em context.message_id para responder, e para descartar repetições.
  • timestampstringobrigatório
    Segundos desde 1970, como texto.
  • contextobjectopcional
    Quando a mensagem responde a outra, foi encaminhada, ou veio do botão de um produto.
    • fromstringopcional
      O número da empresa da mensagem citada.
    • idstringopcional
      O wamid da mensagem que o cliente respondeu, ou da mensagem cujo botão ele tocou.
    • forwardedbooleanopcional
      A mensagem foi encaminhada.
    • frequently_forwardedbooleanopcional
      A mensagem foi encaminhada muitas vezes.
    • referred_productobjectopcional
      Quando o cliente escreveu pelo botão "Mensagem" de um produto.
      • catalog_idstringopcional
        O catálogo.
      • product_retailer_idstringopcional
        O produto.
  • referralobjectopcional
    Só na primeira mensagem de quem chegou por um anúncio de clique para o WhatsApp (ou uma publicação).
    • source_urlstringobrigatório
      A URL do anúncio ou da publicação.
    • source_idstringobrigatório
      O id do anúncio.
    • source_typestringobrigatório
      ad ou post.
    • bodystringopcional
      O texto principal do anúncio.
    • headlinestringopcional
      O título do anúncio.
    • media_typestringopcional
      image ou video.
    • image_urlstringopcional
      Só com media_type: image.
    • video_urlstringopcional
      Só com media_type: video.
    • thumbnail_urlstringopcional
      Só com media_type: video.
    • ctwa_clidstringopcional
      O id do clique no anúncio (Click to WhatsApp): o dado que fecha a atribuição da conversão.
    • welcome_messageobjectopcional
      • textstringopcional
        A saudação do anúncio.
  • errorsobject[]opcional
    Só em unsupported: por que a Meta não entregou o conteúdo.
    • codeintegerobrigatório
      O código da Meta (por exemplo 131047 fora da janela de 24 h, 131026 destinatário sem WhatsApp, 131051 tipo de mensagem não suportado).
    • titlestringopcional
      O título do erro.
    • messagestringopcional
      A mensagem do erro.
    • error_dataobjectopcional
      • detailsstringopcional
        O detalhe.
    • hrefstringopcional
      A página da Meta sobre o código.
  • typestringobrigatório
    Valores: unsupported, unknown.
Mensagem não suportada (com errors)
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Maria Souza"
                },
                "wa_id": "5511999999999"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjBDNUE2RjQ3RjE4QjdBMz18AA==",
                "timestamp": "1767225600",
                "type": "unsupported",
                "errors": [
                  {
                    "code": 131051,
                    "title": "Message type unknown",
                    "message": "Message type unknown",
                    "error_data": {
                      "details": "Message type is currently not supported."
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

statuses#

Status de uma mensagem enviada · origem: Meta

Dispara quando a Meta informa o status de uma mensagem enviada pelo número (enviada, entregue, lida, falhou) — pela API, pelo Inbox ou por uma campanha. A Meta entrega isso dentro do campo messages, e é com esse nome que sai: changes[].field é messages e o value traz statuses, como a Meta mandou. O filtro statuses do webhook escolhe quais status chegam; null = todos.

Assine com "statuses" em fields. No envelope, changes[].field é messages.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Um webhook que assina messages e statuses recebe os dois no mesmo value quando a Meta os manda juntos.

Quando só statuses sobra, contacts e messages saem do value; o resto (messaging_product, metadata) fica.

A ordem não é garantida: um read pode chegar antes do delivered da mesma mensagem. Guarde o status mais avançado.

Um envio aceito (200) ainda pode falhar depois: é o status failed, com errors, que diz por quê.

  • Um webhook que assina messages e statuses recebe os dois no mesmo value quando a Meta os manda juntos.
  • Quando só statuses sobra, contacts e messages saem do value; o resto (messaging_product, metadata) fica.
  • A ordem não é garantida: um read pode chegar antes do delivered da mesma mensagem. Guarde o status mais avançado.
  • Um envio aceito (200) ainda pode falhar depois: é o status failed, com errors, que diz por quê.
Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjRDNkU5QTlGNzA1RkE0QzZBAA==",
                "status": "delivered",
                "timestamp": "1767225600",
                "recipient_id": "5511999999999"
              }
            ]
          }
        }
      ]
    }
  ]
}

smb_message_echoes#

Mensagem enviada pela empresa fora da API · origem: Meta ou Synergy

Dispara em dois casos. (1) A Meta entrega smb_message_echoes: a empresa respondeu pelo aplicativo WhatsApp Business (coexistência); o value é o da Meta. (2) Um atendente enviou uma mensagem pelo Inbox em uma conversa individual e a Meta aceitou: a Synergy monta o eco no mesmo formato, a partir do corpo que foi para a Meta. Um envio pela API pública NÃO gera eco: foi a própria integração que enviou.

Assine com "smb_message_echoes" em fields. No envelope, changes[].field é smb_message_echoes.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): Eco montado pela Synergy: echo-<wamid, escapado>_c<8 primeiros caracteres do id do webhook> (o . do wamid vira _d). Eco vindo da Meta: o mesmo formato dos outros eventos do número (ev-…).

Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "smb_message_echoes",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "message_echoes": [
              {
                "from": "554430000000",
                "to": "5511999999999",
                "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjdGQjI0QzE4RTlBMDVENzQxAA==",
                "timestamp": "1767225600",
                "type": "text",
                "text": {
                  "body": "oi, tudo bem?",
                  "preview_url": true
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

smb_app_state_sync#

Contatos do aplicativo WhatsApp Business (coexistência) · origem: Meta

Dispara quando a Meta entrega o campo smb_app_state_sync no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "smb_app_state_sync" em fields. No envelope, changes[].field é smb_app_state_sync.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>). Em evento da conta (WABA): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>.

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

history#

Histórico de conversas do aplicativo WhatsApp Business (coexistência) · origem: Meta

Dispara quando a Meta entrega o campo history no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "history" em fields. No envelope, changes[].field é history.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>). Em evento da conta (WABA): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>.

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

calls#

Eventos de chamada · origem: Meta

Dispara quando a Meta entrega o campo calls no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "calls" em fields. No envelope, changes[].field é calls.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>). Em evento da conta (WABA): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>.

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

message_template_status_update#

Status de um modelo de mensagem mudou · origem: Meta

Dispara quando a Meta entrega o campo message_template_status_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "message_template_status_update" em fields. No envelope, changes[].field é message_template_status_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>

Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": {
            "event": "REJECTED",
            "message_template_id": 9,
            "reason": "INVALID_FORMAT",
            "rejection_info": {
              "reason": "Parâmetros colados um no outro.",
              "recommendation": "Separe com texto."
            }
          }
        }
      ]
    }
  ]
}

message_template_quality_update#

Qualidade de um modelo de mensagem mudou · origem: Meta

Dispara quando a Meta entrega o campo message_template_quality_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "message_template_quality_update" em fields. No envelope, changes[].field é message_template_quality_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>

Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "message_template_quality_update",
          "value": {
            "new_quality_score": "YELLOW",
            "message_template_id": 2
          }
        }
      ]
    }
  ]
}

template_category_update#

Categoria de um modelo de mensagem mudou · origem: Meta

Dispara quando a Meta entrega o campo template_category_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "template_category_update" em fields. No envelope, changes[].field é template_category_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

phone_number_quality_update#

Qualidade de um número mudou · origem: Meta

Dispara quando a Meta entrega o campo phone_number_quality_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "phone_number_quality_update" em fields. No envelope, changes[].field é phone_number_quality_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>

Evento de UM número: só chega aos webhooks cujo instanceIds cobre o número de display_phone_number (ou é null).

  • Evento de UM número: só chega aos webhooks cujo instanceIds cobre o número de display_phone_number (ou é null).
Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "554430000000",
            "event": "FLAGGED"
          }
        }
      ]
    }
  ]
}

phone_number_name_update#

Atualização do nome de um número · origem: Meta

Dispara quando a Meta entrega o campo phone_number_name_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "phone_number_name_update" em fields. No envelope, changes[].field é phone_number_name_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

Evento de UM número: só chega aos webhooks cujo instanceIds cobre o número de display_phone_number (ou é null).

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • Evento de UM número: só chega aos webhooks cujo instanceIds cobre o número de display_phone_number (ou é null).

account_update#

Atualização da conta do WhatsApp Business · origem: Meta

Dispara quando a Meta entrega o campo account_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "account_update" em fields. No envelope, changes[].field é account_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

account_alerts#

Alertas da conta do WhatsApp Business · origem: Meta

Dispara quando a Meta entrega o campo account_alerts no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "account_alerts" em fields. No envelope, changes[].field é account_alerts.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>). Em evento da conta (WABA): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>.

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

business_capability_update#

Atualização das capacidades da conta · origem: Meta

Dispara quando a Meta entrega o campo business_capability_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "business_capability_update" em fields. No envelope, changes[].field é business_capability_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>). Em evento da conta (WABA): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>.

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

group_lifecycle_update#

Ciclo de vida de um grupo · origem: Meta

Dispara quando a Meta entrega o campo group_lifecycle_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "group_lifecycle_update" em fields. No envelope, changes[].field é group_lifecycle_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>). Em evento da conta (WABA): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>.

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

group_participant_update#

Participantes de um grupo · origem: Meta

Dispara quando a Meta entrega o campo group_participant_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "group_participant_update" em fields. No envelope, changes[].field é group_participant_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>). Em evento da conta (WABA): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>.

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

group_settings_update#

Configurações de um grupo · origem: Meta

Dispara quando a Meta entrega o campo group_settings_update no webhook da conta. O value é o da Meta, repassado como chegou: os campos são os da documentação da Cloud API para este field.

Assine com "group_settings_update" em fields. No envelope, changes[].field é group_settings_update.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>). Em evento da conta (WABA): sys-<sequência do evento na organização>_c<8 primeiros caracteres do id do webhook>.

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.

O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Cloud API.
  • O caminho de entrega depende do que a Meta manda: com metadata.phone_number_id no value (ou recebido na URL do próprio número) o evento é do número e tem retentativa; sem ele é da conta (WABA) e tem uma tentativa só.

messaging_postbacks#

Toque em botão, Ice Breaker ou item do menu (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo messaging_postbacks no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "messaging_postbacks" em fields. No envelope, changes[].field é messaging_postbacks.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

message_reactions#

Reação a uma mensagem (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo message_reactions no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "message_reactions" em fields. No envelope, changes[].field é message_reactions.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

messaging_seen#

Mensagem vista pelo contato (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo messaging_seen no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "messaging_seen" em fields. No envelope, changes[].field é messaging_seen.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

messaging_referral#

Conversa aberta por um link ig.me ou por um anúncio (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo messaging_referral no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "messaging_referral" em fields. No envelope, changes[].field é messaging_referral.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

message_edit#

Mensagem editada pelo contato (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo message_edit no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "message_edit" em fields. No envelope, changes[].field é message_edit.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

messaging_optins#

Opt-in de notificação (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo messaging_optins no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "messaging_optins" em fields. No envelope, changes[].field é messaging_optins.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

comments#

Comentário em uma publicação da conta (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo comments no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "comments" em fields. No envelope, changes[].field é comments.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

Os comentários de uma mesma entrega da Meta saem em um único envelope por webhook; acima de 60 envelopes por webhook por minuto, o excedente é descartado e contado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.
  • Os comentários de uma mesma entrega da Meta saem em um único envelope por webhook; acima de 60 envelopes por webhook por minuto, o excedente é descartado e contado.

live_comments#

Comentário em uma Live da conta (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo live_comments no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "live_comments" em fields. No envelope, changes[].field é live_comments.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

mentions#

Menção à conta em um comentário ou legenda (Instagram) · origem: Meta

Dispara quando a Meta entrega o campo mentions no webhook de uma conta do Instagram conectada. O value é o da Meta, repassado como chegou: os campos são os da documentação da Instagram API with Instagram Login para este field.

Assine com "mentions" em fields. No envelope, changes[].field é mentions.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ev-<24 hex>_c<8 primeiros caracteres do id do webhook> — os 24 hex são os 12 primeiros bytes de SHA-256(<field>|<JSON do value que a Meta mandou>).

Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.

Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.

Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

  • Sem exemplo: o payload é definido pela Meta e este repositório não tem um caso real dele para copiar. Consulte a referência de webhooks da Instagram API.
  • Só de contas do Instagram: o envelope sai com object: "instagram" e entry[].id é o id da conta (ig-user-id), como a Meta manda.
  • Encaminhar exige o recurso Instagram no plano na hora em que o evento chega: sem ele o evento é guardado na plataforma e não é enviado.

synergy_conversations#

Uma conversa automatizada mudou de mãos · origem: Synergy

Evento da Synergy, sem equivalente na Meta. Dispara quando uma conversa que pertence a uma automação (aberta por um envio da API) muda de status por ação de uma pessoa na plataforma: um atendente respondeu ou assumiu, resolveu, ou devolveu para a automação. É o aviso para um bot parar de falar quando um humano entra. O handoff pedido pela própria integração (POST /v1/numbers/{phone_number_id}/handoff) não gera este evento.

Assine com "synergy_conversations" em fields. No envelope, changes[].field é synergy_conversations.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): conv--_c<8 primeiros caracteres do id do webhook>

Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "synergy_conversations",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "554430000000",
              "phone_number_id": "106540352242922"
            },
            "conversations": [
              {
                "wa_id": "5511999999999",
                "status": "open",
                "previous_status": "automated",
                "automation": "key:0b9c4d1e-52a7-4f6b-8c3d-1e2f3a4b5c6d",
                "timestamp": "1767225600"
              }
            ]
          }
        }
      ]
    }
  ]
}

synergy_comment_actions#

Resultado de uma ação sobre um comentário (Instagram) · origem: Synergy

Evento da Synergy, sem equivalente na Meta. Dispara quando uma ação sobre um comentário do Instagram chega a um resultado final: a resposta privada (private reply), a resposta pública ou a resposta a uma menção foi enviada, falhou, venceu na fila, foi descartada ou ficou sem confirmação. Vale para as ações de uma Jornada e para as pedidas pela API (recipient.comment_id). Cada comentário recebe no máximo uma ação de cada tipo.

Assine com "synergy_comment_actions" em fields. No envelope, changes[].field é synergy_comment_actions.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ca-<sequência da ação na conta>_c<8 primeiros caracteres do id do webhook>

Só de contas do Instagram: no envelope real object é "instagram" e entry[].id é o id da conta (ig-user-id).

Nunca traz o texto da resposta, token nem link de mídia.

  • Só de contas do Instagram: no envelope real object é "instagram" e entry[].id é o id da conta (ig-user-id).
  • Nunca traz o texto da resposta, token nem link de mídia.
Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "17841400000000001",
      "time": 1767225600,
      "changes": [
        {
          "field": "synergy_comment_actions",
          "value": {
            "messaging_product": "instagram",
            "comment_actions": [
              {
                "comment_id": "17900000000000001",
                "kind": "private_reply",
                "status": "sent",
                "origin": "journey",
                "journey_id": "jrn_abcdefghijklmnop",
                "message_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDAw",
                "reason": null,
                "timestamp": "1767225600"
              }
            ]
          }
        }
      ]
    }
  ]
}

synergy_journeys#

Evento de uma Jornada · origem: Synergy

Evento da Synergy, sem equivalente na Meta. Dispara nos marcos de uma Jornada: uma execução começou (run.started), chegou ao fim do fluxo (run.completed) ou terminou por outro motivo (run.ended, com reason); um dado pedido ao contato foi capturado (data.captured); um link rastreado foi clicado (link.clicked); a Jornada foi pausada pelo disjuntor (journey.paused); ou um bloco "webhook" em modo aviso passou (notify). Vale para Jornadas no WhatsApp e no Instagram.

Assine com "synergy_journeys" em fields. No envelope, changes[].field é synergy_journeys.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): j_c<id da execução>_c_c<8 primeiros caracteres do id do webhook> — o mesmo em toda retentativa.

Numa conta do Instagram, no envelope real object é "instagram" e entry[].id é o id da conta (ig-user-id).

Nunca traz token, link de mídia nem segredo; a URL do webhook é revalidada em cada envio.

  • Numa conta do Instagram, no envelope real object é "instagram" e entry[].id é o id da conta (ig-user-id).
  • Nunca traz token, link de mídia nem segredo; a URL do webhook é revalidada em cada envio.
Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "synergy_journeys",
          "value": {
            "messaging_product": "whatsapp",
            "journeys": [
              {
                "event": "run.started",
                "journey_id": "jrn_abcdefghijklmnop",
                "run_id": 4821,
                "contact": {
                  "wa_id": "5511999999999"
                },
                "reason": null,
                "data": null,
                "timestamp": "1767225600"
              }
            ]
          }
        }
      ]
    }
  ]
}

synergy_onboarding#

O resultado de um cadastro hospedado de número · origem: Synergy

Evento da Synergy, sem equivalente na Meta. Dispara quando uma sessão de cadastro (POST /v1/onboarding-sessions) termina: onboarding.completed (o número foi conectado), onboarding.failed (uma tentativa falhou; final diz se a sessão acabou) ou onboarding.expired. É o resultado AUTORITATIVO: libere o recurso do seu cliente por ele, ou por GET /v1/onboarding-sessions/{session_id}, comparando o state que você guardou — nunca só pelo redirect do navegador. Assinar exige uma chave com o escopo onboarding (além de management). Chega aos webhooks com instanceIds null ou, em completed, que cobrem o número novo.

Assine com "synergy_onboarding" em fields. No envelope, changes[].field é synergy_onboarding.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): onb-<id da sessão>-<sequência do evento na sessão>_c<8 primeiros caracteres do id do webhook> — o mesmo em toda retentativa.

entry[].id é o waba_id quando há (concluído), senão "0".

X-Synergy-Instance-Id só em onboarding.completed.

Entregue pela fila da organização, com as mesmas esperas das outras retentativas (x-webhook-delivery.retries), por até 24 h.

Nunca traz o code da Meta, token nem o telefone de quem fez o cadastro além de display_phone_number do número conectado.

  • entry[].id é o waba_id quando há (concluído), senão "0".
  • X-Synergy-Instance-Id só em onboarding.completed.
  • Entregue pela fila da organização, com as mesmas esperas das outras retentativas (x-webhook-delivery.retries), por até 24 h.
  • Nunca traz o code da Meta, token nem o telefone de quem fez o cadastro além de display_phone_number do número conectado.
Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1767225600,
      "changes": [
        {
          "field": "synergy_onboarding",
          "value": {
            "event": "onboarding.completed",
            "session_id": "obs_4Fq9Lm2Xr7Tz1Vb8Nc3Kd6Hs",
            "state": "e7f2c0d4-9b1e-4c52-8d0a-3f6a1b2c4d5e",
            "external_ref": "tenant_8841",
            "final": true,
            "error": null,
            "instance": {
              "id": "3f9a1c0b7d2e4a6f8b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
              "phone_number_id": "106540352242922",
              "waba_id": "102290129340398",
              "display_phone_number": "+55 11 91234-5678",
              "mode": "cloud"
            },
            "timestamp": "1767225600"
          }
        }
      ]
    }
  ]
}

synergy_ping#

Evento de verificação da URL · origem: Synergy

Não se assina: é o POST assinado que prova a URL na verificação ping — ao criar o webhook e ao mudar a URL, o modo de verificação ou os headers. A URL precisa responder 2xx em até 5 s, ou o cadastro é recusado com 400. Não é um evento do WhatsApp: ignore o conteúdo e responda 2xx.

X-Synergy-Delivery-Id (só A-Za-z0-9_-, até 200 caracteres; o _ do id vira __, : vira _c e . vira _d): ping-

entry[].id é "0": o ping não pertence a nenhuma conta.

Sem X-Synergy-Instance-Id.

  • entry[].id é "0": o ping não pertence a nenhuma conta.
  • Sem X-Synergy-Instance-Id.
Corpo
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1767225600,
      "changes": [
        {
          "field": "synergy_ping",
          "value": {
            "messaging_product": "whatsapp",
            "ping": true,
            "timestamp": "1767225600"
          }
        }
      ]
    }
  ]
}

Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.