Setup Webhook

Giới thiệu

Tài liệu này mô tả chi tiết về dịch vụ webhook của Retion, cho phép các doanh nghiệp nhận thông báo theo thời gian thực khi có các sự kiện tương tác mới xảy ra với khách hàng trên các nền tảng được quản lý thông qua Retion.

Mục đích

Webhook của Retion được thiết kế để giúp các doanh nghiệp:

Cập nhật thông tin về các tương tác của khách hàng (tin nhắn, bình luận, kết bạn, …) trên các trang được quản lý thông qua Retion.
Tự động hóa các quy trình làm việc liên quan đến tương tác của khách hàng trên các trang kết nối với Retion.
Đồng bộ dữ liệu tin nhắn từ các trang trên Retion với hệ thống nội bộ.

Cấu hình Webhook trên Retion

Để bắt đầu nhận thông báo webhook từ Retion, doanh nghiệp cần thực hiện các bước sau:

Cung cấp URL Webhook: Trong giao diện quản lý tổ chức trên Retion, doanh nghiệp sẽ được yêu cầu nhập URL API mà hệ thống của họ sẽ sử dụng để nhận các yêu cầu POST từ webhook của Retion. URL này sẽ là điểm đến để doanh nghiệp nhận thông báo về các sự kiện tin nhắn từ các trang của họ trên Retion.
Lưu cấu hình: Sau khi nhập URL, doanh nghiệp cần lưu lại cấu hình trên Retion. Retion sẽ liên kết URL này với tổ chức và sử dụng nó cho các thông báo webhook phát sinh từ bất kỳ trang Facebook nào thuộc tổ chức đó được quản lý trên Retion.
Theo dõi lịch sử gửi: Giao diện người dùng của Retion cũng cung cấp một bảng lịch sử, nơi doanh nghiệp có thể theo dõi các lần gửi webhook gần nhất liên quan đến tổ chức của họ trên Retion, bao gồm thời gian gửi và dữ liệu.

Truy cập Retion > Cài đặt doanh nghiệp > Webhook

Sự kiện Webhook từ Retion

Retion hỗ trợ các sự kiện webhook sau:

comment.create: Kích hoạt khi có một bình luận mới được tạo.
common.friend.accept: Kích hoạt khi khách hàng chấp nhận kết bạn (hiện tại chỉ áp dụng cho nền tảng Zalo cá nhân).
message.create: Kích hoạt khi có một tin nhắn mới được tạo.
message.update: Kích hoạt khi có một tin nhắn được cập nhật.

Mỗi yêu cầu webhook từ Retion sẽ luôn bao gồm các trường sau:

event: Tên của sự kiện đã xảy ra (ví dụ: comment.create, common.friend.accept, message.create).
org_id: ID duy nhất của tổ chức trên Retion.
page_id: ID duy nhất của trang trên Retion.
client_id: ID duy nhất của khách hàng trong hệ thống của Retion.
platform_type: Nền tảng của trang (ví dụ: FB_MESS, ZALO_PERSONAL).

Các trường dữ liệu khác sẽ phụ thuộc vào giá trị của trường event:

1. Sự kiện comment.create

Kích hoạt khi có một bình luận mới được tạo. Dữ liệu bao gồm các trường chung và các trường sau:

