استخدام رموز QR والروابط القصيرة في واتساب

تُعد رموز QR طريقة سهلة لتضمين عناصر غنية بالمعلومات في شكل صورة صغيرة. كثيرًا ما نلاحظ استخدامها ضمن مجموعة من الأغراض المختلفة، بدايةً من تزويد مشاهدي الملصقات بمزيد من المعلومات وصولاً إلى توفير قائمة الطعام لدى رواد المطعم.

على المستوى الأساسي، تُعد رموز QR والروابط القصيرة، وهي نسخة مختصرة وأكثر قابلية للقراءة مقارنةً بالرابط المعقد، طريقة مباشرة وسهلة للتواصل مع عميلك. يستخدم واتساب رموز QR والروابط القصيرة لمساعدتك في التواصل مع العملاء بشكل أفضل. تعمل هذه الرموز والروابط معًا على تمكين عملائك من بدء محادثة معك، من دون الحاجة إلى إدخال رقم هاتف، أو الوصول بسرعة إلى معلومات المنتج والعروض الترويجية والمزيد.

ستعرض هذه المقالة كيفية إنشاء كل من رموز QR والروابط القصيرة واستخدامها من منصة واتساب للأعمال باستخدام API السحابة التي تتم استضافتها بواسطة Meta. سنراجع كيفية إنشاء رمز QR والرابط القصير وتحديثه والحصول عليه وحذفه وسنعرض طريقة إرسالهم في رسالة واتساب. يمكنك الاطّلاع على الرمز بالكامل هنا، في أي وقت.

المتطلبات الأساسية

لمتابعة هذا العرض التوضيحي، ستحتاج إلى ما يلي:

1. تطبيق واتساب في حساب مطوّر Meta لديك وفقًا لدليل بدء الاستخدام وإمكانية إرسال رسالة اختبارية (لا يلزم إعداد حدث webhook).

2. رمز وصول مستخدم النظام يحتوي على الأذونات المطلوبة (whatsapp_business_management وwhatsapp_business_messaging وbusiness_management)

3. معرفة بأساسيات Node.js وExpress.js

بالإضافة إلى ذلك، سيستخدم هذا العرض التوضيحي مكتبات Node.js متعددة، بما في ذلك dotenv لتخزين التكوين الضروري لإجراء طلبات HTTP من خلال API السحابة. ستستخدم أيضًا Postman لاختبار نقاط نهاية هذا التطبيق. وأخيرًا، ستحتاج إلى الرمز الأساسي هذا كأساس لهذه المقالة.

إعداد البيئة

يمكنك إنشاء ملف .env وفتحه في جذر المشروع وملء كل المتغيرات المفقودة بالقيم من الخطوتين الأولى والثانية للمتطلبات الأساسية.

# 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

والآن بعض إضافة متغيرات البيئة، ابدأ تشغيل التطبيق باستخدام برنامج الاختصار النصي npm init، والذي سيعمل على إنشاء تطبيق أساسي.

إنشاء رمز QR ورابط قصير جديدين

ستبدأ بإنشاء رمز QR ورابط قصير جديدين باستخدام API إدارة الأعمال، وهي جزء من منصة واتساب للأعمال.

وفقًا إلى الوثائق، ابدأ بإرسال طلب POST إلى نقطة النهاية/{phone-number-ID}/message_qrdls مع تضمين ثلاث معلمات استعلام: prefilled_message وgenerate_qr_image و access_token.

في هذه المرحلة، تريد تخزين رمز QR الذي تم مسحه ضوئيًا والرابط القصير في prefilled_message. وهذا سيسمح للمستخدم بإرسال رسالة مكتوبة مسبقًا لك، الأمر الذي قد يكون مفيدًا بالنسبة لخدمة العملاء والتجارة الإلكترونية والحصول على الاشتراك في الرسائل التسويقية والمزيد.

بعد ذلك، تمكّنك generate_qr_image من دعم تنسيقين لصورة رمز QR التي تم إنشاؤها: .svg أو .png. ويمكنك تحديد التنسيق المفضل باستخدام الأسلوب التالي. يستخدم هذا المثال تنسيق: .png.

باستخدام الرمز الأساسي، انتقل إلى controllers/qrCode.js وقم بتحديث الأسلوب createQRCode باستخدام الرمز التالي:

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

بعد ذلك، يجب إدخال متغيرين من نص الطلب: رسالة (والتي سيتم استخدامها فيما بعد كـ prefilled_message) وتنسيق الصورة. ثم، اختبره باستخدام Postman.

فيما يلي ما يبدو عليه نص الطلب:

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

عند النقر على الزر "إرسال" في أعلى الجانب الأيسر، ستعمل API على إرجاع الاستجابة المعروضة في لقطة الشاشة أدناه. تتضمن الاستجابة deep_link_urlوالذي يعمل كرابط قصير و qr_image_urlوالذي يعمل كصورة رمز QR. كما تحتوي على id و prefilled_message.

إرسال رسالة واتساب تحتوي على رمز QR ورابط قصير

