Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Webhook

Webhook là một URL do đối tác chỉ định, nơi nền tảng RCS for Business đăng tin nhắn và sự kiện. URL này đóng vai trò là một điểm cuối nhận các yêu cầu POST qua HTTPS chứa dữ liệu về các sự kiện. Điều này có nghĩa là dữ liệu được gửi đến ứng dụng của bạn một cách an toàn qua HTTPS.

URL webhook có thể có dạng như sau: https://[your company name].com/api/rbm-events. Sau khi định cấu hình webhook, bạn có thể bắt đầu nhận tin nhắn và sự kiện.

Webhook của đối tác và webhook của nhân viên hỗ trợ

Bạn có thể định cấu hình webhook ở cấp đối tác hoặc cấp nhân viên hỗ trợ.

Webhook đối tác của bạn áp dụng cho mọi tác nhân mà bạn duy trì. Nếu các trợ lý ảo của bạn có hành vi tương tự nhau hoặc nếu bạn chỉ có một trợ lý ảo, hãy sử dụng webhook đối tác.
Webhook của nhân viên hỗ trợ áp dụng cho từng nhân viên hỗ trợ. Nếu vận hành nhiều tác nhân có hành vi riêng biệt, bạn có thể đặt một webhook riêng cho từng tác nhân.

Nếu bạn đã định cấu hình cả webhook đối tác và webhook tác nhân, thì webhook tác nhân sẽ được ưu tiên trên tác nhân cụ thể của tác nhân đó, trong khi webhook đối tác sẽ áp dụng cho mọi tác nhân không có webhook riêng.

Định cấu hình webhook của tác nhân

Bạn nhận được tin nhắn gửi đến nhân viên hỗ trợ tại webhook đối tác. Nếu bạn muốn tin nhắn cho một tác nhân cụ thể đến một webhook khác, hãy thiết lập một webhook của tác nhân.

Mở RCS for Business Developer Console rồi đăng nhập bằng Tài khoản Google của đối tác RCS for Business.
Nhấp vào tác nhân của bạn.
Nhấp vào Tích hợp.
Trong phần Webhook, hãy nhấp vào Định cấu hình.
1. Trong Điểm cuối webhook, hãy nhập URL webhook bắt đầu bằng "https://".
2. Trong Mã thông báo của ứng dụng, hãy chỉ định giá trị clientToken. Bạn cần mã này để xác minh rằng những tin nhắn bạn nhận được là từ Google.
Lưu ý: Mã thông báo khách hàng hiện tại của bạn không được hiển thị vì lý do bảo mật. Để tạo mã thông báo khách hàng mới, hãy nhập một giá trị vào trường tương ứng hoặc nhấp vào Làm mới để tạo một giá trị ngẫu nhiên.

Thiết lập webhook để chấp nhận các yêu cầu POST có tải trọng JSON bao gồm các tham số clientToken và secret.

{
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
}

Để xác thực yêu cầu, điểm cuối của bạn phải trả về mã trạng thái HTTP 200 OK với giá trị chuỗi thô của tham số secret trong nội dung phản hồi.

Cấu hình webhook mẫu

Ví dụ: nếu webhook của bạn nhận được một yêu cầu POST có nội dung sau đây:

  {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
  }

Sau đó, webhook của bạn sẽ xác nhận giá trị clientToken và nếu clientToken là chính xác, hãy trả về một phản hồi 200 OK với YOURSECRET làm nội dung phản hồi:

  // clientToken from Configure
  const myClientToken = "YOURCLIENTTOKEN";

  // Example endpoint
  app.post("/rbm-webhook", (req, res) => {
    // Use the X-Goog-Webhook-Type header to route requests
    const webhookType = req.header('X-Goog-Webhook-Type');

    if (webhookType === 'verification') {
      const msg = req.body;
      if (msg.clientToken === myClientToken) {
          res.status(200).send(msg.secret);
          return;
      }
    }
    res.send(400);
    // Handle other webhook types
  });