{
  "event": "comment.create",
  "org_id": "ID_TỔ_CHỨC_TRÊN_RETION",
  "page_id": "ID_TRANG_TRÊN_RETION",
  "client_id": "UNIQUE_CLIENT_ID",
  "platform_type": "FB_MESS",
  "comment": {
    "ai": [],
    "comment_id": "ID_BÌNH_LUẬN",
    "created_at": "THỜI_ĐIỂM_TẠO_BÌNH_LUẬN (ISO 8601)",
    "message": "NỘI_DUNG_BÌNH_LUẬN",
    "message_attachments": [],
    "parent_id": "ID_BÌNH_LUẬN_CHA (nếu có)",
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_BÌNH_LUẬN (ISO 8601)"
  },
  "conversation": {
    "user_id": "ID_NHÂN_VIÊN_CHĂM_SÓC",
    "last_ad_id": "ID_QUẢNG_CÁO_GẦN_NHẤT",
    "client_name": "TÊN_KHÁCH_HÀNG",
    "client_phone": "SỐ_ĐIỆN_THOẠI_KHÁCH_HÀNG",
    "conversation_id": "ID_CUỘC_HỘI_THOẠI",
    "created_at": "THỜI_ĐIỂM_TẠO_CUỘC_HỘI_THOẠI (ISO 8601)",
    "emotion": "CẢM_XÚC (nếu có)",
    "label_id": [
      "ID_NHÃN_1",
      "ID_NHÃN_2"
    ],
    "last_message": "NỘI_DUNG_TIN_NHẮN_CUỐI",
    "last_message_id": "ID_TIN_NHẮN_CUỐI",
    "last_message_time": TIMESTAMP_UNIX_MILISECONDS,
    "last_message_type": "client" hoặc "page",
    "staff_read": {
      "ID_NHÂN_VIÊN_1": TIMESTAMP_ĐÃ_ĐỌC,
      "ID_NHÂN_VIÊN_2": TIMESTAMP_ĐÃ_ĐỌC
    },
    "unread_message_amount": SỐ_LƯỢNG_TIN_NHẮN_CHƯA_ĐỌC,
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_CUỘC_HỘI_THOẠI (ISO 8601)"
  },
  "message": {
    "ai": [
      {
        "ctas": {}
      }
    ],
    "client_phone": "SỐ_ĐIỆN_THOẠI_KHÁCH_HÀNG",
    "created_at": "THỜI_ĐIỂM_TẠO_TIN_NHẮN (ISO 8601)",
    "message_attachments": [
      {
        "_id": "ID_ĐÍNH_KÈM"
      }
    ],
    "message_id": "ID_TIN_NHẮN",
    "message_text": "NỘI_DUNG_TIN_NHẮN",
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_TIN_NHẮN (ISO 8601)"
  },
  "post": {
    "content": {
      "admin_creator": {
        "id": "ID_NGƯỜI_TẠO_BÀI_VIẾT",
        "name": "TÊN_NGƯỜI_TẠO_BÀI_VIẾT"
      },
      "attachments": {
        "data": [
          {
            "description": "MÔ_TẢ_ĐÍNH_KÈM",
            "media": {
              "image": {
                "height": CHIỀU_CAO_ẢNH,
                "src": "URL_ẢNH",
                "width": CHIỀU_RỘNG_ẢNH
              }
            },
            "target": {
              "id": "ID_MỤC_TIÊU",
              "url": "URL_MỤC_TIÊU"
            },
            "type": "LOẠI_ĐÍNH_KÈM",
            "url": "URL_ĐÍNH_KÈM"
          }
        ]
      },
      "created_time": "THỜI_ĐIỂM_TẠO_BÀI_VIẾT (ISO 8601)",
      "from": {
        "id": "ID_NGƯỜI_ĐĂNG_BÀI",
        "name": "TÊN_NGƯỜI_ĐĂNG_BÀI"
      },
      "id": "ID_BÀI_VIẾT",
      "message": "NỘI_DUNG_BÀI_VIẾT",
      "permalink_url": "URL_BÀI_VIẾT",
      "updated_time": "THỜI_ĐIỂM_CẬP_NHẬT_BÀI_VIẾT (ISO 8601)"
    },
    "post_id": "ID_BÀI_VIẾT"
  }
}

2. Sự kiện common.friend.accept

Kích hoạt khi khách hàng chấp nhận kết bạn (hiện tại chỉ áp dụng cho nền tảng Zalo cá nhân). Dữ liệu bao gồm các trường chung và các trường sau:

{
  "event": "common.friend.accept",
  "org_id": "ID_TỔ_CHỨC_TRÊN_RETION",
  "page_id": "ID_TRANG_TRÊN_RETION",
  "client_id": "UNIQUE_CLIENT_ID",
  "platform_type": "ZALO_PERSONAL",
  "conversation": {
    "user_id": "ID_NHÂN_VIÊN_CHĂM_SÓC",
    "last_ad_id": "ID_QUẢNG_CÁO_GẦN_NHẤT",
    "client_name": "TÊN_KHÁCH_HÀNG",
    "client_phone": "SỐ_ĐIỆN_THOẠI_KHÁCH_HÀNG",
    "conversation_id": "ID_CUỘC_HỘI_THOẠI",
    "created_at": "THỜI_ĐIỂM_TẠO_CUỘC_HỘI_THOẠI (ISO 8601)",
    "label_id": [],
    "last_message": "NỘI_DUNG_TIN_NHẮN_CUỐI",
    "last_message_id": "ID_TIN_NHẮN_CUỐI",
    "last_message_time": TIMESTAMP_UNIX_MILISECONDS,
    "last_message_type": "client",
    "unread_message_amount": SỐ_LƯỢNG_TIN_NHẮN_CHƯA_ĐỌC,
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_CUỘC_HỘI_THOẠI (ISO 8601)"
  },
  "message": {
    "ai": [],
    "attachment_size": [],
    "created_at": "THỜI_ĐIỂM_TẠO_TIN_NHẮN (ISO 8601)",
    "llm_sources": [],
    "message_attachments": [],
    "message_id": "ID_TIN_NHẮN",
    "message_mid": "MESSAGE_ID (nếu có)",
    "message_text": "NỘI_DUNG_TIN_NHẮN",
    "message_type": "client",
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_TIN_NHẮN (ISO 8601)"
  }
}

