Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Webhook messaging_postbacks do Instagram: ice breakers e botões

O campo messaging_postbacks do webhook do Instagram notifica uma aplicação quando alguém toca numa pergunta de ice breaker, num botão postback de um template ou num 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 a aplicação definiu para essa opção; e mid, o ID da mensagem, a partir da Graph API v11.0.

A easyCoexistence subscreve cada conta do Instagram ligada a comentários, mensagens e menções, e encaminha esses eventos, incluindo os toques em respostas rápidas, para o seu endpoint HTTPS assim que chegam, assinados com o segredo dessa conta e sem cópia guardada.

4

Máximo de perguntas de ice breaker que uma conta pode definir através da API Ice Breaker da Meta.

v11.0

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

3

Máximo de botões numa mensagem de template de botões, cada um de tipo postback ou web_url.

24 hours

Tempo para responder depois de uma pessoa tocar num item do menu persistente, que abre a janela de mensagens predefinida.

13

Máximo de respostas rápidas que uma mensagem oferece; uma resposta rápida tocada chega em messages, não em messaging_postbacks.

Quando é disparado o messaging_postbacks?

Quando uma pessoa toca numa das opções estruturadas da conta numa conversa, depois de a aplicação e a conta estarem subscritas ao campo. Os guias da Meta listam estas origens:

  • Uma pergunta de ice breaker, até 4 por conta, oferecida quando uma conversa começa. Não disponível no computador.
  • Um botão postback num template de botões, até 3 por mensagem, ou num template genérico, até 3 por elemento.
  • Um item postback no menu persistente da conta.
  • Um ice breaker tocado numa nova conversa aberta a partir de um link ig.me com um parâmetro ref: o postback traz então também referral.
  • Um teste de auto-mensagem, em que a conta toca no seu próprio botão: o evento acrescenta is_self com o valor true.

Como é uma notificação de postback?

Um evento de mensagem com um objeto postback onde uma DM teria a sua mensagem. O exemplo da Meta para o Instagram Login traz mid, title e payload, e o guia de ice breakers mostra o mesmo objeto sem mid. Uma notificação tem este aspeto:

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 âmbito 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 ice breakers da Meta.
  • postback.title: a pergunta de ice breaker ou o título do botão que a pessoa viu.
  • postback.payload: a string definida para essa opção quando foi criada, escolhida pela aplicação.
  • 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 a partir de um link ig.me com um parâmetro ref.
  • is_self: definido como true, ao lado de postback, quando a conta toca no seu próprio botão num teste de auto-mensagem.

Como se definem os ice breakers?

Com POST /<IG_ID>/messenger_profile em graph.instagram.com: platform definido como instagram e um array ice_breakers cujos call_to_actions contêm até 4 pares de pergunta e payload, com um locale para cada conjunto traduzido. GET /me/messenger_profile?fields=ice_breakers lista-os, e um DELETE com fields definido como ice_breakers remove-os. 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 se enviam os botões postback?

Dentro de uma mensagem que a conta envia com POST /<IG_ID>/messages. Um template de botões tem texto de até 640 caracteres e de 1 a 3 botões; um template genérico tem até 10 elementos, cada um com até 3 botões. Um botão do tipo postback devolve o seu payload em messaging_postbacks quando é tocado, enquanto um botão web_url abre uma página no navegador integrado. O menu persistente, definido em messenger_profile, aceita os mesmos dois tipos.

As respostas rápidas usam messaging_postbacks?

Não: chegam em messages. Uma resposta rápida tocada publica o 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, com até 20 caracteres cada, apenas em texto simples. O guia de Mensagens do Instagram da Meta também inclui as seleções de ice breaker e de template genérico entre o que messages reporta, sem exemplo de payload.

Um toque abre a janela de mensagens?

No caso do menu persistente, a Meta diz que sim: um toque num item do menu abre a janela de mensagens predefinida, 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 echo, com is_echo definido como true.

A easyCoexistence reencaminha os postbacks?

Só os toques em respostas rápidas. Chegam em messages, campo a que a app da easyCoexistence e cada conta ligada estão subscritas, por isso chegam ao seu endpoint com o respetivo quick_reply.payload. Os toques em ice breakers, botões e itens do menu chegam em messaging_postbacks, a que a easyCoexistence não se subscreve, por isso não são reencaminhados.

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.
  • Encaminhar com base em postback.title. O title é o que a pessoa viu e pode mudar consoante o locale; encaminhe com base no payload, que a aplicação define.
  • Esperar mid numa versão antiga da API. A Meta inclui postback.mid apenas a partir da Graph API v11.0.
  • Definir mais de 4 ice breakers, ou testá-los no desktop. A API Ice Breaker da Meta aceita até 4 perguntas, e a funcionalidade não está disponível no desktop.
Fazer isto com a EasyCoexistence

send_social_dm responde à pessoa dentro da janela de 24 horas. A partir de US$ 9 por ligação por mês, descendo até US$ 0.75 à medida que adiciona ligações, com os primeiros 3 dias gratuitos.

Perguntas frequentes

Que campo do webhook comunica os toques em ice breakers 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 ice breakers pode ter uma conta do Instagram?

Até 4 perguntas, definidas com POST /<IG_ID>/messenger_profile e platform definido como instagram, opcionalmente por locale.

Como se responde a um postback do Instagram?

Com POST /<IG_ID>/messages e recipient.id definido como o sender.id do postback, o ID com âmbito do Instagram da pessoa que tocou. Depois de um toque no menu persistente, a Meta dá à conta 24 horas para responder.

Devo encaminhar os postbacks do Instagram por title ou por payload?

Por payload, a string que a aplicação definiu para a opção. O title é o texto que a pessoa viu, que pode mudar consoante o locale.

Continue a ler

Ligue o seu primeiro canal em dois minutos.

Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorizado 24/7

Verificado em