개발자 소식으로 돌아가기

WhtasApp에서 QR 코드 및 단축 링크 사용하기

2022년 12월 12일제작:Rashed Talukder
개발자 뉴스 구독하기

QR 코드를 이용하면 수많은 정보를 담고 있는 항목을 작은 이미지에 간편하게 포함할 수 있습니다. QR 코드는 포스터를 보는 사람에게 자세한 정보를 전달하거나 음식점에서 손님에게 메뉴를 제공하는 등 다양한 용도로 활용되고 있습니다.

기본적으로 QR 코드와 단축 링크(복잡한 링크를 읽기 쉽게 줄인 형태)는 고객에게 더 손쉽게 다가갈 수 있는 수단입니다. WhatsApp은 QR 코드와 단축 링크를 사용하여 비즈니스가 고객에게 더 손쉽게 다가갈 수 있도록 돕습니다. 고객은 이 둘을 활용하여 전화번호를 입력하지 않고 비즈니스와 대화를 시작하거나 제품 정보, 프로모션 등에 빠르게 액세스할 수 있습니다.

이 문서에서는 Meta가 호스팅하는 클라우드 API를 사용하여 WhatsApp Business 플랫폼에서 QR 코드와 단축 링크를 생성하고 활용하는 방법을 보여줍니다. 새로운 QR 코드와 단축 링크를 만들고, 업데이트하고, 가져오고, 삭제하는 방법을 검토하고 WhatsApp 메시지에서 전송하는 방법도 보여드릴 것입니다. 언제든지 여기에서 전체 코드를 확인할 수 있습니다.

필수 조건

이 튜토리얼을 따라 하려면 다음 조건이 필요합니다.

  1. 시작하기 가이드에 따라 Meta 개발자 계정에서 WhatsApp 앱이 준비된 상태이고 테스트 메시지를 전송할 수 있어야 함(Webhooks 설정 불필요)

  2. 필수적인 권한이 포함된 시스템 사용자 액세스 토큰(whatsapp_business_management, whatsapp_business_messaging, and business_management)

  3. Node.js 및 Express.js에 대한 기본 지식

또한 이 튜토리얼에서는 여러 개의 Node.js 라이브러리(dotenv 포함)를 사용하여 클라우드 API로 HTTP 요청을 보내는 데 필요한 구성을 저장합니다. 그리고 Postman을 사용하여 이 앱의 엔드포인트도 테스트할 것입니다. 마지막으로, 이 문서의 기초가 되는 상용구 코드가 필요합니다.

환경 설정

프로젝트 루트에 .env 파일을 만든 후 열어서 필수 조건 1단계와 2단계에서 얻은 값으로 누락된 모든 변수를 입력합니다.

# 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 코드 및 단축 링크 만들기

먼저 WhatsApp Business 플랫폼에 포함된 Business Management API를 사용하여 새로운 QR 코드 및 단축 링크를 만듭니다.

이 문서에 따라 /{phone-number-ID}/message_qrdls 엔드포인트로 POST 요청을 보내고 세 가지 매개변수인 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 코드와 단축 링크를 포함하여 WhatsApp 메시지 보내기

이제 새로 생성된 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 메서드를 만듭니다. shell 메서드는 이미 상용구 안에 포함됩니다.

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 코드와 단축 링크의 리스트를 가져오는 방법은 간단합니다. /{phone-number-ID}/message_qrdls 엔드포인트로 GET 요청을 보내기만 하면 됩니다. 그러면 개체의 배열이 반환되는데, 각 개체에는 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));
      }
    }
  );
};

코드를 추가한 후 Postman으로 API를 테스트합니다. 아래의 이미지는 Postman에서 요청이 어떻게 나타나는지 보여줍니다.

요청이 성공하면 QR 코드 및 단축 링크의 배열이 응답으로 제공됩니다.

QR 코드 메시지 업데이트하기

QR 코드를 업데이트하면 QR 코드 이미지를 변경하지 않고 메시지가 업데이트되므로 매우 유용합니다. 그러므로 새로운 QR 코드를 다시 인쇄하거나 공유할 필요가 없습니다. 이 기능은 연락처, 프로모션 상세 정보 등을 QR 코드에 저장할 때 특히 유용합니다.

QR 코드 메시지를 업데이트하려면 생성된 QR 코드의 코드(ID)가 있어야 합니다. 이를 쿼리 매개변수로 삼아 /{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 코드 내의 정보가 오래되었거나 더 이상 유효하지 않을 때는 삭제하는 것이 좋습니다.

먼저 /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} 엔드포인트로 DELETE 요청을 보내야 합니다.

  controllers/qrCode.js 로 이동하고 다음 코드를 사용해서 shell 메서드에서 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 코드의 코드 ID를 쿼리 매개변수로 전달해야 합니다. 요청이 성공하면 success가 true로 설정된 JSON 개체가 응답으로 출력됩니다.

QR 코드가 삭제되고 나면 더 이상 이 QR 코드를 사용하여 사용자 입력 없이 대화를 시작하고 메시지를 입력할 수 없습니다.

결론

이 실습 튜토리얼에서는 Meta에서 호스팅하는 클라우드 API를 사용하여 WhatsApp Business 플랫폼에서 QR 코드 및 단축 링크를 만들고, 업데이트하고, 가져오고, 삭제하는 방법을 알아보고 몇 가지 사용 사례를 간략히 살펴보았습니다.

WhatsApp QR 코드는 관리하기 간편하며, 여러 의미 있는 방식으로 고객의 참여를 늘리는 데 큰 도움이 될 수 있습니다. WhatsApp의 QR 코드 및 단축 링크 기능을 사용하면 그 어느 때보다 쉽게 사용자 기반과의 관계를 유지할 수 있습니다.


태그:
비즈니스 도구개발자 도구플랫폼2022년WhatsApp
관련 뉴스

앱에서 WhatsApp 계정 지표를 시각화하는 방법

비즈니스 도구개발자 도구플랫폼2022년WhatsApp
2022년 12월 19일

Send Interactive Messages on the WhatsApp Business Platform

비즈니스 도구개발자 도구플랫폼2022년WhatsApp
2022년 11월 21일

Integrating WhatsApp Into Your E-commerce Flow

비즈니스 도구개발자 도구플랫폼2022년WhatsApp
2022년 11월 14일
소식 더 보기