Nền tảng Messenger

API Cuộc trò chuyện cho Nền tảng Messenger

Tài liệu này giải thích cách lấy thông tin về cuộc trò chuyện trên Messenger và cuộc trò chuyện qua tính năng Nhắn tin trên Instagram. Bạn có thể lấy:

  • Danh sách cuộc trò chuyện cho Trang Facebook hoặc Tài khoản công việc trên Instagram của mình
  • Danh sách tin nhắn trong mỗi cuộc trò chuyện
  • Chi tiết về mỗi tin nhắn, bao gồm cả thời gian gửi và người gửi tin nhắn

Trước khi bạn bắt đầu

Hướng dẫn này giả định rằng bạn đã đọc phần Tổng quan về nền tảng Messenger và Tổng quan về tính năng Nhắn tin trên Instagram, cũng như triển khai các thành phần cần thiết.

Bạn sẽ cần:

  • ID Trang Facebook của doanh nghiệp bạn hoặc Trang Facebook liên kết với Tài khoản công việc trên Instagram
  • Mã truy cập Trang do một người có thể thực hiện tác vụ MESSAGING hoặc MODERATE trên Trang đó yêu cầu
  • Bạn cần có Quyền truy cập nâng cao để truy cập cuộc trò chuyện giữa doanh nghiệp và những người không có vai trò trên ứng dụng nhắn tin, Tài khoản công việc trên Instagram, Trang Facebook hoặc doanh nghiệp của bạn

Đối với cuộc trò chuyện trên Messenger giữa người dùng và Trang, ứng dụng của bạn sẽ cần:

Đối với cuộc trò chuyện qua tính năng Nhắn tin trên Instagram giữa người dùng và Tài khoản công việc trên Instagram, ứng dụng của bạn sẽ cần:

  • Mã truy cập Trang do một người có thể thực hiện tác vụ MESSAGING trên Trang liên kết với tài khoản Kinh doanh trên Instagram của bạn yêu cầu
  • Các quyền instagram_basic, instagram_manage_messages và pages_manage_metadata
  • Ứng dụng của bạn phải do một doanh nghiệp đã được xác minh sở hữu

Giới hạn

  • Chỉ URL video hoặc hình ảnh của nội dung chia sẻ mới được đưa vào dữ liệu trả về trong lệnh gọi đến API hoặc trong thông báo webhook.
  • Nếu tài khoản của bạn được liên kết bằng các khóa riêng tư, chẳng hạn như email hoặc số điện thoại, bạn sẽ không thể truy xuất cuộc trò chuyện giữa các tài khoản này. Bạn chỉ có thể truy xuất cuộc trò chuyện giữa Người dùng Facebook và tài khoản Instagram. Vấn đề này sẽ được giải quyết khi ứng dụng của bạn được phê duyệt Quyền truy cập nâng cao. Nếu có nhiều tài khoản được liên kết trong Trung tâm tài khoản trên ứng dụng Instagram, bạn sẽ có thể truy xuất cuộc trò chuyện giữa tất cả tài khoản liên kết.
  • Các cuộc trò chuyện trong thư mục Tin nhắn đang chờ sẽ không được trả về trong lệnh gọi API nếu không hoạt động trong 30 ngày.

Bạn có thể tận dụng API này để đồng bộ những cuộc trò chuyện trước đây trong hộp thư khi một tài khoản kinh doanh trên Instagram mới được kết nối với ứng dụng của bạn.

Lấy danh sách cuộc trò chuyện

Để lấy danh sách cuộc trò chuyện, hãy gửi yêu cầu GET đến điểm cuối /PAGE-ID/conversations và thêm thông số platform được đặt thành instagram hoặc messenger.

Yêu cầu mẫu

Được định dạng để dễ đọc
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

Sau khi thành công, ứng dụng của bạn sẽ nhận được một đối tượng JSON kèm theo danh sách ID của các cuộc trò chuyện giữa bạn và người dùng, cũng như thời gian gửi tin nhắn gần đây nhất.

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

Tìm cuộc trò chuyện với một người dùng cụ thể

Để lấy cuộc trò chuyện giữa Tài khoản công việc trên Instagram hoặc Trang Facebook và một người cụ thể, hãy gửi yêu cầu GET đến điểm cuối /PAGE-ID/conversations với thông số platform và thông số user_id được đặt thành ID trong Instagram hoặc ID người dùng trong Trang của người đó.

Yêu cầu mẫu

Được định dạng để dễ đọc
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

Sau khi thành công, ứng dụng của bạn sẽ nhận được ID của cuộc trò chuyện đó.


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

Lấy danh sách tin nhắn trong cuộc trò chuyện

Để lấy danh sách tin nhắn trong một cuộc trò chuyện, hãy gửi yêu cầu GET đến điểm cuối /CONVERSATION-ID và thêm trường messages.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

Sau khi thành công, ứng dụng của bạn sẽ nhận được danh sách ID tin nhắn và thời gian tạo của từng tin nhắn.

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

Lấy thông tin về tin nhắn

Để lấy thông tin về một tin nhắn, chẳng hạn như người gửi, người nhận và nội dung tin nhắn, hãy gửi yêu cầu GET đến điểm cuối /MESSAGE-ID cùng với các trường mà bạn quan tâm.

Các trường mặc định là id và created_time.

Lưu ý: Truy vấn đến điểm cuối /CONVERSATION-ID sẽ trả về tất cả ID tin nhắn trong một cuộc trò chuyện. Tuy nhiên, bạn chỉ có thể lấy thông tin chi tiết về 20 tin nhắn gần đây nhất trong cuộc trò chuyện đó. Nếu tin nhắn được truy vấn không nằm trong 20 tin nhắn gần đây, bạn sẽ nhìn thấy lỗi cho biết tin nhắn này đã bị xóa. 

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

Nếu thành công, ứng dụng của bạn sẽ nhận được phản hồi JSON sau đây. Trong ví dụ này, khách hàng đã gửi một tin nhắn văn bản thuần túy đến Tài khoản công việc trên Instagram của bạn.

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

Tìm hiểu thêm

Hãy truy cập tài liệu tham khảo của chúng tôi dành cho:

Hỗ trợ nhà phát triển