Voltar para Notícias para desenvolvedores

Como usar QR codes e links curtos no WhatsApp

12 de dezembro de 2022PorRashed Talukder

Assinar o blog Notícias para desenvolvedores

Os QR codes são uma maneira fácil de incorporar itens com muitas informações em uma imagem pequena. Com frequência, eles são usados para diversas finalidades, como fornecer mais informações sobre um cartaz, sobre o cardápio de um restaurante, entre outras.

Em essência, QR codes e links curtos (uma versão encurtada e mais legível de um link complexo) são um modo direto e acessível de se conectar com o cliente. O WhatsApp usa QR codes e links curtos para ajudar você a se conectar com o cliente de maneira aprimorada. Juntos, esses recursos permitem que os clientes iniciem uma conversa com você sem precisar digitar um número de telefone, além de possibilitar o acesso rápido a informações sobre o produto, promoções e muito mais.

Este artigo mostrará como gerar e usar QR codes e links curtos da Plataforma do WhatsApp Business por meio da API de Nuvem hospedada pela Meta. Veremos como criar, atualizar, obter e excluir um QR code e link curto novos, além de descobrir como enviá-los em uma mensagem do WhatsApp. Você pode consultar o código completo aqui a qualquer momento.

Pré-requisitos

Para concluir este tutorial, você precisará do seguinte:

Um app do WhatsApp na sua conta de desenvolvedor da Meta conforme o guia de introdução, além da capacidade de enviar uma mensagem de teste (não é preciso fazer a configuração do webhook)
Um token de acesso do usuário do sistema com as permissões necessárias (whatsapp_business_management, whatsapp_business_messaging e business_management)
Conhecimento básico de Node.js e Express.js

Além disso, este tutorial usará diversas bibliotecas do Node.js, incluindo dotenv para armazenar a configuração necessária para fazer solicitações HTTP a API de Nuvem. Você também usará o Postman para testar os pontos de extremidade desse app. Por fim, você precisará deste código-padrão como a base do artigo.

Configurar o ambiente

Crie e abra um arquivo .env na raiz do projeto e preencha todas as variáveis que estão faltando com os valores das etapas 1 e 2 dos pré-requisitos.

# Your WhatsApp Business app Id
APP_ID=

# Your WhatsApp Business app secret
APP_SECRET=

# Recipient phone number without "+" symbol
RECIPIENT_PHONE_NUMBER=

# Your WhatsApp phone number Id
PHONE_NUMBER_ID=

# Business Account Id
BUSINESS_ACCOUNT_ID=

# System User Access Token. Not temporary access token
ACCESS_TOKEN=

# Cloud API version number
VERSION=v15.0

# Override the default app listener port.
LISTENER_PORT=3000

Agora que você adicionou as variáveis do ambiente, inicie o app usando o script de atalho npm init. Ele criará um esqueleto de aplicativo.

Como criar um QR code e um link curto

Use a API de Gerenciamento do WhatsApp Business, parte da Plataforma do WhatsApp Business, para criar um QR code e um link curto.

Conforme a documentação, o primeiro passo é enviar uma solicitação POST ao ponto de extremidade /{phone-number-ID}/message_qrdls com três parâmetros de consulta: prefilled_message, generate_qr_image e o seu access_token.

O QR code escaneado e o link curto devem armazenar prefilled_message. Isso permitirá que o usuário envie a você uma mensagem predefinida, o que pode ser útil para atendimento ao cliente, comércio eletrônico, obter adesão ao recebimento de mensagens de marketing, entre outros.

Já generate_qr_image permite ter compatibilidade com dois formatos de imagem do QR code gerado: .svg ou .png. É possível selecionar o formato preferido por meio do seguinte método. Este exemplo usa .png.

Usando o texto-padrão, navegue até controllers/qrCode.js e atualize o método createQRCode com o seguinte código:

const qrdlObject =
  {
    "prefilled_message" : message,
    "generate_qr_image" : type
  }

  const config =
  {
    "method" : "post",
    "url" : `https://graph.facebook.com/${process.env.VERSION}/${process.env.BUSINESS_ACCOUNT_ID}/message_qrdls`,
    "headers" : {
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
      'Content-Type': 'application/json'
    },
    "data" : qrdlObject,
  };

  try
  {
    await axios( config );
  }
  catch( error )
  {
    console.log( "")
  }

    },
    function (err, resp, body) {
      if (err) {
        console.log("Error!");
      } else {
        res.json(JSON.parse(body));
      }
    }
  );
};

