QR-код — это простой способ разместить объекты с большим количеством информации в небольшом изображении. Эти коды часто используются для самых разных целей, например на плакатах, чтобы предложить людям дополнительную информацию, или в кафе в качестве ссылки на меню.
По сути, QR-коды и короткие ссылки — это сокращенная и более удобная версия сложной ссылки, которая упрощает взаимодействие с клиентом. С этой же QR-коды и короткие ссылки используются в WhatsApp. Они позволяют вашим клиентам начать переписку с вами без необходимости вводить номер телефона либо быстро получить информацию о товаре, акциях и многом другом.
В этой статье описано, как создавать и использовать QR-коды и короткие ссылки на платформе WhatsApp Business с использованием облачного API, размещенного на хостинге Meta. Мы рассмотрим, как создавать, обновлять, получать и удалять QR-коды и короткие ссылки, а также покажем, как отправлять их в сообщениях в WhatsApp. Полный код можно посмотреть по этой ссылке.
Вам понадобятся:
Приложение WhatsApp в аккаунте разработчика Meta (см. руководство по началу работы) и возможность отправлять тестовые сообщения (настройка Webhooks необязательна).
Маркер доступа системного пользователя с обязательными разрешениями (whatsapp_business_management, whatsapp_business_messaging и business_management
).
Базовые навыки работы с 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-кода и короткой ссылки используйте API Business Management, который является частью платформы WhatsApp Business.
Как указано в документации, отправьте запрос 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" }
Когда вы нажимаете кнопку Send (Отправить) в верхнем правом углу, API возвращает ответ, аналогичный показанному на снимке экрана ниже. Ответ содержит следующие параметры: deep_link_url
, который представляет собой короткую ссылку, и qr_image_url
, который представляет собой изображение QR-кода. Кроме того, в ответе содержатся параметры id
и prefilled_message
.
Теперь рассмотрим, как отправить сгенерированный 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-кодов и коротких ссылок, нужно отправить запрос 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-кодом, вам понадобится 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-код, если он содержит неактуальную информацию.
Для этого отправьте запрос 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)); } } ); };
Таким образом вы передаете ID QR-кода, который необходимо удалить, в параметре запроса. В случае успеха вы получите объект JSON, в котором параметр success имеет значение true.
Стоит отметить, что вы не сможете использовать удаленный QR-код, чтобы начать переписку и создать сообщение без участия пользователя.
Из этого практического руководства вы узнали, как создавать, обновлять, получать и удалять QR-коды и короткие ссылки на платформе WhatsApp Business с помощью облачного API, размещенного на хостинге Meta, а также рассмотрели несколько примеров использования.
QR-коды в WhatsApp — это простой и удобный способ улучшить взаимодействие с вашими клиентами. Поддерживать связь с ними ещё никогда не было так просто.