بعد ذلك، ستتمكن من إرسال رمز QR والرابط القصير اللذان تم إنشاؤهما مؤخرًا إلى العميل. لإجراء ذلك، ستحتاج إلى استخدام API السحابة. يمكنك اتباع الأمثلة في تلك الوثائق كنقطة مرجعية. من خلال API، ستتمكن من إرسال رابط قصير كرسالة نصية وعنوان URL الصورة كرسالة وسائط.

الرسائل النصية

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

رسائل الوسائط

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

ستنشئ أسلوبًا يقبل كائن طلب مماثلاً ويعمل على إجراء طلب HTTP، والذي بدوره سيعمل على استدعاء نقطة النهاية /phone_number_id/messages وإرسال رسالة. في controllers/qrCode.js، يمكنك إنشاء أسلوب sendMessage باستخدام الرمز التالي. سيكون أسلوب المخطط بالفعل في الرمز الأساسي.

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

بعد ذلك، سترسل رسالة تتضمن رمز QR الذي تم إنشاؤه مؤخرًا. انسخ qr_image_url وأضفه كرابط صورة إلى نص الطلب.

فيما يلي شكل كائن طلب Postman. هنا، يمكن أن يمثل PHONE_NUMBER_TO_SEND أي تنسيق يمكن الاتصال به.

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

إذا تلقيت استجابة مماثلة للصورة أدناه، فهذا يعني أنه تم إرسال الرسالة بنجاح.

تعرض الصورة أدناه طريقة عرض الرسالة بالنسبة إلى المستلم:

والآن، عندما يمسح شخص ما رمز QR هذا ضوئيًا باستخدام هاتف ذكي أو أي جهاز آخر، فسيعمل على ملء الرسالة مسبقًا من دون أي إدخال من جانب المستخدم وبدء محادثة جديدة.

استرداد قائمة برموز QR والروابط القصيرة الموجودة

يُعد الحصول على قائمة برموز QR والروابط القصيرة الموجودة أمرًا سهلاً، حيث إنك لن تحتاج سوى إرسال طلب GET إلى نقطة النهاية /{phone-number-ID}/message_qrdls . وسترجع مصفوفة كائنات، حيث تتضمن الكائنات الفردية code(id) وprefilled_message و deep_link_url.

في الملف controllers/qrCode.js ، قم بتحديث الأسلوب باستخدام الرمز أدناه:

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

بعد إضافة الرمز، اختبر API من خلال Postman. تعرض الصورة أدناه كيف يبدو الطلب في Postman:

تتضمن الاستجابة الناجحة مصفوفة من رموز QR والروابط القصيرة.

تحديث رسائل رمز QR

يُعد تحديث رمز QR أمرًا مفيدًا بالفعل، حيث يعمل على تحديث الرسالة من دون تغيير صورة رمز QR. ولذلك، لا تحتاج إلى إعادة طباعة رموز QR جديدة أو إعادة مشاركتها. هذه الميزة مفيدة بشكل خاص عند تخزين المعلومات مثل جهة الاتصال والتفاصيل الترويجية في رموز QR.

لتحديث رسالة رمز QR، يجب معرفة code(id) لرمز QR الذي تم إنشاؤه، والذي يمكنك إدخاله كمعلمة استعلام في نقطة النهاية /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} .

في الملف controllers/qrCode.js ، قم بتحديث الأسلوب updateQRCode باستخدام الرمز التالي:

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

عند اختباره في Postman، سيظهر كائن الطلب التالي:

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

يعيد الطلب الناجح إرسال الرمز الذي تم تحديثه.

حذف رموز QR

نظرًا لأن رموز QR لا تنتهي صلاحيتها، فقد يتعين حذفها عندما تكون المعلومات داخل رمز QR هذا قديمة أو لم تعد صالحة.

أولاً، ستحتاج إلى إرسال طلب DELETE إلى نقطة النهاية /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} .

انتقل إلى controllers/qrCode.js وقم بتحديث الأسلوب deleteQRCode من أسلوب المخطط باستخدام الرمز التالي:

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

في هذه المرحلة، ستقوم بإدخال معرف رمز QR الذي تريد إيقاف العمل به في صورة معلمات استعلام. ينتج عن الاستجابة الناجحة كائن JSON مع تعيين success على true.

والجدير بالذكر أنه بمجرد حذف رمز QR، لن يعد بإمكانك استخدامه لبدء محادثة وكتابة رسالة من دون الاستعانة بإدخال المستخدم.

الخلاصة

في هذا العرض التوضيحي العملي، تعرفت على كيفية إنشاء رموز QR والروابط القصيرة وتحديثها وجلبها وحذفها من خلال منصة واتساب للأعمال باستخدام API السحابة التي تتم استضافتها بواسطة Meta، بالإضافة إلى نظرة سريعة على حالات استخدام متعددة.

من السهل إدارة رموز QR في واتساب ويمكنها المساعدة بشكل كبير في زيادة التفاعل مع العملاء من خلال العديد من الطرق الهادفة. مع الإمكانيات التي يوفرها رمز QR والرابط القصير في واتساب، أصبح البقاء على اتصال بقاعدة المستخدمين أسهل من أي وقت مضى.