EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

4

Número máximo de perguntas de quebra-gelo que uma conta pode definir pela API Ice Breaker da Meta.

v11.0

Versão da Graph API a partir da qual os eventos de postback incluem mid; o campo em si exige v8.0 ou posterior.

3

Número máximo de botões em uma mensagem de template de botões, cada um um postback ou botão web_url.

24 hours

Tempo para responder depois que uma pessoa toca em um item do menu persistente, que abre a janela de atendimento padrão.

13

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_self com 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:

A messaging_postbacks notification, as Meta sends it
{
  "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.

Setting two ice breakers
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.
Fazendo isso com o EasyCoexistence

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