Trong Developer Console, hãy nhấp vào Xác minh. Sau khi bạn nhấp vào Xác minh, Google sẽ gửi một yêu cầu POST đến webhook của bạn cùng với clientToken và secret làm thông số trong nội dung của yêu cầu. Khi RCS for Business xác minh webhook của bạn, hộp thoại sẽ đóng.

Xác định các loại yêu cầu

Để xác định loại yêu cầu cho tất cả yêu cầu được gửi đến webhook của bạn, hãy sử dụng tiêu đề X-Goog-Webhook-Type.

Tiêu đề có thể có các giá trị sau:

verification: Được dùng cho quy trình xác minh điểm cuối ban đầu.
message_callback: Dùng cho các sự kiện liên quan đến tin nhắn, chẳng hạn như thông báo về việc nhập hoặc gửi và tin nhắn đến từ người dùng.
agent_callback: Dùng cho các sự kiện quản trị dành riêng cho nhân viên hỗ trợ, chẳng hạn như các thay đổi về trạng thái khởi chạy của nhân viên hỗ trợ.

Xác minh tin nhắn đến

Vì webhook có thể nhận tin nhắn từ bất kỳ người gửi nào, nên bạn phải xác minh rằng Google đã gửi tin nhắn đến trước khi xử lý nội dung tin nhắn.

Để xác minh rằng Google đã gửi một thông báo mà bạn nhận được, hãy làm theo các bước sau:

Trích xuất tiêu đề X-Goog-Signature của thư. Đây là bản sao đã băm và được mã hoá base64 của tải trọng nội dung thư.
Giải mã Base-64 tải trọng RCS for Business trong phần tử message.body của yêu cầu.
Sử dụng mã thông báo ứng dụng khách của webhook (bạn đã chỉ định khi thiết lập webhook) làm khoá, hãy tạo một HMAC SHA512 gồm các byte của tải trọng thông báo được giải mã base-64 và mã hoá kết quả base64.
So sánh hàm băm X-Goog-Signature với hàm băm mà bạn đã tạo.
- Nếu các hàm băm khớp nhau, tức là bạn đã xác nhận rằng Google gửi tin nhắn.
- Nếu các hàm băm không khớp, hãy kiểm tra quy trình băm của bạn trên một thông báo đã biết là tốt.
  
  Nếu quy trình băm của bạn hoạt động bình thường và bạn nhận được một thông báo mà bạn cho rằng được gửi cho bạn một cách gian lận, hãy liên hệ với chúng tôi.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);

Xử lý tin nhắn

Việc trả về bất kỳ giá trị nào khác ngoài 200 OK từ webhook đều được coi là lỗi giao hàng.

Nhà phát triển phải lưu ý rằng việc gửi tin nhắn với tốc độ cao sẽ tạo ra thông báo webhook với tốc độ cao và phải thiết kế mã để xử lý thông báo ở tốc độ dự kiến. Nhà phát triển cần cân nhắc những tình huống có thể gây ra phản hồi thất bại, bao gồm cả phản hồi 500 từ vùng chứa web, thời gian chờ hoặc lỗi ở nguồn trên. Những điều cần cân nhắc bao gồm:

Xác minh rằng các biện pháp bảo vệ chống DDoS được định cấu hình để xử lý tốc độ thông báo webhook dự kiến.
Xác nhận rằng các tài nguyên như nhóm kết nối cơ sở dữ liệu không hết và tạo ra thời gian chờ hoặc phản hồi 500.

Nhà phát triển nên thiết kế hệ thống của mình sao cho quá trình xử lý các sự kiện RBM diễn ra không đồng bộ và không ngăn webhook trả về 200 OK.

Xử lý webhook không đồng bộ