3. Sự kiện message.create

Kích hoạt khi có một tin nhắn mới được tạo. Dữ liệu bao gồm các trường chung và các trường sau:

{
  "event": "message.create",
  "org_id": "ID_TỔ_CHỨC_TRÊN_RETION",
  "page_id": "ID_TRANG_TRÊN_RETION",
  "client_id": "UNIQUE_CLIENT_ID",
  "platform_type": "FB_MESS" hoặc "ZALO_PERSONAL",
  "conversation": {
    "user_id": "ID_NHÂN_VIÊN_CHĂM_SÓC",
    "last_ad_id": "ID_QUẢNG_CÁO_GẦN_NHẤT",
    "client_email": "EMAIL_KHÁCH_HÀNG (nếu có)",
    "client_name": "TÊN_KHÁCH_HÀNG",
    "client_phone": "SỐ_ĐIỆN_THOẠI_KHÁCH_HÀNG",
    "conversation_id": "ID_CUỘC_HỘI_THOẠI",
    "created_at": "THỜI_ĐIỂM_TẠO_CUỘC_HỘI_THOẠI (ISO 8601)",
    "emotion": "CẢM_XÚC (nếu có)",
    "label_id": [
      "ID_NHÃN_1",
      "ID_NHÃN_2"
    ],
    "last_message": "NỘI_DUNG_TIN_NHẮN_CUỐI",
    "last_message_id": "ID_TIN_NHẮN_CUỐI",
    "last_message_time": TIMESTAMP_UNIX_MILISECONDS,
    "last_message_type": "client" hoặc "page",
    "staff_read": {
      "ID_NHÂN_VIÊN_1": TIMESTAMP_ĐÃ_ĐỌC,
      "ID_NHÂN_VIÊN_2": TIMESTAMP_ĐÃ_ĐỌC
    },
    "unread_message_amount": SỐ_LƯỢNG_TIN_NHẮN_CHƯA_ĐỌC,
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_CUỘC_HỘI_THOẠI (ISO 8601)"
  },
  "message": {
    "ai": [],
    "attachment_size": [],
    "created_at": "THỜI_ĐIỂM_TẠO_TIN_NHẮN (ISO 8601)",
    "llm_sources": [],
    "message_attachments": [],
    "message_id": "ID_TIN_NHẮN",
    "message_metadata": "SIÊU_DỮ_LIỆU_TIN_NHẮN (nếu có)",
    "message_mid": "MESSAGE_ID (nếu có)",
    "message_text": "NỘI_DUNG_TIN_NHẮN",
    "message_type": "client" hoặc "page",
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_TIN_NHẮN (ISO 8601)"
  }
}

Sự kiện message.update

Kích hoạt khi có một tin nhắnđược cập nhật. Dữ liệu bao gồm các trường chung và các trường sau:

{
  "event": "message.create",
  "org_id": "ID_TỔ_CHỨC_TRÊN_RETION",
  "page_id": "ID_TRANG_TRÊN_RETION",
  "client_id": "UNIQUE_CLIENT_ID",
  "platform_type": "FB_MESS" hoặc "ZALO_PERSONAL",
  "conversation": {
    "user_id": "ID_NHÂN_VIÊN_CHĂM_SÓC",
    "last_ad_id": "ID_QUẢNG_CÁO_GẦN_NHẤT",
    "client_email": "EMAIL_KHÁCH_HÀNG (nếu có)",
    "client_name": "TÊN_KHÁCH_HÀNG",
    "client_phone": "SỐ_ĐIỆN_THOẠI_KHÁCH_HÀNG",
    "conversation_id": "ID_CUỘC_HỘI_THOẠI",
    "created_at": "THỜI_ĐIỂM_TẠO_CUỘC_HỘI_THOẠI (ISO 8601)",
    "emotion": "CẢM_XÚC (nếu có)",
    "label_id": [
      "ID_NHÃN_1",
      "ID_NHÃN_2"
    ],
    "last_message": "NỘI_DUNG_TIN_NHẮN_CUỐI",
    "last_message_id": "ID_TIN_NHẮN_CUỐI",
    "last_message_time": TIMESTAMP_UNIX_MILISECONDS,
    "last_message_type": "client" hoặc "page",
    "staff_read": {
      "ID_NHÂN_VIÊN_1": TIMESTAMP_ĐÃ_ĐỌC,
      "ID_NHÂN_VIÊN_2": TIMESTAMP_ĐÃ_ĐỌC
    },
    "unread_message_amount": SỐ_LƯỢNG_TIN_NHẮN_CHƯA_ĐỌC,
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_CUỘC_HỘI_THOẠI (ISO 8601)"
  },
  "message": {
    "ai": [],
    "attachment_size": [],
    "created_at": "THỜI_ĐIỂM_TẠO_TIN_NHẮN (ISO 8601)",
    "llm_sources": [],
    "message_attachments": [],
    "message_id": "ID_TIN_NHẮN",
    "message_metadata": "SIÊU_DỮ_LIỆU_TIN_NHẮN (nếu có)",
    "message_mid": "MESSAGE_ID (nếu có)",
    "message_text": "NỘI_DUNG_TIN_NHẮN",
    "message_type": "client" hoặc "page",
    "updated_at": "THỜI_ĐIỂM_CẬP_NHẬT_TIN_NHẮN (ISO 8601)"
  }
}

Giải thích các trường dữ liệu:

Các trường chung (luôn có trong mọi sự kiện):

event: Tên của sự kiện đã xảy ra (comment.create, common.friend.accept, message.create).
org_id: ID duy nhất của tổ chức trên Retion.
page_id: ID duy nhất của trang trên Retion.
client_id: ID duy nhất của khách hàng trong hệ thống của Retion.
platform_type: Nền tảng của tương tác (FB_MESS, ZALO_PERSONAL).

Các trường dữ liệu tùy thuộc vào sự kiện:

Đối tượng comment (chỉ có trong sự kiện comment.create):

ai: Thông tin liên quan đến AI (nếu có).
comment_id: ID của bình luận.
created_at: Thời điểm tạo bình luận (ISO 8601).
message: Nội dung của bình luận.
message_attachments: Mảng chứa thông tin về các tệp đính kèm trong bình luận (nếu có).
parent_id: ID của bình luận cha (nếu đây là bình luận trả lời).
updated_at: Thời điểm cập nhật bình luận (ISO 8601).

Đối tượng conversation (có trong tất cả các sự kiện):

client_name: Tên của khách hàng.
client_phone: Số điện thoại của khách hàng (nếu có).
conversation_id: ID của cuộc hội thoại.
created_at: Thời điểm cuộc hội thoại được tạo (ISO 8601).
emotion: Cảm xúc được phân tích từ tin nhắn (nếu có).
label_id: Danh sách các ID nhãn được gán cho cuộc hội thoại.
last_message: Nội dung của tin nhắn cuối cùng trong cuộc hội thoại.
last_message_id: ID duy nhất của tin nhắn cuối cùng.
last_message_time: Thời điểm gửi tin nhắn cuối cùng (Unix timestamp tính bằng milliseconds).
last_message_type: Loại người gửi tin nhắn cuối cùng ("client" hoặc "page").
staff_read: Object chứa ID nhân viên Retion và thời điểm họ đọc tin nhắn cuối cùng.
unread_message_amount: Số lượng tin nhắn chưa đọc trong cuộc hội thoại.
updated_at: Thời điểm cập nhật cuộc hội thoại (ISO 8601).
user_id: ID nhân viên được assign
last_ad_id: ID quảng cáo gần nhất
client_email: Địa chỉ email của khách hàng (nếu có, chỉ trong message.create).
label_id: Danh sách các ID nhãn được gán cho cuộc hội thoại (có thể trống trong common.friend.accept).

Đối tượng message (có trong tất cả các sự kiện):