Depois, você precisará passar duas variáveis do corpo da solicitação: uma mensagem (que depois será usada como prefilled_message) e o formato da imagem. Por fim, faça o teste no Postman.

O corpo da solicitação ficará assim:

{
    "message":"Creating the example QR Code and Short Link",
    "type":"png"
}

Ao clicar no botão Enviar no canto superior direito, a API retornará a resposta exibida na captura de tela abaixo. A resposta inclui deep_link_url, que funciona como um link curto, e qr_image_url, que funciona como uma imagem de QR code. Ela também contém id e prefilled_message.

Como enviar uma mensagem do WhatsApp com um QR code e um link curto

Agora, veremos como enviar a um cliente o QR code e o link curto recém-gerados. Para isso, é preciso usar a API de Nuvem. Você pode seguir os exemplos nessa documentação como ponto de referência. Com a API, será possível enviar um link curto como mensagem de texto e uma URL de imagem como mensagem de mídia.

Mensagens de texto

curl -X  POST \
 'https://graph.facebook.com/v15.0/BUSINESS_ACCOUNT_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "RECIPIENT_PHONE_NUMBER",
  "type": "text",
  "text": { // the text object
    "preview_url": false,
  "body": "MESSAGE_CONTENT"
  }
}'

Mensagens de mídia

curl -X  POST \
 'https://graph.facebook.com/v15.0/BUSINESS_ACCOUNT_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "RECIPIENT_PHONE_NUMBER",
  "type": "image",
  "image": {
  "id" : "MEDIA_OBJECT_ID"
  }
}'

Você criará um método que aceita um objeto de solicitação semelhante e realiza a solicitação HTTP. Por sua vez, a solicitação fará uma chamada ao ponto de extremidade /phone_number_id/messages e enviará uma mensagem. Em controllers/qrCode.js, crie um método sendMessage com o seguinte código. O método Shell já estará no texto-padrão.

exports.sendMessage = async (req, res) => {
  const { to, type } = req.body;
  if (!to || !type) {
    return res.status(400).json({
      error: "Required Fields: to and type",
    });
  }
  request.post(
    {
      url: `https://graph.facebook.com/${process.env.VERSION}/${process.env.BUSINESS_ACCOUNT_ID}/messages`,
      headers: {
        Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
        "content-type": "application/json",
      },
      body: JSON.stringify(req.body),
    },
    function (err, resp, body) {
      if (err) {
        console.log("Error!");
      } else {
        res.json(JSON.parse(body));
      }
    }
  );
};

Depois, você enviará uma mensagem com o QR code recém-gerado. Copie qr_image_url e adicione-a como link de imagem ao corpo da solicitação.

O objeto da solicitação do Postman ficará assim. Aqui, PHONE_NUMBER_TO_SEND pode ser qualquer formato discável.

{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "RECIPIENT_PHONE_NUMBER",
    "type": "image",
    "image": {
        "link": "https://scontent.fybz2-1.fna.fbcdn.net/m1/v/t6/An95lHumHOGcQ_Fl8cDwVrARmc9T9tmtMLyeTOeSFny-OoLLAqSFHEd8gQzAYVsVS6jNm9IBVU27fcb1H05ERwyb5i87Jtp4fjsNppvFnTu26k7ss_dN8S1ZtkSl6XRZtwB68GUabG8?ccb=10-5&oh=00_AT-LCjyu6J8kkeoW1Qj2rxMZikjrHw0fvwA2C6cn9DYkEA&oe=62C8EC07&_nc_sid=f36290"
    }
}

Se você obtiver uma resposta semelhante à imagem abaixo, isso significa que a mensagem foi enviada com sucesso.

A imagem abaixo mostra a visualização da mensagem do ponto de vista do destinatário:

Agora, quando alguém escanear o QR code com um smartphone ou outro dispositivo, ele preencherá a mensagem sem ação do usuário e iniciará uma nova conversa.

Como recuperar a lista de QR codes e links curtos existentes

