Volver a las novedades para desarrolladores

Usar códigos QR y enlaces directos en WhatsApp

12 de diciembre de 2022DeRashed Talukder

Suscribirte a Noticias para desarrolladores

Los códigos QR son una forma simple de insertar elementos que contienen mucha información en una imagen pequeña. Solemos usarlos con diferentes fines, desde proporcionar más información en un póster hasta ofrecer el menú a los comensales de un restaurante.

Para decirlo de manera más simple, los códigos QR y los enlaces directos (una versión más breve y fácil de leer del enlace complejo) te ofrecen una manera directa y accesible de conectarte con tu cliente. WhatsApp usa los códigos QR y los enlaces directos para que puedas conectarte mejor con tus clientes. En conjunto, permiten a tus clientes iniciar una conversación contigo sin tener que ingresar un número de teléfono o acceder a información sobre productos, promociones, etc.

En este artículo, te mostraremos cómo generar y utilizar códigos QR y enlaces directos desde la Plataforma de WhatsApp Business mediante la API de la nube, alojada por Meta. Veremos cómo crear, actualizar, obtener y borrar un nuevo código QR y enlace directo, y te mostraremos cómo enviarlos en un mensaje de WhatsApp. Puedes ver el código completo aquí en cualquier momento.

Requisitos previos

Para seguir este tutorial, necesitarás lo siguiente:

Una app de WhatsApp en tu cuenta de desarrollador de Meta, tal como se indica en la guía Primeros pasos, y poder enviar un mensaje de prueba (no es necesario configurar el webhook).
Un token de acceso de usuario del sistema con los permisos necesarios (whatsapp_business_management, whatsapp_business_messaging y business_management).
Conocimientos básicos de Node.js y Express.js.

Además, en este tutorial, se usarán varias bibliotecas de Node.js, incluida dotenv, a fin de almacenar la configuración necesaria para realizar solicitudes HTTP con la API de la nube. También usarás Postman para probar los puntos de conexión de esta aplicación. Por último, necesitarás este código repetitivo como base de este artículo.

Configurar el entorno

Crea un archivo .env en el directorio raíz del proyecto, ábrelo y completa todas las variables faltantes con los valores de los pasos 1 y 2 de los requisitos previos.

# 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

Ahora que agregaste las variables del entorno, inicia la app con el script de atajo "npm init", que creará un esqueleto de la app.

Crear un código QR y un enlace directo nuevos

Primero, crearás un código QR y un enlace directo nuevos con la API de administración de WhatsApp Business, que forma parte de la Plataforma de WhatsApp Business.

Tal como lo indica la documentación, primero envía una solicitud POST al punto de conexión /{phone-number-ID}/message_qrdls con tres parámetros de consulta: prefilled_message, generate_qr_image y access_token.

El código QR escaneado y el enlace directo deben almacenarse en prefilled_message. De esta manera, el usuario puede enviarte un mensaje escrito previamente, lo que puede resultar útil para la atención al cliente, para el comercio electrónico, para aumentar la aceptación de mensajes de marketing y para mucho más.

Luego, generate_qr_image te permite admitir dos formatos de imagen del código QR generado: .svg o .png. Puedes usar el siguiente método para seleccionar el formato que prefieras. En este ejemplo, se usa .png.

Con el código repetitivo, navega a controllers/qrCode.js y actualiza el método createQRCode con el siguiente 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));
      }
    }
  );
};

Luego, tendrás que pasar dos variables del cuerpo de la solicitud: un mensaje (que más tarde se usará como prefilled_message) y el formato de la imagen. Usa Postman para hacer una prueba.

El cuerpo de la solicitud debería tener el siguiente aspecto:

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

Cuando presiones el botón "Enviar" de la esquina superior derecha, la API devolverá la respuesta que aparece en la siguiente captura de pantalla. La respuesta incluye deep_link_url, que actúa como enlace directo, y qr_image_url, que actúa como imagen del código QR. También contiene id y prefilled_message.

Enviar un mensaje de WhatsApp con un código QR y un enlace directo

A continuación, podrás enviar a un cliente el código QR y el enlace directo que acabas de generar. Para ello, tendrás que usar la API de la nube. Puedes seguir los ejemplos que aparecen en la documentación como punto de referencia. Con la API, podrás enviar un enlace directo como mensaje de texto y una URL de imagen como mensaje multimedia.

Mensajes 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"
  }
}'

Mensajes multimedia

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"
  }
}'

Crearás un método que acepte un objeto de solicitud similar y realice la solicitud HTTP, que puede llamar al punto de conexión /phone_number_id/messages y enviar un mensaje. En controllers/qrCode.js, crea un método sendMessage con el siguiente código. El método del esquema ya estará en el código repetitivo.

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));
      }
    }
  );
};

Luego, enviarás un mensaje con el código QR recién generado. Copia qr_image_url y agrégala como enlace de imagen al cuerpo de la solicitud.

A continuación, puedes ver el aspecto de un objeto de solicitud Postman. Aquí, PHONE_NUMBER_TO_SEND puede estar en cualquier formato de marcación.

{
    "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"
    }
}

Si recibes una respuesta similar a la de la imagen siguiente, significa que el mensaje se envió de forma correcta.

La siguiente imagen muestra la vista del destinatario del mensaje:

De ahora en más, cuando una persona escanee este código QR con un smartphone o cualquier otro dispositivo, el mensaje se completará previamente sin que el usuario tenga que ingresar información y se iniciará una nueva conversación.

Recuperar la lista de códigos QR y enlaces directos preexistentes

La lista de códigos QR y enlaces directos se puede obtener de manera simple, ya que solo necesitas hacer una solicitud GET al punto de conexión /{phone-number-ID}/message_qrdls . Se devuelve una matriz de objetos, donde los objetos individuales incluyen code(id), prefilled_message y deep_link_url.

En el archivo controllers/qrCode.js , actualiza el método con el siguiente código:

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));
      }
    }
  );
};

Después de agregar el código, prueba la API con Postman. La siguiente imagen muestra cómo se ve la solicitud en Postman.

Si la respuesta es exitosa, se proporciona una matriz de códigos QR y enlaces directos.

Actualizar mensajes de códigos QR

Actualizar un código QR resulta muy útil, ya que se actualiza el mensaje sin cambiar la imagen del código QR. Por eso, no es necesario volver a imprimir o compartir nuevos códigos QR. Esta función es particularmente útil para almacenar información, como detalles de contactos y promocionales, en códigos QR.

Para actualizar el mensaje del código QR, tendrás que conocer el code(id) del código QR creado, que puedes pasar como parámetro de consulta al punto de conexión /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} .

En el archivo controllers/qrCode.js , actualiza el método updateQRCode con el siguiente 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));
      }
    }
  );
};

Cuando pruebes esto en Postman, verás este objeto de solicitud:

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

Si la solicitud se realiza correctamente, envía el código actualizado.

Borrar códigos QR

Como los códigos QR no caducan, te recomendamos borrarlos cuando la información que contienen esté desactualizada o ya no sea válida.

Primero, tendrás que enviar una solicitud DELETE al punto de conexión /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} .

Navega hasta controllers/qrCode.js y actualiza el método deleteQRCode del método de esquema con el siguiente 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));
      }
    }
  );
};

Aquí, pasas el identificador del código QR que quieres retirar como parámetro de consulta. Una respuesta correcta muestra como resultado un objeto JSON con "success" configurado en "true".

Ten en cuenta que una vez que el código QR se borra, ya no puedes usarlo para iniciar una conversación y escribir un mensaje sin la intervención de un usuario.

Conclusión

En este tutorial práctico, aprendiste a crear, actualizar, obtener y borrar códigos QR y enlaces directos con la Plataforma de WhatsApp Business usando la API de la nube, alojada por Meta, y también viste rápidamente varios casos de uso.

Los códigos QR de WhatsApp son fáciles de administrar y pueden ayudarte mucho a aumentar la interacción con tus clientes de varias maneras importantes. Con las funciones de los códigos QR y los enlaces directos de WhatsApp, ahora es más fácil que nunca permanecer conectado con tu base de usuarios.

Etiquetas:

Herramientas empresariales Herramientas para desarrolladores Plataformas 2022 WhatsApp

NOTICIAS RELACIONADAS