ai: Thông tin liên quan đến AI (nếu có).
attachment_size: Mảng chứa thông tin về kích thước tệp đính kèm (có thể trống).
created_at: Thời điểm tạo tin nhắn (ISO 8601).
llm_sources: Nguồn thông tin từ các mô hình ngôn ngữ lớn (nếu có).
message_attachments: Mảng chứa thông tin về các tệp đính kèm (nếu có).
message_id: ID duy nhất của tin nhắn.
message_text: Nội dung tin nhắn.
updated_at: Thời điểm cập nhật tin nhắn (ISO 8601).
message_mid: Message ID do nền tảng cung cấp (nếu có, trong common.friend.accept và message.create).
message_metadata: Siêu dữ liệu bổ sung của tin nhắn (nếu có, chỉ trong message.create).
message_type: Loại người gửi tin nhắn ("client" hoặc "page", chỉ trong message.create và common.friend.accept).
client_phone: Số điện thoại khách hàng (chỉ trong comment.create).

Đối tượng post (chỉ có trong sự kiện comment.create):

content: Chi tiết nội dung của bài viết.

* admin\_creator: Thông tin về người tạo bài viết.

* id: ID người tạo.
* name: Tên người tạo.
* attachments: Thông tin về các tệp đính kèm của bài viết.
*
  * data: Mảng chứa thông tin từng đính kèm.
  *
    * description: Mô tả đính kèm.
    * media: Thông tin về media (ví dụ: image).
    *
      * image: Thông tin ảnh.
      *
        * height: Chiều cao ảnh.
        * src: URL ảnh.
        * width: Chiều rộng ảnh.
    * target: Mục tiêu của đính kèm.
    *
      * id: ID mục tiêu.
      * url: URL mục tiêu.
    * type: Loại đính kèm.
    * url: URL đính kèm.
* created\_time: Thời điểm tạo bài viết (ISO 8601).
* from: Thông tin về người đăng bài.
*
  * id: ID người đăng.
  * name: Tên người đăng.
* id: ID của bài viết.
* message: Nội dung của bài viết.
* permalink\_url: URL trực tiếp đến bài viết.
* updated\_time: Thời điểm cập nhật bài viết (ISO 8601).

post_id: ID của bài viết.

Xử lý Yêu cầu Webhook từ Retion

Khi hệ thống của doanh nghiệp nhận được một yêu cầu POST từ webhook của Retion, họ nên:

Xác thực yêu cầu: Mặc dù Retion có thể không triển khai cơ chế xác thực phức tạp ở giai đoạn này, doanh nghiệp nên đảm bảo rằng họ chỉ xử lý các yêu cầu được gửi đến URL webhook đã cấu hình trên Retion cho tổ chức của họ. Trong tương lai, Retion có thể bổ sung các phương pháp xác thực an toàn hơn.
Xử lý dữ liệu JSON: Phân tích phần thân JSON của yêu cầu để trích xuất thông tin về tin nhắn mới và các chi tiết liên quan đến cuộc hội thoại và trang từ Retion.
Trả về phản hồi 2xx: Để xác nhận rằng yêu cầu đã được nhận thành công, hệ thống của doanh nghiệp nên trả về mã trạng thái HTTP 2xx (ví dụ: 200 OK, 204 No Content) trong thời gian hợp lý. Nếu Retion không nhận được phản hồi thành công, hệ thống có thể thử gửi lại thông báo webhook sau một khoảng thời gian.

Lưu ý quan trọng khi tích hợp với Retion:

Đảm bảo rằng URL webhook mà doanh nghiệp cung cấp trên Retion có thể truy cập công khai và có khả năng xử lý các yêu cầu POST từ Retion.
Hệ thống của doanh nghiệp nên được thiết kế để xử lý các lượng lớn yêu cầu webhook từ Retion một cách hiệu quả, đặc biệt trong các khung giờ cao điểm.
Chúng tôi khuyến khích doanh nghiệp ghi lại (log) các yêu cầu và phản hồi webhook từ Retion để phục vụ cho việc gỡ lỗi và giám sát quá trình tích hợp.

Hỗ trợ tích hợp Retion Webhook

Nếu doanh nghiệp có bất kỳ câu hỏi nào hoặc cần hỗ trợ trong quá trình tích hợp webhook của Retion, vui lòng liên hệ với đội ngũ hỗ trợ của Retion.