Thiết lập Webhooks

Đăng ký Webhooks để nhận thông báo về tin nhắn mà doanh nghiệp bạn nhận được và thông tin mới về hồ sơ khách hàng.

Tạo điểm cuối

Trước khi có thể bắt đầu nhận thông báo, bạn sẽ cần tạo một điểm cuối trên máy chủ để nhận thông báo.

Điểm cuối của bạn phải có khả năng xử lý 2 loại yêu cầu HTTPS: Yêu cầu xác minh và Thông báo sự kiện. Vì cả hai yêu cầu này đều sử dụng HTTPS nên máy chủ của bạn phải đặt cấu hình và cài đặt chính xác một chứng chỉ TLS hoặc SSL hợp lệ. Chứng chỉ tự ký không được hỗ trợ.

Tìm hiểu thêm về Yêu cầu xác minh và Thông báo sự kiện

Việc thiết lập Webhooks sẽ không ảnh hưởng đến số điện thoại trên Ứng dụng WhatsApp Business của bạn. Chỉ sau khi chuyển số điện thoại sang Nền tảng WhatsApp Business, bạn mới không dùng được số đó trên Ứng dụng WhatsApp Business nữa.

Đăng ký Webhooks

Để đăng ký Webhooks, bạn sẽ cần lấy ID ứng dụng trên Meta và các quyền truy cập. Để thực hiện việc này, hãy truy cập Bảng điều khiển ứng dụng trên Meta. Tại đây, bạn sẽ:

1. Tạo một ứng dụng thuộc loại dành cho Doanh nghiệp trong Bảng điều khiển ứng dụng trên Meta
2. Thêm sản phẩm Webhooks vào ứng dụng của bạn trên Meta trong Bảng điều khiển ứng dụng

   Hiện tại, mỗi Ứng dụng trên Meta chỉ có thể yêu cầu đặt cấu hình một điểm cuối. Nếu cần gửi bản cập nhật webhook đến nhiều điểm cuối, bạn cần có nhiều Ứng dụng trên Meta.

Nếu là Nhà cung cấp giải pháp kinh doanh (BSP), bạn có thể cần:

1. Thêm quyền whatsapp_business_messaging vào Bảng điều khiển ứng dụng
2. Hoàn tất thành công quy trình Xét duyệt ứng dụng của Meta - Bước này sẽ cần nhiều thời gian, nhưng bạn có thể tiếp tục thử nghiệm trong toàn bộ quy trình xét duyệt.

Tìm hiểu về Webhooks

Mỗi khi một sự kiện kích hoạt diễn ra, Nền tảng WhatsApp Business sẽ xem xét sự kiện đó và gửi thông báo đến URL Webhook mà bạn đã chỉ định trước đây. Bạn có thể nhận được 2 loại thông báo:

• Tin nhắn đã nhận: Thông báo này cho bạn biết thời điểm bạn nhận được tin nhắn. Thông báo này còn được gọi là "thông báo tin nhắn đến" trong toàn bộ tài liệu.

• Thông báo trạng thái tin nhắn và giá cả: Thông báo này cho bạn biết thời điểm trạng thái tin nhắn thay đổi. Ví dụ: đã đọc hoặc đã gửi tin nhắn. Thông báo này còn được gọi là "thông báo tin nhắn đi" trong toàn bộ tài liệu.

Mọi Webhooks đều có định dạng chung sau:

{
  "object": "whatsapp_business_account",
  "entry": [{
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [{
          "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                  "display_phone_number": "PHONE_NUMBER",
                  "phone_number_id": "PHONE_NUMBER_ID"
              },
              # specific Webhooks payload            
          },
          "field": "messages"
        }]
    }]
}

Hãy xem phần Thành phần để biết thông tin về từng trường.

Nếu nhận một tin nhắn không được hỗ trợ cho API Đám mây, bạn sẽ nhận được webhook tin nhắn không xác định.

Kích thước phần tải dữ liệu

Kích thước phần tải dữ liệu của Webhooks có thể lên đến 3MB.

Điểm cuối ứng dụng mẫu

Tạo một điểm cuối ứng dụng mẫu để thử nghiệm webhooks của bạn.

• Điểm cuối ứng dụng mẫu sử dụng Glitch
• Điểm cuối ứng dụng mẫu sử dụng Heroku