Obter a lista de QR codes e links curtos existentes é simples: basta fazer uma solicitação GET ao ponto de extremidade /{phone-number-ID}/message_qrdls . Isso retorna uma matriz de objetos que inclui os seguintes objetos individuais: code(id), prefilled_message e deep_link_url.

No arquivo controllers/qrCode.js , atualize o método com o código abaixo:

exports.fetchQRCodes = async (req, res) => {
  request.get(
    {
      url: `https://graph.facebook.com/${process.env.VERSION}/${process.env.BUSINESS_ACCOUNT_ID}/message_qrdls`,
      headers: {
        Authorization: `Bearer ${process.env.ACCESS_TOKEN}`
      }
    },
    function (err, resp, body) {
      if (err) {
        console.log("Error!");
      } else {
        res.json(JSON.parse(body));
      }
    }
  );
};

Depois de adicionar o código, teste a API com o Postman. A imagem abaixo mostra como a solicitação ficará no Postman:

A resposta bem-sucedida gera uma matriz de QR codes e links curtos.

Como atualizar mensagens de QR code

É muito útil atualizar um QR code, já que isso muda a mensagem sem alterar a imagem do código. Assim, não é necessário reimprimir nem recompartilhar novos QR codes. Esse recurso é particularmente útil ao armazenar informações como dados de contato e promoções em QR codes.

Para atualizar a mensagem do QR code, é preciso saber o code(id) do QR code criado. Você pode passá-lo como parâmetro de consulta ao ponto de extremidade /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} .

No arquivo controllers/qrCode.js , atualize o método updateQRCode com o seguinte código:

exports.updateQRCode = async (req, res) => {
  const { message, qr-code-id } = req.body;
  if (!message || !qr-code-id) {
    return res.status(400).json({
      error: "Required Fields: message and id",
    });
  }
  request.post(
    {
      url: `https://graph.facebook.com/v14.0/${process.env.META_PHONE_ID}/message_qrdls/${qr-code-id}?prefilled_message=${message}`,
      headers: {
        Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
        "content-type": "application/json",
      }
    },
    function (err, resp, body) {
      if (err) {
        console.log("Error!");
      } else {
        res.json(JSON.parse(body));
      }
    }
  );
};

Ao testar isso no Postman, você verá este objeto de solicitação:

{
    "message":"This is my first Updated QR code",
    "id":"4WW67TGNCGPXB1"
}

A solicitação bem-sucedida devolve o código atualizado.

Como excluir QR codes

Já que os QR codes não expiram, é possível excluí-los quando as próprias informações estiverem desatualizadas ou deixarem de ser válidas.

Primeiro, será preciso enviar uma solicitação DELETE ao ponto de extremidade /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} .

Navegue até controllers/qrCode.js e atualize o método deleteQRCode do método Shell usando o seguinte código:

exports.deleteQRCode = async (req, res) => {
  const { qr_code_id } = req.query;
  request.delete(
    {
      url: `https://graph.facebook.com/${process.env.VERSION}/${process.env.BUSINESS_ACCOUNT_ID}/message_qrdls/${qr_code_id}`,
      headers: {
        Authorization: `Bearer ${process.env.ACCESS_TOKEN}`
      }


    },
    function (err, resp, body) {
      if (err) {
        console.log("Error!");
      } else {
        res.json(JSON.parse(body));
      }
    }
  );
};

Aqui, você está passando o número de identificação do QR code que você quer descontinuar como parâmetro de consulta. A resposta bem-sucedida fornece um objeto JSON em que success está definido como true.

Vale destacar que, após a exclusão do QR code, não será mais possível usá-lo para iniciar uma conversa e digitar uma mensagem sem ação do usuário.

Conclusão

Neste tutorial prático, vimos como criar, atualizar, obter e excluir QR codes e links curtos com a Plataforma do WhatsApp Business por meio da API de Nuvem hospedada pela Meta. Também vimos diversos casos de uso.

Os QR codes do WhatsApp são fáceis de gerenciar e podem ajudar a aumentar o engajamento com os seus clientes de diversas maneiras significativas. Com os recursos de QR code e link curto do WhatsApp, está mais fácil do que nunca se conectar com a base de usuários.

Tags:

Ferramentas para empresas Ferramentas para desenvolvedores Plataformas 2022 WhatsApp

NOTÍCIAS RELACIONADAS