Tutorial de início rápido

Caso ainda não tenha feito isto, siga o nosso guia de configuração do app para configurar o seu app do Facebook e usá-lo com a plataforma do Messenger.

Todas as solicitações às APIs da Plataforma do Messenger são autenticadas ao incluir um token de acesso no nível da página no parâmetro access_token da string de consulta.

Caso não tenha feito isto ao configurar o app do Facebook, gere um token de acesso à Página seguindo estas etapas:

Recomendamos que você mantenha as suas informações confidenciais (como o token de acesso à página) seguras não as codificando no webhook.

Para fazer isso, adicione o seguinte às suas variáveis de ambiente, sendo <PAGE_ACCESS_TOKEN> o token de acesso gerado e <VERIFY_TOKEN> uma string aleatória definida para verificar o webhook:

PAGE_ACCESS_TOKEN="

Agora, tudo o que você precisa fazer é adicionar o token de acesso à página e verificá-lo na parte superior do arquivo app.js para que esse token seja usado na sua lógica de webhook:

const PAGE_ACCESS_TOKEN = process.env.PAGE_ACCESS_TOKEN;
const VERIFY_TOKEN = process.env.VERIFY_TOKEN;

Para começar, faremos stub out de três funções que administrarão os tipos de eventos de webhook recebidos aos quais queremos oferecer suporte, além de responder por meio da API de Envio. Para fazer isso, anexe o seguinte ao seu arquivo app.js:

// Handles messages events
function handleMessage(sender_psid, received_message) {

}

// Handles messaging_postbacks events
function handlePostback(sender_psid, received_postback) {

}

// Sends response messages via the Send API
function callSendAPI(sender_psid, response) {
  
}

Para responder às pessoas no Messenger, primeiro precisamos saber quem elas são. No Messenger, fazemos isso ao obter o ID do remetente no escopo da página (PSID) a partir do evento de webhook recebido.

O que é o PSID?

As pessoas recebem um ID no escopo da página (PSID) exclusivo para cada página do Facebook com a qual iniciam uma conversa. O PSID é usado para identificar uma pessoa ao enviar mensagens.

Se você concluiu uma das opções na seção Projeto inicial, você tem um ponto de extremidade /webhook básico que aceita as solicitações POST e registra o corpo de eventos de webhook recebidos com esta aparência:

app.post('/webhook', (req, res) => {  

  // Parse the request body from the POST
  let body = req.body;

  // Check the webhook event is from a Page subscription
  if (body.object === 'page') {

    // Iterate over each entry - there may be multiple if batched
    body.entry.forEach(function(entry) {

      // Get the webhook event. entry.messaging is an array, but 
      // will only ever contain one event, so we get index 0
      let webhook_event = entry.messaging[0];
      console.log(webhook_event);
      
    });

    // Return a '200 OK' response to all events
    res.status(200).send('EVENT_RECEIVED');

  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }

});

Para obter o PSID do remetente, atualize o bloco body.entry.forEach com o seguinte código para extrair o PSID da propriedade sender.id do evento:

Queremos que nossa experiência seja capaz de administrar dois tipos de evento de webhook: messages e messaging_postback. O nome do tipo de evento não é incluído no corpo do evento, mas podemos determiná-lo verificando certas propriedades do objeto.

O que são os eventos de webhook?

A plataforma do Messenger envia eventos de webhook para notificar você sobre as ações que ocorrem no Messenger. Os eventos são enviados no formato JSON como solicitações POST para o seu webhook. Para saber mais, consulte Webhooks para a plataforma do Messenger.

Para fazer isso, atualize o bloco body.entry.forEach do webhook com uma condicional que verifica se o evento recebido contém uma propriedade message ou postback. Também adicionaremos chamadas às funções handleMessage() e handlePostback() que fizemos stub out antes:

body.entry.forEach(function(entry) {

  // Gets the body of the webhook event
  let webhook_event = entry.messaging[0];
  console.log(webhook_event);


  // Get the sender PSID
  let sender_psid = webhook_event.sender.id;
  console.log('Sender PSID: ' + sender_psid);

  // Check if the event is a message or postback and
  // pass the event to the appropriate handler function
  if (webhook_event.message) {
    handleMessage(sender_psid, webhook_event.message);        
  } else if (webhook_event.postback) {
    handlePostback(sender_psid, webhook_event.postback);
  }
  
});

Agora que as mensagens recebidas estão sendo encaminhadas à função de manipulador apropriada, atualizaremos handleMessage() para administrar e responder a mensagens de texto básicas. Para fazer isso, atualize o código definindo a carga de mensagem da resposta e passe essa carga para callSendAPI(). Queremos responder com uma mensagem de texto básica. Por isso, definiremos um objeto JSON com uma propriedade "text":

