Webhook messaging_postbacks do Instagram: quebra-gelo e botões
O campo messaging_postbacks do webhook do Instagram notifica um app quando uma pessoa toca em uma pergunta de quebra-gelo, em um botão postback de um template ou em um item do menu persistente numa conversa com uma conta profissional. O objeto postback do evento traz title, o texto que a pessoa tocou; payload, a string que o app definiu para essa opção; e mid, o ID da mensagem, a partir da Graph API v11.0.
O easyCoexistence inscreve cada conta do Instagram conectada em comments, messages e mentions e encaminha esses eventos, incluindo os toques em respostas rápidas, ao seu endpoint HTTPS assim que chegam, assinados com o segredo daquela conta e sem manter cópia.
Número máximo de perguntas de quebra-gelo que uma conta pode definir pela API Ice Breaker da Meta.
Versão da Graph API a partir da qual os eventos de postback incluem mid; o campo em si exige v8.0 ou posterior.
Número máximo de botões em uma mensagem de template de botões, cada um um postback ou botão web_url.
Tempo para responder depois que uma pessoa toca em um item do menu persistente, que abre a janela de atendimento padrão.
Número máximo de respostas rápidas que uma mensagem oferece; uma resposta rápida tocada chega em messages, não em messaging_postbacks.
Quando messaging_postbacks é disparado?
Quando uma pessoa toca em uma das opções estruturadas da conta em uma conversa, assim que o app e a conta estão inscritos no campo. Os guias da Meta listam estas origens:
- Uma pergunta de quebra-gelo, uma das até 4 que a conta oferece quando uma conversa começa. Não disponível no desktop.
- Um botão postback em um template de botões, até 3 por mensagem, ou em um template genérico, até 3 por elemento.
- Um item postback do menu persistente da conta.
- Um quebra-gelo tocado numa nova conversa aberta por um link ig.me com parâmetro ref: o postback então também traz referral.
- Um teste de automensagem, em que a conta toca no próprio botão: o evento acrescenta
is_selfcom valor true.
Como é uma notificação de postback?
Um evento de mensagem com um objeto postback onde uma mensagem direta (DM) teria a sua mensagem. O exemplo da Meta para o Instagram Login traz mid, title e payload, e o guia de quebra-gelo mostra o mesmo objeto sem mid. Uma notificação tem esta forma:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"postback": {
"mid": "<MESSAGE_ID>",
"title": "<ICE_BREAKER_QUESTION_OR_BUTTON_TITLE>",
"payload": "<PAYLOAD_SET_FOR_THE_OPTION>"
}
}
]
}
]
}O que significa cada campo?
Os campos que a Meta documenta para um postback, de fora para dentro:
- sender.id: o ID com escopo do Instagram da pessoa que tocou, o ID para responder. recipient.id e entry[].id: a conta profissional.
- timestamp: quando a pessoa tocou, segundo o guia de quebra-gelo da Meta.
- postback.title: a pergunta de quebra-gelo ou o título do botão que a pessoa viu.
- postback.payload: a string definida para essa opção na criação, escolhida pelo app.
- postback.mid: o ID da mensagem que o toque enviou à conta, a partir da Graph API v11.0.
- postback.referral: ref, source e type, quando a conversa foi aberta por um link ig.me com parâmetro ref.
is_self: definido como true, ao lado de postback, quando a conta toca no próprio botão em um teste de automensagem.
Como os quebra-gelos são definidos?
Com POST /<IG_ID>/messenger_profile em graph.instagram.com: platform definido como instagram e um array ice_breakers cujos call_to_actions guardam até 4 pares de pergunta e payload, com um locale para cada conjunto traduzido. GET /me/messenger_profile?fields=ice_breakers os lista, e um DELETE com fields definido como ice_breakers os remove. O payload escolhido aqui é o que messaging_postbacks devolve quando a pergunta é tocada.
POST https://graph.instagram.com/<IG_ID>/messenger_profile?access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json
{
"platform": "instagram",
"ice_breakers": [
{
"call_to_actions": [
{ "question": "<QUESTION_1>", "payload": "<PAYLOAD_1>" },
{ "question": "<QUESTION_2>", "payload": "<PAYLOAD_2>" }
]
}
]
}Como os botões postback são enviados?
Dentro de uma mensagem que a conta envia com POST /<IG_ID>/messages. Um template de botões carrega texto de até 640 caracteres e de 1 a 3 botões; um template genérico carrega até 10 elementos, cada um com até 3 botões. Um botão do tipo postback devolve seu payload em messaging_postbacks quando tocado, enquanto um botão web_url abre uma página no navegador interno do app. O menu persistente, definido em messenger_profile, aceita os mesmos dois tipos.
Respostas rápidas usam messaging_postbacks?
Não: elas chegam em messages. Uma resposta rápida tocada publica seu título na conversa como mensagem, e o evento messages traz text com esse título e quick_reply.payload com o payload da opção. Uma mensagem pode oferecer até 13 respostas rápidas de até 20 caracteres cada, somente texto simples. O guia de Mensagens do Instagram da Meta também lista as seleções de quebra-gelo e de template genérico entre o que messages informa, sem um payload de exemplo.
Um toque abre a janela de mensagens?
No caso do menu persistente, a Meta confirma: um toque em um item do menu abre a janela de atendimento padrão, e a conta tem 24 horas para responder. Responda com POST /<IG_ID>/messages e recipient.id definido como o sender.id do postback. A resposta da conta volta em messages como um eco, com is_echo definido como true.
O easyCoexistence encaminha postbacks?
Somente toques em respostas rápidas. Eles chegam em messages, que o app do easyCoexistence e cada conta conectada assinam, então chegam ao seu endpoint com quick_reply.payload. Toques em quebra-gelo, botões e itens de menu chegam em messaging_postbacks, que o easyCoexistence não assina, então não são encaminhados.
Erros comuns
- Esperar respostas rápidas em messaging_postbacks. Uma resposta rápida chega em messages, com quick_reply.payload ao lado do texto da opção tocada.
- Rotear pelo postback.title. O title é o que a pessoa viu e pode variar por locale; roteie pelo payload, que o app define.
- Esperar mid em uma versão antiga da API. A Meta inclui postback.mid apenas a partir da Graph API v11.0.
- Definir mais de 4 quebra-gelos, ou testá-los no desktop. A API Ice Breaker da Meta aceita até 4 perguntas, e o recurso não está disponível no desktop.
send_social_dm responde à pessoa dentro da janela de 24 horas. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Qual campo de webhook informa os toques em quebra-gelo do Instagram?
messaging_postbacks. O objeto postback traz a pergunta como title e o payload definido para ela, além de mid a partir da Graph API v11.0.
Quantos quebra-gelos uma conta do Instagram pode ter?
Até 4 perguntas, definidas com POST /<IG_ID>/messenger_profile e platform definido como instagram, opcionalmente por locale.
Como respondo a um postback do Instagram?
Com POST /<IG_ID>/messages e recipient.id definido como o sender.id do postback, o ID com escopo do Instagram da pessoa que tocou. Após um toque no menu persistente, a Meta dá à conta 24 horas para responder.
Devo rotear postbacks do Instagram por title ou payload?
Por payload, a string que o app definiu para a opção. O title é o texto que a pessoa viu, que pode variar por locale.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em