Lỗi gửi webhook

Nếu chúng tôi gửi yêu cầu webhook đến điểm cuối của bạn và máy chủ trả về mã trạng thái HTTP không phải là 200 hoặc nếu không thể gửi webhook vì lý do khác, chúng tôi sẽ tiếp tục gửi yêu cầu với tần suất giảm dần trong tối đa 7 ngày cho đến khi yêu cầu thành công.

Lưu ý rằng trong các lần thử lại, chúng tôi sẽ gửi yêu cầu đến tất cả ứng dụng đã đăng ký webhooks (và các trường thích hợp) cho Tài khoản WhatsApp Business. Việc này có thể dẫn đến thông báo webhook trùng lặp.

Địa chỉ IP

Bạn có thể chạy lệnh sau trong cửa sổ dòng lệnh để lấy địa chỉ IP cho máy chủ webhook của chúng tôi:

whois -h whois.radb.net — '-i origin AS32934' | grep ^route | awk '{print $2}' | sort

Chúng tôi thay đổi các địa chỉ IP này theo định kỳ. Vì vậy, nếu bạn đưa máy chủ của chúng tôi vào danh sách cho phép thì đôi khi, bạn nên tạo lại danh sách này và cập nhật danh sách cho phép cho phù hợp.

Các bước tiếp theo

Tìm hiểu thêm về thông tin bạn có thể nhận được trong thông báo Webhooks.

Triển khai Webhook từ Nền tảng WhatsApp Business

Webhook là một cách đơn giản để các dịch vụ gửi dữ liệu bất cứ khi nào có điều gì đó xảy ra. Bạn thiết lập một ứng dụng hoặc máy chủ để nhận tin nhắn và cung cấp cho dịch vụ địa chỉ. Khi một sự kiện kích hoạt trong dịch vụ, nó có thể chỉ cần gọi webhook để gửi tin nhắn đến ứng dụng của bạn.

Nền tảng WhatsApp Business cung cấp nhiều tùy chọn cho các sự kiện khác nhau mà bạn có thể tích hợp vào ứng dụng hoặc dịch vụ của mình miễn là nó hỗ trợ HTTPS và có chứng chỉ SSL hợp lệ. Điều này cung cấp cho bạn khả năng tự động trả lời tin nhắn WhatsApp trong thời gian thực.

Trong bài viết này, chúng tôi sẽ xem xét các cách thiết lập webhook để kết nối với WhatsApp. Chúng ta cũng sẽ đi qua một hướng dẫn trình bày cách thiết lập một ứng dụng nhận tin nhắn và lưu trữ chúng trong cơ sở dữ liệu.

Triển khai Webhooks

Các doanh nghiệp thuộc mọi quy mô đều được hưởng lợi từ việc sử dụng WhatsApp để thiết lập các cuộc trò chuyện 2 chiều với khách hàng của họ. Các trường hợp sử dụng rơi vào ba loại chính: dịch vụ khách hàng, tiếp thị.

Webhook có thể cung cấp thông báo về các loại sự kiện khác nhau. Ví dụ: sự kiện tin nhắn đã nhận đi qua webhook tin nhắn. Bạn có thể sử dụng webhook này để giảm gánh nặng cho các đại lý dịch vụ khách hàng bằng cách lọc ra các truy vấn phổ biến của khách hàng. Các tin nhắn đơn giản được chuyển đến dịch vụ chatbot để xây dựng phản hồi và bất cứ điều gì không thể trả lời ngay lập tức sẽ được chuyển đến các đại lý trực tiếp.

Sự kiện tin nhắn đã nhận cũng có thể chứa phương tiện, nếu người dùng gửi hình ảnh hoặc chi tiết tương tác, nếu người dùng bấm vào nút để trả lời tin nhắn thay vì nhập trả lời.

Bây giờ chúng ta đã khám phá một số trường hợp sử dụng cho webhook WhatsApp, hãy đi sâu vào hướng dẫn. Chúng tôi sẽ xem xét một trường hợp sử dụng đơn giản trong đó khách hàng cung cấp phản hồi đánh giá qua tin nhắn WhatsApp. Chúng tôi sẽ chỉ cho bạn cách lưu trữ những đánh giá này trong cơ sở dữ liệu, nơi chúng có thể được phân tích để hiểu các chủ đề đánh giá phổ biến hoặc cảm nhận chung xung quanh một sản phẩm cụ thể.