function handleMessage(sender_psid, received_message) {

  let response;

  // Check if the message contains text
  if (received_message.text) {    

    // Create the payload for a basic text message
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an image!`
    }
  }  
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Chegou a hora de enviar sua primeira mensagem com a API de Envio da plataforma do Messenger!

Em handleMessage(), faremos uma chamada a callSendAPI(). Agora, precisamos atualizar esse elemento com objetivo de criar o corpo completo da solicitação e enviá-lo para a plataforma do Messenger. A solicitação para a API de Envio tem duas propriedades:

• recipient: define o destinatário da mensagem. Nesse caso, identificamos a pessoa usando o PSID.
• message: define os detalhes da mensagem a ser enviada. Esse campo será definido como o objeto de mensagem que passamos com a função handleMessage().

Ao criar o corpo da solicitação, atualize o stub de callSendAPI() para o seguinte:

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }
}

Agora, tudo o que precisamos fazer é enviar a mensagem por meio da solicitação POST à API de Envio em https://graph.facebook.com/v2.6/me/messages.

O PAGE_ACCESS_TOKEN deve ser anexado ao parâmetro access_token da string de consulta da URL.

const request = require('request');

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }

  // Send the HTTP request to the Messenger Platform
  request({
    "uri": "https://graph.facebook.com/v2.6/me/messages",
    "qs": { "access_token": process.env.PAGE_ACCESS_TOKEN },
    "method": "POST",
    "json": request_body
  }, (err, res, body) => {
    if (!err) {
      console.log('message sent!')
    } else {
      console.error("Unable to send message:" + err);
    }
  }); 
}

Faça o teste!

No Messenger, envie outra mensagem de texto para a sua página do Facebook. Você deverá receber uma resposta automática da sua experiência do Messenger que ecoa sua mensagem e solicita que você envie uma imagem.

Como a resposta solicita que o destinatário envie uma imagem, a próxima etapa é atualizar o código para administrar um anexo. Os anexos enviados são salvos automaticamente pela plataforma do Messenger e disponibilizados por meio de uma URL na propriedade payload.url de cada índice na matriz attachments. Por isso, também extrairemos isso do evento.

Quais tipos de anexo são compatíveis?

Sua experiência no Messenger pode enviar e receber a maioria dos tipos de ativo, incluindo imagem, áudio, vídeo e arquivo. A mídia é exibida e pode ser reproduzida na conversa, permitindo que você crie experiências multimídia.

Para determinar se a mensagem é um anexo, atualize a condicional na função handleMessage() para verificar se há a propriedade attachments na received_message. Depois, extraia a URL dela. Em um bot de verdade, repetiríamos a matriz para verificar diferentes anexos. Entretanto, usaremos apenas o primeiro anexo neste tutorial.

function handleMessage(sender_psid, received_message) {

  let response;

  // Checks if the message contains text
  if (received_message.text) {
    
    // Creates the payload for a basic text message, which
    // will be added to the body of our request to the Send API
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an attachment!`
    }

  } else if (received_message.attachments) {
  
    // Gets the URL of the message attachment
    let attachment_url = received_message.attachments[0].payload.url;
  
  } 
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Depois, responderemos à imagem com uma mensagem de modelo genérica. O modelo genérico é o tipo mais usado de mensagem estruturada, que permite enviar imagem, texto e botões em uma mensagem.

Há outros modelos de mensagem disponíveis?

Sim. A plataforma do Messenger fornece um conjunto de modelos de mensagem úteis, projetados para oferecer suporte a estruturas de mensagem específicas e comuns, incluindo listas, recibos, botões e muito mais. Para saber mais, consulte Modelos de mensagem.

Os modelos de mensagens são definidos na propriedade attachment da mensagem, que contém as propriedades type e payload. Em payload, definimos os detalhes do modelo genérico nas seguintes propriedades:

• template_type: define o tipo de modelo usado na mensagem. Estamos usando o modelo genérico, então o valor é "generic".
• elements: define as propriedades personalizadas do modelo. Para o modelo genérico, especificaremos título, subtítulo, imagem e dois botões de postback.

Para a mensagem estruturada, usaremos a attachment_url que foi enviado como a image_url a ser exibida no modelo, além de incluir alguns botões de postback a fim de permitir que o destinatário responda à mensagem. Para criar a carga da mensagem e enviar o modelo genérico, atualize handleMessage() para o seguinte:

A última etapa é gerenciar o evento de webhook messaging_postbacks que será enviado quando o destinatário tocar em um dos botões de postback no modelo genérico.

O que posso fazer com postbacks?

O botão de postback envia um evento de webhook messaging_postbacks com uma string personalizada de até 1.000 caracteres na propriedade payload. Isso permite que você implemente facilmente diferentes cargas de postback que você pode analisar e responder com comportamentos específicos.

Como o modelo genérico permite que o destinatário escolha entre dois botões, responderemos com base no valor da propriedade payload do evento de postback. Para fazer isso, atualize o seu stub handlePostback() para o seguinte: