Volver a las novedades para desarrolladores

Uso de 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 sencilla de insertar elementos con mucha información en una pequeña imagen. Con frecuencia vemos que se utilizan para diferentes propósitos, desde proporcionar más información a las personas que ven un póster hasta ofrecer a los comensales la carta de un restaurante.

En un nivel básico, los códigos QR y los enlaces directos (una versión acortada y más legible de un enlace complejo) son una forma directa y accesible de conectar con tu cliente. WhatsApp utiliza los códigos QR y los enlaces directos para ayudarte a conectar mejor con tus clientes. Cuando los usas, facilitas que los clientes inicien una conversación contigo sin tener que introducir un número de teléfono o acceder rápidamente a información sobre un producto, promociones y mucho más.

En este artículo se explica cómo generar y utilizar códigos QR y enlaces directos desde la Plataforma de WhatsApp Business mediante la API de nube alojada por Meta. Abordaremos la creación, actualización, obtención y eliminación de un código QR y un enlace directo nuevos y mostraremos cómo enviarlos en un mensaje de WhatsApp. Puedes consultar el código completo aquí cuando quieras.

Requisitos previos

Para seguir este tutorial, necesitarás lo siguiente:

Una aplicación de WhatsApp en tu cuenta de desarrollador de Meta según la guía de introducción. Además, debes poder enviar un mensaje de prueba (no es necesario configurar webhooks).
Un identificador 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 (tales como dotenv) para almacenar la configuración necesaria a fin de realizar solicitudes HTTP con la API de nube. También usarás Postman para probar los extremos de esta aplicación. Por último, necesitarás este código reutilizable como base para este artículo.

Configuración del entorno

Crea y abre un archivo .env en la raíz del proyecto y rellena las variables que falten 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 has añadido las variables de entorno, inicia la aplicación con el script de acceso directo npm init, que creará una aplicación de esqueleto.

Creación de un código QR y un enlace directo nuevos

Para empezar, 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.

Según lo indicado en la documentación, envía primero una solicitud POST al extremo /{phone-number-ID}/message_qrdls con tres parámetros de consulta: prefilled_message, generate_qr_image y tu access_token.

Aquí, quieres que el código QR escaneado y el enlace directo se almacenen en prefilled_message. De esta forma, un usuario podrá enviarte un mensaje escrito previamente, una práctica que puede resultar útil para la atención al cliente, el comercio electrónico, la obtención de una suscripción voluntaria a mensajes de marketing y mucho más.

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

Con el código reutilizable, ve a controllers/qrCode.js y actualiza el método createQRCode con el código siguiente:

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

A continuación, tienes que pasar dos variables del cuerpo de la solicitud: un mensaje (que posteriormente se usará como prefilled_message) y el formato de imagen. Después, haz pruebas con Postman.

A continuación se presenta el aspecto del cuerpo de la solicitud:

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

Al pulsar el botón “Enviar” situado en la esquina superior derecha, la API devolverá la respuesta que se muestra en la captura de pantalla siguiente. En la respuesta se incluye deep_link_url, que actúa como enlace directo, y qr_image_url, que actúa como imagen de un código QR. También se incluyen los valores de id y prefilled_message.

Envío de un mensaje de WhatsApp con un código QR y un enlace directo

Después, podrás enviar el código QR y el enlace directo que se acaban de generar a un cliente. Para ello, tienes que usar la API de nube. Puedes seguir los ejemplos de dicha documentación como punto de referencia. Con la API, podrás enviar un enlace directo como mensaje de texto y la URL de una 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 acepta un objeto de solicitud similar y realiza la solicitud HTTP, que llamará al extremo /phone_number_id/messages y enviará un mensaje. En controllers/qrCode.js, crea un método sendMessage con el código siguiente. El método del shell ya estará en el código reutilizable.

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

A continuación, enviarás un mensaje con el código QR recién generado. Copia el valor de qr_image_url y añádelo como un enlace de imagen al cuerpo de la solicitud.

A continuación se muestra el aspecto del objeto de solicitud de Postman. Aquí, PHONE_NUMBER_TO_SEND puede ser cualquier formato que se pueda marcar.

{
    "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 obtienes una respuesta similar a la imagen siguiente, el mensaje se ha enviado correctamente.

En la imagen siguiente se muestra cómo ve el destinatario el mensaje:

Ahora, cuando alguien escanee este código QR con un smartphone u otro dispositivo, el mensaje se rellenará sin la entrada del usuario y se iniciará una nueva conversación.

Recuperación de la lista de códigos QR y enlaces directos existentes

La obtención de la lista de códigos QR y enlaces directos existentes es una operación sencilla, ya que solo tienes que realizar una solicitud GET al extremo /{phone-number-ID}/message_qrdls. Se devuelve una matriz de objetos, en la que cada uno de ellos incluye code(id), prefilled_message y deep_link_url.

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

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 añadir el código, prueba la API con Postman. En la imagen siguiente se muestra el aspecto de la solicitud en Postman:

Una respuesta correcta proporciona una matriz de códigos QR y enlaces directos.

Actualización de mensajes de códigos QR

La actualización de un código QR es muy útil, ya que se actualiza el mensaje sin cambiar la imagen de dicho código. De esta forma, no tienes que volver a imprimir o compartir códigos QR nuevos. Esta función es especialmente útil al almacenar información como detalles promocionales o de contacto en códigos QR.

Para actualizar el mensaje del código QR, tienes que saber el valor de code(id) del código QR creado, que puedes pasar como un parámetro de consulta al extremo /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id}.

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

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

Al probar este fragmento de código en Postman, verás este objeto de solicitud:

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

Una respuesta correcta devuelve el código actualizado.

Eliminación de códigos QR

Como los códigos QR no caducan, es posible que quieras eliminarlo cuando la información que contenga haya quedado desactualizada o deje de ser válida.

En primer lugar, tendrás que enviar una solicitud DELETE al extremo /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id}.

Ve a controllers/qrCode.js y actualiza el método deleteQRCode desde el método del shell con el código siguiente:

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í vas a pasar el identificador del código QR que quieras retirar como parámetros de consulta. Una respuesta correcta devuelve un objeto JSON con el valor de success establecido en true.

Merece la pena señalar que, una vez eliminado el código QR, no puedes usarlo para iniciar una conversación y escribir un mensaje sin la entrada del usuario.

Conclusión

En este tutorial práctico, has aprendido a crear, actualizar, recuperar y eliminar códigos QR y enlaces directos con la Plataforma de WhatsApp Business mediante la API de nube alojada por Meta. Además, has podido consultar brevemente algunos casos de uso.

Los códigos QR de WhatsApp son fáciles de administrar y pueden ayudar considerablemente a aumentar la interacción con tus clientes de diversas formas significativas. Con las funciones de los códigos QR y los enlaces directos de WhatsApp, mantenerte en contacto con tu base de usuarios es más fácil que nunca.

Etiquetas:

Herramientas para empresas Herramientas para desarrolladores Plataformas 2022 WhatsApp

NOTICIAS RELACIONADAS