Điều quan trọng là bạn không xử lý sự kiện RBM trong chính webhook. Mọi lỗi hoặc sự chậm trễ trong quá trình xử lý đều có thể ảnh hưởng đến mã trả về của webhook:

Xử lý webhook đồng bộ

Hành vi khi không gửi được

Nếu webhook của bạn trả về trạng thái khác với 200 OK, thì nền tảng RCS cho doanh nghiệp sẽ sử dụng cơ chế giảm tốc và thử lại để gửi lại dữ liệu. Điều này có nghĩa là hệ thống sẽ tăng dần độ trễ giữa mỗi lần thử gửi, cuối cùng đạt đến tần suất tối đa là một lần thử lại sau mỗi 10 phút cho mỗi thông báo đang chờ xử lý. Chu kỳ thử lại tiếp tục trong 7 ngày, sau đó thư sẽ bị xoá vĩnh viễn.

Ý nghĩa của webhook ở cấp nhân viên hỗ trợ

RCS for Business xếp tin nhắn vào một hàng đợi cho một đối tác. Tất cả nhân viên hỗ trợ trong một tài khoản đối tác duy nhất đều dùng chung một hàng đợi. Do đó, lỗi trong một webhook có thể chặn toàn bộ hàng đợi, ngăn các sự kiện của người dùng cho tất cả các tác nhân đến được đối tác.

Một số thông báo chưa được xác nhận có thể gây ra sự gia tăng đột biến về các sự kiện thử lại. Ví dụ: nếu một tác nhân không xác nhận 1.600 biên nhận giao hàng và tần suất thử lại đạt đến giới hạn 10 phút, thì tác nhân đó có thể tạo ra khoảng 230.000 lỗi tiềm ẩn mỗi ngày:

1.600 thư × 6 lần thử lại mỗi giờ × 24 giờ mỗi ngày = khoảng 230.000 lỗi mỗi ngày

Số lượng lần thử lại này có thể chặn hàng đợi Pub/Sub dùng chung và gây ra sự chậm trễ đáng kể trong việc nhận các sự kiện của người dùng cho tất cả chiến dịch của một đối tác.

Các phương pháp hay nhất

Để đảm bảo độ tin cậy của lưu lượng truy cập trong quá trình phát hành công khai và tránh các vấn đề chặn hàng đợi, hãy làm theo các phương pháp hay nhất sau:

Trả về 200 OK ngay lập tức: Webhook sẽ nhận được thông báo, lưu trữ thông báo đó trong hàng đợi cục bộ và trả về phản hồi 200 OK trong vòng 5 giây.
Xử lý tách biệt: Sử dụng các worker riêng biệt ở chế độ nền để xử lý logic thông báo từ hàng đợi cục bộ.
Giám sát các tác tử kiểm thử: Xử lý các tác tử phát triển như các tác tử sản xuất, vì chúng cũng có thể chặn hàng đợi đối tác dùng chung nếu không thành công.
Tài khoản riêng cho mục đích kiểm thử: Tốt nhất là bạn nên sử dụng một tài khoản nhà phát triển cho các tác nhân chính thức và một tài khoản nhà phát triển riêng cho các tác nhân kiểm thử.
Xác minh lưu lượng truy cập của Google: Sử dụng DNS ngược hoặc tiêu đề X-Goog-Signature thay vì danh sách cho phép IP cố định, vì Google sử dụng IP truyền tin bất kỳ động. Để biết thêm thông tin về quy trình xác minh thủ công và cách xác định dải IP của Google, hãy xem tài liệu Xác minh yêu cầu của Google và cụ thể là các tệp JSON cho trình tìm nạp do người dùng kích hoạt và trình tìm nạp do người dùng Google kích hoạt.

Các bước tiếp theo

Sau khi bạn định cấu hình webhook, nhân viên hỗ trợ có thể nhận tin nhắn từ thiết bị thử nghiệm. Gửi tin nhắn để xác thực chế độ thiết lập.

Tiếp

Dialogflow