Node.js Webhook Listener với AWS Lambda

Hãy tưởng tượng rằng doanh nghiệp của bạn muốn sử dụng Nền tảng WhatsApp Business để liên hệ với khách hàng bằng thông báo yêu cầu họ xem xét sản phẩm họ đã mua gần đây. Doanh nghiệp của bạn muốn cho phép khách hàng trả lời tin nhắn bằng đánh giá của họ và sau đó bạn muốn lưu trữ đánh giá đó trong cơ sở dữ liệu.

Để thực hiện việc này, bạn sẽ tạo một hàm AWS Lambda bằng Node.js và lưu trữ dữ liệu trong DynamoDB. Sử dụng các công nghệ này làm cho toàn bộ ngăn xếp trở nên phi máy chủ, loại bỏ gánh nặng cơ sở hạ tầng trong khi phát triển và cho phép bạn tự động tăng hoặc giảm quy mô để phù hợp với nhu cầu. Điều này cũng giúp làm cho giá cả linh hoạt hơn, vì bạn chỉ trả tiền cho những gì bạn sử dụng.

Định cấu hình ứng dụng của bạn

Đầu tiên, khởi tạo một dự án Node.js mới. Serverless Framework là một lựa chọn tốt, vì nó đơn giản hóa việc thiết lập và triển khai cho các hàm AWS Lambda.

Nhập các lệnh sau để khởi tạo dự án:

npm init

serverless create --template aws-nodejs

npm install -s express serverless-http serverless-offline

Once your project is initialized, you then need to create an endpoint that will allow you to verify your application with the WhatsApp Business Platform. This is a requirement when creating your app on Meta for Developers.

Replace the boilerplate code in handler.js with the following:

const serverless = require('serverless-http')
const express = require('express')
const app = express()

const token = process.env.TOKEN

app.get('/webhooks',  (req, res) => {
 if (
   req.query['hub.mode'] == 'subscribe' &&
   req.query['hub.verify_token'] == token
 ) {
   res.send(req.query['hub.challenge']);
 } else {
   res.sendStatus(400);
 }
})

module.exports.handler = serverless(app);

The endpoint is very simple: It returns the hub.challenge parameter, which the verification system sends as a request parameter.

Next, you need to configure your endpoint in the Serverless YAML file. This YAML file defines the functions, endpoints, and any resources that should be created when the project is deployed to AWS.

This helps make the deployment process simpler and removes the need for any manual configuration. It bundles together any code and additional infrastructure configurations, such as resource creation or permission definitions. Replace the boilerplate code in serverless.yml with the following code:

service: whatsapp-webhooks
frameworkVersion: '2'

provider:
 name: aws
 runtime: nodejs14.x
 lambdaHashingVersion: 20201221
 environment:
   TOKEN: ${env:APP_TOKEN}

plugins:
 - serverless-offline

functions:
 app:
   handler: handler.handler
   events:
     - http: ANY /
     - http: 'ANY {proxy+}'

The plugins section includes Serverless Offline, which emulates AWS Lambda and API Gateway and lets you test your endpoint locally before deploying it to AWS.

The functions section defines the location for your endpoint handler and defines which HTTP events can trigger it. For the sake of simplicity, set this handler to respond to any event.

The provider section contains the TOKEN environment variable. This secret token is required when sending the verification message from Meta for Developers.

To define the token, export an environment variable with the name “APP_TOKEN” in your terminal. For example, use the following command:

export APP_TOKEN=testtoken

When the service is deployed, the TOKEN variable will take the value of your local APP_TOKEN variable and make it available to the Lambda function in AWS.

Test Your App

Now that your project is configured, you should test that the function works locally.

Launch the project in offline mode by running the following command:

serverless offline

Once your app is running, run the following command in another window as the app will have control of the current one. Make sure you replace the token value with the value for the token you defined earlier:

curl -v "http://localhost:3000/dev/webhooks?hub.mode=subscribe&hub.verify_token=testtoken"

The output and 204 status responses should look similar to this:

*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 3000 (#0)
> GET /dev/webhooks?hub.mode=subscribe&hub.verify_token=testtoken HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 204 No Content
< x-powered-by: Express
< content-type: application/json; charset=utf-8
< cache-control: no-cache
< Date: Thu, 21 Apr 2022 16:28:24 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host localhost left intact
* Closing connection 0

Next, deploy your application to AWS by running the following command:

serverless deploy

AWS will then output your endpoint to the terminal once your app has finished deploying.

Configure the Webhook

Next, begin the verification process by creating a Facebook app.

On the left navigation panel on the App Dashboard, select PRODUCTS. Then select Webhooks from the options. In the dropdown menu, select Whatsapp Business Account.

Next, enter the callback URL with the endpoint provided by AWS. The token should be the same token you used in the severless.yml file.

Once your app is verified, you can see all of the different object fields your webhook can subscribe to. Each provides an option to test and subscribe.

The field of interest is the messages field, which sends messages to your endpoint when they are received. Each of the webhooks sends a POST request to the same callback URL you provided when verifying the application.

Tiếp theo, bạn cần viết mã để truy xuất các yêu cầu POST và lưu trữ dữ liệu trong DynamoDB.

Thêm mã sau vào tệp .js trình xử lý:

const AWS = require('aws-sdk')
const dynamoDb = new AWS.DynamoDB.DocumentClient();

app.post('/webhooks',  (req, res) => {

const body = JSON.parse(req.body)

if(body.field !== 'messages'){

// not from the messages webhook so dont process

return res.sendStatus(400)

}

const reviews = body.value.messages.map((message)=>{

const reviewInfo = {

TableName: process.env.REVIEW_TABLE,

Item: {

phonenumber: message.from,

review: message.text.body

}

}

return dynamoDb.put(reviewInfo).promise()

})

// return 200 code once all reviews have been written to dynamoDB

return Promise.all(reviews).then((data) => res.sendStatus(200));

})

Mã này trước tiên sẽ cài đặt gói npm AWS SDK để bạn có thể sử dụng máy khách tài liệu DynamoDB. Chức năng sau đó kiểm tra xem yêu cầu đã được gửi qua webhook tin nhắn hay chưa. Nếu có, hàm sẽ tạo một mục đánh giá bao gồm đánh giá và số điện thoại của khách hàng (được cung cấp bởi webhook). Webhook gửi mỗi thư dưới dạng một mảng trong trường tin nhắn, vì vậy nó có thể gửi nhiều thư cùng một lúc. Hàm lặp qua các tin nhắn, tạo ra một mảng các lời hứa PUT của DynamoDB có thể được thực thi sau này để lưu trữ dữ liệu.

Cấu hình DynamoDB

Ví dụ đơn giản này lấy dữ liệu và lưu trữ nguyên trạng dưới dạng bản ghi DynamoDB. Tại thời điểm này, bạn có thể thêm chức năng để phân tích cú pháp thông báo theo yêu cầu để thực hiện logic nghiệp vụ bổ sung.

Để tính năng này hoạt động, bạn cần cung cấp một số chi tiết cấu hình cho DynamoDB trong cấu hình Serverless của mình. Tệp serverless.yml hoàn chỉnh bây giờ sẽ trông như thế này:

service: whatsapp-webhooks
frameworkVersion: '2'

provider:
 name: aws
 runtime: nodejs14.x
 lambdaHashingVersion: 20201221
 region: eu-west-1
 iamRoleStatements:
   - Effect: "Allow"
     Action:
     - dynamodb:Query
     - dynamodb:Scan
     - dynamodb:GetItem
     - dynamodb:PutItem
     - dynamodb:UpdateItem
     - dynamodb:DeleteItem
     Resource: arn:aws:dynamodb:us-east-1:111111111111:table/${self:provider.environment.REVIEW_TABLE}
 environment:
   TOKEN: ${env:APP_TOKEN}
   REVIEW_TABLE: reviews

plugins:
 - serverless-offline

functions:
 app:
   handler: handler.handler
   events:
     - http: ANY /
     - http: 'ANY {proxy+}'

resources:
 Resources:
   ReviewsTable:
     Type: 'AWS::DynamoDB::Table'
     Properties:
       TableName: ${self:provider.environment.REVIEW_TABLE}
       AttributeDefinitions:
         - AttributeName: phonenumber
           AttributeType: S
       KeySchema:
         - AttributeName: phonenumber
           KeyType: HASH
       ProvisionedThroughput:
         ReadCapacityUnits: 1
         WriteCapacityUnits: 1

Tệp hiện có các câu lệnh quản lý quyền bổ sung trong phần nhà cung cấp cho phép hàm Lambda truy xuất và ghi dữ liệu vào bảng DynamoDB của bạn. Tệp cũng chứa phần tài nguyên cấu hình bảng DynamoDB, khóa của bảng và thông lượng được cung cấp. Trong khi thử nghiệm, phụ cấp cho các đơn vị năng lực được đặt thành giá trị thấp để thử nghiệm. Nhưng điều này có thể được cấu hình trong sản xuất để mở rộng quy mô tùy thuộc vào nhu cầu.

Kiểm tra ứng dụng của bạn

Giờ đây, khi bạn triển khai ứng dụng Serverless, bảng DynamoDB sẽ tự động được tạo và cấu hình, đồng thời hàm Lambda của bạn sẽ có tất cả các quyền cần thiết để có thể ghi dữ liệu vào bảng. Điều này một lần nữa nhấn mạnh sức mạnh của việc sử dụng khung Serverless, vì tất cả các yêu cầu cơ sở hạ tầng của chúng tôi đều được xử lý trong một cấu hình đơn giản.

Sau khi triển khai, hãy quay lại Meta for Developers và chọn nút Thử nghiệm trong hàng trường tin nhắn. Nó mở ra một cửa sổ Field Sample mới trông như thế này:

Điều này hiển thị định dạng của payload được gửi mỗi khi một tin nhắn được gửi đến tài khoản. Chọn Gửi đến máy chủ của tôi, sau đó điều hướng đến DynamoDB trong bảng điều khiển AWS để xem bản ghi mới với bài đánh giá chứa văn bản kiểm tra:

Kết thúc

Đây là một ứng dụng thử nghiệm đơn giản cho thấy sự dễ dàng và đơn giản của việc thiết lập trình nghe webhook bằng Serverless Framework. Bằng cách sử dụng các công nghệ phi máy chủ như AWS Lambda và DynamoDB, ứng dụng này có thể được mở rộng từ một nguyên mẫu đơn giản thành một dịch vụ sẵn sàng sản xuất có khả năng xử lý khối lượng thông lượng lớn.

Bạn có thể sử dụng webhook trên Nền tảng WhatsApp Business để giúp tự động hóa việc quản lý và tương tác tài khoản khách hàng. Tài liệu webhook chính thức của WhatsApp cung cấp thông tin đầy đủ hơn về việc đăng ký webhook cho hệ thống sản xuất. Lưu ý rằng tài liệu webhook bỏ qua trường [messages]. Sử dụng Tham chiếu Webhooks để có danh sách đầy đủ các trường có sẵn để đăng ký.

Khi xây dựng người nghe cho các webhook này, điều quan trọng là phải suy nghĩ về chi phí và khả năng mở rộng. Giải pháp cần có khả năng đối phó với nhu cầu tăng đột biến gây ra bởi một lượng lớn khách hàng liên hệ với bạn qua WhatsApp cùng một lúc. Vào những thời điểm khác, nhu cầu của bạn có thể giảm khi khách hàng không liên hệ với bạn - ví dụ: qua đêm - vì vậy bạn muốn giải pháp của mình giảm quy mô để giảm chi phí. Giải pháp cũng nên mở rộng quy mô nói chung khi cơ sở khách hàng của bạn phát triển.

Chọn các công cụ thích hợp là rất quan trọng. Serverless Framework, AWS Lambda và DynamoDB phù hợp với trình nghe webhook này, nhưng bạn nên cân nhắc nhu cầu cụ thể của doanh nghiệp. Giải pháp trong bài viết này đáp ứng nhu cầu mở rộng quy mô thay đổi, điều chỉnh để giữ chi phí thấp trong thời gian sử dụng thấp và loại bỏ yêu cầu quản lý cơ sở hạ tầng. Điều này giúp các nhà phát triển dễ dàng triển khai và quản lý.

Tham khảo hướng dẫn thiết lập webhook WhatsApp chính thức để biết thêm thông tin chi tiết về cách sử dụng webhook trong ứng dụng của bạn.