Tích hợp API Meta & Instagram

Tài liệu tham khảo về cách xây dựng ứng dụng Instagram trên Nền tảng ChatHub SMSBAT: xác thực, Cuộc trò chuyện trên Instagram Direct, nhận xét về bài đăng và Câu chuyện, câu trả lời Câu chuyện, webhooks và cuộc thăm dò ý kiến.

---

1. URL cơ sở

Mục đích	URL
API trò chuyện + API Meta	https://chatapi.smsbat.com
Giao diện người dùng vênh vang / OpenAPI	https://chatapi.smsbat.com/index.html · …/swagger/v1/swagger.json
API REST (tổ chức, URL gọi lại)	https://restapi.smsbat.com
Công cụ chuyển đổi API REST	https://restapi.smsbat.com/swagger/v1/swagger.json
Bảng điều khiển web của nhà điều hành	https://chat.smsbat.com

---

2. Xác thực

Lược đồ xác thực phụ thuộc vào nhóm điểm cuối. Trộn lẫn chúng là nguyên nhân phổ biến nhất của 401.

Nhóm	Tiêu đề
chatapi.smsbat.com/api/meta/* (bài viết, bình luận)	X-Authorization-Key: <organization token>
chatapi.smsbat.com/api/chat/*, /api/company/*, /api/operator/*	Authorization: Bearer <JWT>
restapi.smsbat.com/*	X-Authorization-Key · Authorization: Bearer · Xác thực cơ bản

Mã thông báo tổ chức cho X-Authorization-Key được cấp trong bảng điều khiển bên dưới Hồ sơ. JWT của công ty và nhà điều hành đến từ /api/company/get-token và /api/operator/get-token.

2.1 Mã thông báo công ty

POST https://chatapi.smsbat.com/api/company/get-token
Content-Type: application/json

{ "login": "company_login", "password": "company_password" }

200 OK trả về chuỗi mã thông báo trần.

2.2 Tổ chức

GET https://chatapi.smsbat.com/api/company/organization
Authorization: Bearer <company_token>

[ { "id": 24, "name": "My Instagram Store" } ]

2.3 Người vận hành trong một tổ chức

GET https://chatapi.smsbat.com/api/operator?organizationId=24
Authorization: Bearer <company_token>

[
  {
    "id": 21,
    "name": "Jane Doe",
    "status": 0,
    "organization": { "id": 24, "name": "My Instagram Store" }
  }
]

Trạng thái của người vận hành: 0 Đang hoạt động, 1 Không hoạt động, 2 Đã xóa.

2.4 Toán tử thêm/đồng bộ

POST https://chatapi.smsbat.com/api/operator/synchronize
Authorization: Bearer <company_token>
Content-Type: application/json

[ { "organizationId": 24, "name": "John Operator" } ]

200 OK → [ { "id": 21, "status": 0, "name": "John Operator" } ]

2.5 Toán tử JWT

POST https://chatapi.smsbat.com/api/operator/get-token
Authorization: Bearer <company_token>
Content-Type: application/json

{ "id": 21, "expiresAt": "2026-12-31T23:59:59.000Z" }

200 OK trả về JWT dưới dạng chuỗi.

2.6 Xác thực mã thông báo của nhà điều hành

POST https://chatapi.smsbat.com/api/operator/validate-token
Authorization: Bearer <company_token>
Content-Type: application/json

"eyJhbGciOi..."

{
  "isValid": true,
  "operatorId": 21,
  "clientId": 0,
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "error": null
}

Khi không hợp lệ: { "isValid": false, "error": "Invalid token" }.

2.7 Nhúng bảng trò chuyện của nhà điều hành

<script type="module" id="operator-chat-panel-script"
  src="https://widget.smsbat.com/operator-chat-panel/widget-script.js"
  token="YOUR_OPERATOR_JWT_TOKEN"></script>

---

3. Liên kết sâu vào bảng trò chuyện

Một hệ thống bên ngoài (CRM, ERP, website) có thể mở một cuộc trò chuyện cụ thể trong https://chat.smsbat.com/. Toán tử được ủy quyền bởi JWT được truyền dưới dạng tham số truy vấn.

https://chat.smsbat.com/?chat_raw_id=<chat_id>&token=<jwt>
https://chat.smsbat.com/?phone=<phone>&token=<jwt>
https://chat.smsbat.com/?from=<bm_id>&phone=<phone>&token=<jwt>
https://chat.smsbat.com/?source=7&from=<bm_id>&phone=<phone>&token=<jwt>

Tham số	Mô tả
chat_raw_id	ID trò chuyện
phone	Số điện thoại ở định dạng quốc tế
from	Mã nhận dạng tài khoản thương hiệu / doanh nghiệp (bm_id)
source	Nguồn trò chuyện - 7 dành cho Instagram, xem §8.1
token	Nhà điều hành JWT hợp lệ, chưa hết hạn có quyền truy cập vào cuộc trò chuyện

JWT không hợp lệ sẽ đưa khách truy cập vào màn hình đăng nhập của bảng điều hành.

---

4. Cuộc trò chuyện trực tiếp trên Instagram

4.1 Danh sách các cuộc trò chuyện

GET https://chatapi.smsbat.com/api/chat/chats?source=7&page=1&per_page=20
Authorization: Bearer <token>

Tham số truy vấn, tất cả đều tùy chọn:

Tham số	Loại	Mô tả
source	ChatSource	7 giới hạn kết quả ở Instagram
entityId	int	ID tài khoản doanh nghiệp. Chỉ áp dụng cùng với source
instagram_user_id	int	ID người dùng Instagram trong ChatHub
facebook_user_id	int	ID người dùng Facebook trong ChatHub
page / per_page	int	Phân trang, mặc định 1 / 20
status	ChatStatus[]	Trạng thái trò chuyện, có thể lặp lại
search	string	Tìm kiếm văn bản miễn phí (tên, số điện thoại,…)
organizationId	int	ID tổ chức
operatorId	int[]	Lọc theo toán tử được chỉ định
date	string[]	Hai giới hạn: ?date=…&date=…
isChain	bool	Trả lại các cuộc trò chuyện dưới dạng chuỗi, mang tin nhắn từ các cuộc trò chuyện trước đó
isUnread, starMark, isOperator, isAIAgent	bool	Bộ lọc bổ sung
phone, email, contactId, clientId, tagIds, rate, sortedBy	—	Bộ lọc khác

200 OK trả về GetChatsResponse:

{
  "total": 1,
  "newMessagesCount": 2,
  "items": [
    {
      "id": 1867,
      "theme": null,
      "messSource": 7,
      "chatStatus": 1,
      "countUnread": 2,
      "metaUserId": "1585775752382460",
      "instaAccount": { "id": 12, "name": "my_instagram_shop", "photo": "https://..." },
      "instagramUser": { "id": 123, "name": "marianna_cat", "photo": "https://..." },
      "operator": { "id": 21, "name": "Jane", "photo": "https://..." },
      "client": { "id": 55, "name": "Marianna", "photo": null },
      "textLastMess": "Hello! Is this product available?",
      "timeLastMess": "2026-08-13T10:15:00Z",
      "authorLastMessage": 1,
      "messageStatus": 6,
      "isMedia": false,
      "phone": null,
      "organizationId": 1,
      "createdAt": "2026-08-13T10:14:00Z",
      "isStarred": false,
      "isBlocked": false,
      "tags": []
    }
  ]
}

Các trường quan trọng đối với ứng dụng Instagram:

Lĩnh vực	Ý nghĩa
instaAccount	Tài khoản doanh nghiệp trên Instagram (cửa hàng). id là giá trị bộ lọc entityId; name là tên tài khoản từ Meta
instagramUser	khách hàng. name là địa chỉ Instagram, id là giá trị bộ lọc instagram_user_id
metaUserId	ID phạm vi của khách hàng ở phía Meta (chuỗi)
messSource	7 cho Instagram
phone	Thông thường null dành cho Instagram — không sử dụng nó làm chìa khóa

ChatDTO cũng mang olxUser, promUser, waba, rozetkaUser, facebookAccount, facebookUser, viberAccount, tgBot, tgUser, viberBot, viberBotUser, widget, media, isConnectedAI, isPromo, rate, rateComment, closedBy, draft, lang, starMark, contactId, contactName, block, isInStopList, stopList, isSmsFallbackEnabled và taggedMessages.

4.2 Tin nhắn trò chuyện

GET https://chatapi.smsbat.com/api/chat/chats/1867/messages?isChain=false
Authorization: Bearer <token>

200 OK trả về một mảng ChatMessageDTO:

[
  {
    "id": 9928,
    "chatId": 1867,
    "message": "Hi! Do you have size M in stock?",
    "messageTranslation": null,
    "phone": null,
    "author": 1,
    "source": 7,
    "media": null,
    "replyTo": null,
    "status": 6,
    "date": "2026-08-13T10:14:00Z",
    "operator": null,
    "client": { "id": 123, "name": "marianna_cat", "photo": "https://..." },
    "messageType": 0,
    "isInternal": false,
    "isBroadcast": false,
    "starMark": false,
    "referralGuid": null,
    "postId": null,
    "isConnectedAI": false,
    "organizationId": 1,
    "countUnreadMessages": 0
  }
]

postId được điền khi tin nhắn liên quan đến bài đăng hoặc Câu chuyện trên Instagram - hãy chuyển nó đi quay lại thẳng dưới dạng id / postId tới Meta API. media là ChatMediaDTO: { name, format, type, uri, raw, length, isUploaded }.

4.3 Gửi tin nhắn (JSON)

POST https://chatapi.smsbat.com/api/chat/1867/message
Authorization: Bearer <token>
Content-Type: application/json

Cơ thể - SendChatMessageDTO:

{
  "textMessage": "Hello! Yes, size M is available.",
  "author": 0,
  "isInternal": false,
  "replyToMessageId": 9928,
  "appGuid": "550e8400-e29b-41d4-a716-446655440000",
  "media": {
    "name": "item.jpg",
    "format": "image/jpeg",
    "dataBase64": "/9j/4AAQSkZJRg...",
    "type": 1
  }
}

Lĩnh vực	Loại	Mô tả
textMessage	string?	Văn bản tin nhắn. Có thể trống khi có media
author	AuthorMessage?	Nhà điều hành 0, khách hàng 1
isInternal	bool?	true đánh dấu ghi chú nội bộ chưa giao cho khách hàng
replyToMessageId	int?	ID của tin nhắn được trả lời
appGuid	uuid?	HƯỚNG DẪN giới thiệu
media	MediaDTO?	{ name, format, dataBase64, thumbnail, duration, type }

200 OK → { "id": 9930, "messageStatus": 0 }

GUID giới thiệu cũng có thể được chuyển trong đường dẫn: POST /api/chat/{chatId}/{referralGuid}/message (tương tự …/message/v1, …/message/v2).

4.4 Gửi tệp hoặc video (nhiều phần, v2)

POST https://chatapi.smsbat.com/api/chat/1867/message/v2
Authorization: Bearer <token>
Content-Type: multipart/form-data

Trường biểu mẫu	Loại	Mô tả
TextMessage	string	Văn bản tin nhắn
Author	int	Nhà điều hành 0, khách hàng 1
IsInternal	bool	Ghi chú nội bộ
ReplyToMessageId	int	Tin nhắn đang được trả lời
AppGuid	uuid	HƯỚNG DẪN giới thiệu
Media.File	binary	Bản thân tập tin
Media.Name	string	Tên tập tin
Media.Format	string	Loại MIME (video/mp4, image/png, application/pdf)
Media.Type	MediaType	Xem §8.5
Media.DataBase64	string	Thay thế cho Media.File
Media.Thumbnail	string	Khung xem trước video Base64
Media.Duration	double	Thời lượng video tính bằng giây

curl -X POST "https://chatapi.smsbat.com/api/chat/1867/message/v2" \
  -H "Authorization: Bearer <token>" \
  -F "TextMessage=Here is the price list" \
  -F "Author=0" \
  -F "Media.Type=2" \
  -F "Media.File=@./price.pdf"

200 OK → { "id": 9931, "messageStatus": 0 }

4.5 Thay đổi trạng thái trò chuyện

PUT https://chatapi.smsbat.com/api/chat/status
Authorization: Bearer <token>
Content-Type: application/json

{ "id": 1867, "status": 4 }

200 OK lặp lại đối tượng được cập nhật.

4.6 Cập nhật trạng thái tin nhắn

PUT https://chatapi.smsbat.com/api/chat/messages/status
Authorization: Bearer <token>
Content-Type: application/json

{ "status": 3, "messageIds": [9928, 9929] }

4.7 Xóa cuộc trò chuyện

DELETE https://chatapi.smsbat.com/api/chat/chats/1867
Authorization: Bearer <token>

---

5. Bài đăng, Câu chuyện và Câu chuyện

Đường cơ sở: https://chatapi.smsbat.com/api/meta Xác thực: X-Authorization-Key: <organization token>

5.1 Danh sách bài đăng, Câu chuyện và Câu chuyện

GET https://chatapi.smsbat.com/api/meta/posts?platform=instagram&mediaType=story&page=1&perPage=20
X-Authorization-Key: <token>

Tham số	Loại	Bắt buộc	Mô tả
page	int	không	Trang, mặc định 1
perPage	int	không	Các mục trên mỗi trang, mặc định 20
id	int	không	Lọc theo ID bài đăng nội bộ
platform	string	không	instagram hoặc facebook
mediaType	string	không	post, reel hoặc story. Tất cả các loại khi bỏ qua

# Every post
curl -H "X-Authorization-Key: <token>" \
  "https://chatapi.smsbat.com/api/meta/posts?page=1&perPage=10"

# Instagram only
curl -H "X-Authorization-Key: <token>" \
  "https://chatapi.smsbat.com/api/meta/posts?platform=instagram"

# A single post by ID
curl -H "X-Authorization-Key: <token>" \
  "https://chatapi.smsbat.com/api/meta/posts?id=42"

# Instagram Stories only
curl -H "X-Authorization-Key: <token>" \
  "https://chatapi.smsbat.com/api/meta/posts?platform=instagram&mediaType=story"

200 OK:

{
  "total": 42,
  "items": [
    {
      "id": 42,
      "metaId": "18113450675314072",
      "text": "Check out our new collection!",
      "imageUrl": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-1711-4aa8-b21d-f6dbf8f347ef",
      "platform": "instagram",
      "mediaType": "story",
      "createdAt": "2026-07-22T09:35:30Z",
      "story": {
        "id": 42,
        "metaId": "18113450675314072",
        "url": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-1711-4aa8-b21d-f6dbf8f347ef"
      }
    }
  ]
}

Lĩnh vực	Mô tả
id	ID bài đăng nội bộ
metaId	ID bài đăng bên ngoài / Câu chuyện / Câu chuyện trong Meta
text	Chú thích bài đăng
imageUrl	URL phương tiện proxy được khóa bằng MetaPost.Guid không tuần tự hoặc null
platform	facebook hoặc instagram
mediaType	post, reel hoặc story
createdAt	Ngày tạo (ngày nền tảng hoặc ngày cơ sở dữ liệu)
story	Hiện chỉ cho mediaType: "story"
story.id	ID câu chuyện nội bộ; bằng post.id
story.metaId	ID câu chuyện bên ngoài trong Meta
story.url	URL proxy ổn định của phương tiện Câu chuyện được lưu trữ; null nếu không thể lưu phương tiện

Phương tiện đăng bài được phục vụ theo hai tuyến: GET /api/meta/post/media/{id:int} cho lùi khả năng tương thích và GET /api/meta/post/media/{guid:guid}. Phản hồi và gọi lại API mới luôn tạo biểu mẫu GUID.

5.2 Danh sách bình luận

GET https://chatapi.smsbat.com/api/meta/comments?platform=instagram&postId=42&page=1&perPage=20
X-Authorization-Key: <token>

Tham số	Loại	Bắt buộc	Mô tả
page	int	không	Trang, mặc định 1
perPage	int	không	Các mục trên mỗi trang, mặc định 20
postId	int	không	Lọc theo ID bài đăng
parentCommentId	int	không	Nhận xét trẻ em (trả lời) của một nhận xét nhất định
platform	string	không	facebook hoặc instagram

200 OK:

{
  "total": 100,
  "items": [
    {
      "id": 5,
      "metaId": "179000000000005",
      "text": "What is the price?",
      "createdAt": "2026-04-15T10:30:00Z",
      "platform": "instagram",
      "replyStatus": null,
      "author": {
        "type": "meta_user",
        "name": "John Doe",
        "metaUserId": "1585775752382460"
      },
      "post": {
        "id": 1,
        "metaId": "18113450675314072",
        "text": null,
        "imageUrl": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-…",
        "createdAt": "2026-07-22T09:35:30Z",
        "mediaType": "story",
        "story": {
          "id": 1,
          "metaId": "18113450675314072",
          "url": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-…"
        }
      },
      "mediaUrl": "https://chatapi.smsbat.com/api/meta/comment/media/5",
      "replyTo": {
        "id": 3,
        "metaId": "179000000000003",
        "text": "Parent comment..."
      }
    }
  ]
}

Lĩnh vực	Mô tả
id	ID nhận xét nội bộ
metaId	ID bên ngoài trong Meta. null cho câu trả lời đang chờ xử lý của chúng tôi cho đến khi nó được gửi đi
text	Văn bản bình luận
createdAt	Ngày tạo
platform	facebook hoặc instagram
replyStatus	null cho nhận xét của người dùng gửi đến; "pending" / "sent" / "failure" để nhận câu trả lời của chúng tôi
author.type	"meta_user" người dùng bên ngoài, chủ sở hữu trang "owner"
author.name	Tên tác giả
author.metaUserId	ID người dùng có phạm vi trong Meta; null cho "owner"
post	Bài đăng, Câu chuyện hoặc Câu chuyện mà bình luận thuộc về
post.mediaType	post, reel hoặc story
post.story	Tham khảo câu chuyện { id, metaId, url }, Chỉ câu chuyện
mediaUrl	Phương tiện đính kèm với nhận xét hoặc null
replyTo	Nhận xét của phụ huynh { id, metaId, text }; null ở cấp cao nhất

5.3 Trả lời bình luận

Xếp hàng trả lời để gửi.

curl -X POST \
  -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks for the feedback!"}' \
  "https://chatapi.smsbat.com/api/meta/comments/5/reply"

Nội dung yêu cầu: { "text": "Reply text" }

202 Accepted trả về đối tượng nhận xét — có hình dạng giống như GET /api/meta/comments — với replyStatus: "pending" và metaId: null. Kết quả giao hàng đến sau đó dưới dạng source: 13 gọi lại (§6.4).

---

6. Webhook

SMSBAT gửi POST yêu cầu có application/json tới URL của bạn và mong đợi HTTP 200 nhận lại.

6.1 Đăng ký URL gọi lại

curl -X POST 'https://restapi.smsbat.com/organizations/callback_urls' \
  -H 'X-Authorization-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your-server.com/webhook",
    "source": 12,
    "headerName": "X-Webhook-Secret",
    "headerValue": "your-secret",
    "channelType": 7,
    "channelEntityId": 12
  }'

Lĩnh vực	Loại	Mô tả
url	string	Điểm cuối của bạn
source	SendingSourceCallback	Loại sự kiện, xem §8.2
headerName / headerValue	string	Tiêu đề xác thực tùy ý chúng tôi đính kèm theo yêu cầu (tùy chọn)
channelType	ChatSource	Kênh. 7 dành cho Instagram. Tùy chọn
channelEntityId	int	Một tài khoản doanh nghiệp cụ thể. Yêu cầu channelType

Nếu không có channelType, URL sẽ nhận được sự kiện từ mọi kênh.

Các hoạt động còn lại:

GET    https://restapi.smsbat.com/organizations/callback_urls?source=12
GET    https://restapi.smsbat.com/organizations/callback_urls/{id}
PUT    https://restapi.smsbat.com/organizations/callback_urls/{id}
DELETE https://restapi.smsbat.com/organizations/callback_urls/{id}

GET trả về:

[
  {
    "id": 101,
    "url": "https://your-server.com/webhook",
    "source": 12,
    "headerName": "X-Webhook-Secret",
    "headerValue": "your-secret",
    "createdAt": "2026-08-13T09:00:00Z",
    "channelType": 7,
    "channelEntityId": 12
  }
]

6.2 Tin nhắn mới và trả lời Câu chuyện trên Instagram (source: 3, 11)

Câu trả lời của người dùng cho Câu chuyện trên Instagram xuất hiện dưới dạng tin nhắn thông thường trong các cuộc gọi lại này, với khối Story cấp cao nhất bổ sung:

{
  "ChatId": 123,
  "MessageId": 456,
  "MessageText": "😍",
  "Username": "Jane Smith",
  "UserId": 789,
  "MetaUserId": "1585775752382460",
  "ShopId": 12,
  "ShopName": "instagram shop name",
  "Author": 0,
  "type_messenger": 7,
  "Story": {
    "Id": 42,
    "MetaId": "18113450675314072",
    "Url": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-1711-4aa8-b21d-f6dbf8f347ef"
  }
}

Lĩnh vực	Mô tả
ChatId / MessageId	Mã nhận dạng trò chuyện và tin nhắn
Author	người dùng 0, nhà điều hành 1
Username	Tên hiển thị hoặc tên hiển thị trên Instagram / Facebook
UserId	ID người dùng số nội bộ trong SMSBAT
MetaUserId	ID phạm vi của đối tác trò chuyện trong Meta. Trên tin nhắn của nhà điều hành gửi đi, thông báo này vẫn xác định người dùng Meta của cuộc trò chuyện chứ không phải nhà điều hành
ShopId	ID nội bộ của tài khoản doanh nghiệp Instagram / Facebook
ShopName	Tên tài khoản doanh nghiệp nhận được từ Meta tại thời điểm kết nối
MessageText	Văn bản tin nhắn
MessageMedia	URL phương tiện khi tin nhắn là phương tiện
type_messenger	Nguồn, 7 cho Instagram
operator_name	Tên nhà điều hành khi Author = 1
Story	chỉ hiển thị trên câu trả lời Câu chuyện gửi đến
Story.Id	ID Câu chuyện Nội bộ (MetaPost) — có thể sử dụng trực tiếp dưới dạng id / postId trong Meta API
Story.MetaId	ID câu chuyện bên ngoài trong Meta
Story.Url	URL proxy ổn định của phương tiện Story được lưu trữ. Vắng mặt khi không thể lưu phương tiện - khối Story và tin nhắn vẫn được gửi

6.3 Bình luận mới (source: 12)

Kích hoạt khi người dùng Meta bình luận về bài đăng trên Facebook hoặc bài đăng trên Instagram/Câu chuyện.

{
  "type": "new_comment",
  "platform": "instagram",
  "comment": {
    "id": 10,
    "metaId": "179000000000010",
    "parentCommentId": 5,
    "parentMetaId": "179000000000005",
    "parentCommentText": "The user's previous comment",
    "text": "Great product!",
    "createdAt": "2026-04-16T12:00:00Z",
    "author": {
      "type": "meta_user",
      "name": "Jane Smith",
      "metaUserId": "1585775752382460"
    }
  },
  "post": {
    "id": 1,
    "metaId": "123456789012345",
    "text": "Post description...",
    "imageUrl": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-…",
    "createdAt": "2026-04-10T12:00:00Z",
    "mediaType": "post"
  }
}

6.4 Trạng thái trả lời bình luận (source: 13)

Kích hoạt sau khi chúng tôi cố gắng gửi phản hồi, cho dù nó thành công hay thất bại.

{
  "type": "comment_status",
  "platform": "instagram",
  "comment": {
    "id": 15,
    "metaId": "179000000000015",
    "parentCommentId": 10,
    "parentMetaId": "179000000000010",
    "parentCommentText": "Great product!",
    "text": "Thanks for the feedback!",
    "createdAt": "2026-04-16T12:05:00Z",
    "updatedAt": "2026-04-16T12:05:03Z",
    "replyStatus": "sent",
    "author": {
      "type": "owner",
      "name": "Support Agent"
    }
  },
  "post": {
    "id": 1,
    "metaId": "179999999999999",
    "text": "Reel description...",
    "imageUrl": "https://dashboard.smsbat.com/api/meta/post/media/7d124c36-…",
    "createdAt": "2026-07-22T09:35:30Z",
    "mediaType": "reel"
  }
}

6.5 Trường gọi lại nhận xét được chia sẻ

Cả hai lệnh gọi lại nhận xét đều có chung một hình dạng cơ thể và chỉ khác nhau type.

Lĩnh vực	Mô tả
type	"new_comment" hoặc "comment_status"
platform	"facebook" hoặc "instagram"
comment.id	ID nhận xét nội bộ
comment.metaId	ID bên ngoài trong Meta; null để biết câu trả lời đang chờ xử lý trước khi gửi
comment.parentCommentId	ID nhận xét của phụ huynh. Vắng mặt để nhận xét cấp cao nhất
comment.parentMetaId	ID nhận xét gốc bên ngoài. Vắng mặt ở cấp cao nhất
comment.parentCommentText	Văn bản bình luận của phụ huynh. Vắng mặt ở cấp cao nhất
comment.text	Văn bản bình luận
comment.createdAt	Ngày tạo
comment.updatedAt	Cập nhật lần cuối. Vắng mặt nếu bình luận chưa bao giờ được chỉnh sửa
comment.replyStatus	"pending" / "sent" / "failure". Vắng mặt để nhận xét của người dùng gửi đến
comment.author.type	"meta_user" hoặc "owner"
comment.author.name	Tên tác giả
comment.author.metaUserId	ID tác giả có phạm vi trong Meta. Vắng mặt trong "owner"
comment.mediaUrl	Phương tiện bình luận. Vắng mặt khi không có
post.id	ID bài đăng nội bộ
post.metaId	ID bài đăng bên ngoài / Câu chuyện / Câu chuyện trong Meta
post.text	Đăng văn bản
post.imageUrl	Đăng URL hình ảnh hoặc null
post.createdAt	Ngày tạo bài đăng
post.mediaType	Trong các cuộc gọi lại nhận xét, chỉ post hoặc reel

6.6 Trò chuyện mới (source: 7)

{ "ChatId": 12345, "Phone": "+380501234567", "chat.Source": 7 }

6.7 Thay đổi trạng thái tin nhắn và trò chuyện (source: 6 / 5)

{ "name": "changed_message_status", "id": 9928, "status": 6 }
{ "name": "changed_chat_status",    "id": 1867, "status": 4 }

6.8 Đã chỉnh sửa hoặc xóa tin nhắn (source: 9)

{ "messageId": 9930, "text": "Updated message text" }
{ "messageId": 9931, "delete": true }

6.9 Chỉ báo gõ (source: 8)

{ "chat_id": 1867, "event": "start_typing", "operator_name": "Iryna" }
{ "chat_id": 1867, "event": "end_typing" }

---

##7. Sự kiện bỏ phiếu

Đối với các môi trường không thể chấp nhận HTTP gửi đến.

7.1 Tìm nạp sự kiện

GET https://chatapi.smsbat.com/api/chat/callback-events?page=1&perPage=20
Authorization: Bearer <token>

Tham số	Mô tả
organizationId	Không bắt buộc. Lấy từ token khi bỏ qua
page / perPage	Phân trang, mặc định 1 / 20

{
  "page": 1,
  "perPage": 20,
  "total": 947,
  "items": [
    {
      "ChatId": 1867,
      "MessageId": 9928,
      "MessageText": "Hello there!",
      "MessageMedia": null,
      "Phone": null,
      "Username": "marianna_cat",
      "UserId": 123,
      "ShopId": 12,
      "ShopName": "instagram shop name",
      "Author": 1,
      "type_messenger": 7,
      "message_date": "2026-08-13T12:27:39.724Z",
      "timestamp": "2026-08-13T12:27:39.736Z",
      "event_guid": "ff60129e-c6e4-4876-9d90-badb430c0606",
      "organization_id": 1,
      "callback_type": "3"
    }
  ]
}

Mọi sự kiện đều mang theo event_guid, timestamp, organization_id và callback_type — một chuỗi khớp với các giá trị source trong §8.2. Các trường còn lại khớp với trường tương ứng webhook trong §6.

7.2 Xác nhận các sự kiện đã xử lý

POST https://chatapi.smsbat.com/api/chat/callback-events/processed
Authorization: Bearer <token>
Content-Type: application/json

[ "ff60129e-c6e4-4876-9d90-badb430c0606" ]

200 OK → { "deleted": 1 }

Các sự kiện đã bị xóa sẽ không được tính vào deleted. Việc đặt hàng và thử lại là của bạn trách nhiệm của bên.

7.3 Vòng lặp được đề xuất

1. Thăm dò ý kiến GET /api/chat/callback-events theo lịch trình.
2. Xử lý các sự kiện trong dịch vụ của bạn.
3. Gửi danh sách event_guid đã xử lý tới /callback-events/processed.
4. Lặp lại.

---

8. Tham chiếu Enum

8.1 ChatSource — kênh (0–9)

Mã	Kênh
0	Viber
1	ViberBot
2	TelegramBot
3	Whatsapp
4	Tiện ích
5	Rozetka
6	Facebook
7	Instagram
8	vũ hội
9	Olx

8.2 SendingSourceCallback — loại sự kiện gọi lại (0–13)

Mã	Sự kiện
3	Chat — tin nhắn trò chuyện mới, bao gồm cả câu trả lời Câu chuyện
5	Trạng thái trò chuyện đã thay đổi
6	Trạng thái tin nhắn đã thay đổi
7	Trò chuyện mới được tạo
8	Chỉ báo gõ
9	Tin nhắn được cập nhật hoặc xóa
11	AnyChatMessage — bất kỳ tin nhắn trò chuyện nào
12	MetaNewComment — bình luận mới trên Instagram / Facebook
13	MetaCommentStatus — trạng thái gửi phản hồi nhận xét của chúng tôi

Enum kéo dài 0–13; các giá trị còn lại không cần thiết cho việc tích hợp Instagram.

8,3 ChatStatus (0–4)

0 Mới, 1 Mở, 2 Đang chờ, 3 Tạm dừng, 4 Đã đóng

8,4 MessageStatus (0–11)

Mã	Tên
0	MỚI
1	THÀNH CÔNG
2	BỊ TỪ CHỐI
3	ĐỌC
4	KHÔNG BIẾT
5	ĐANG CHẾ BIẾN
6	GIAO HÀNG
7	BLOCKED_BY_USER
8	NGƯỜI DÙNG_NOT_FOUND

Enum trải dài 0–11. Các giá trị 9, 10 và 11 tồn tại trong API nhưng chưa được ghi lại — hãy đối xử với họ như UNKNOWN.

8,5 MediaType (1–10)

1 Ảnh, 2 Tệp, 3 Âm thanh, 4 Video, 5 Nhãn dán, 6 Nhãn dánHoạt hình, 7 Nhãn dánVideo, 8 Hoạt hình, 9 Giọng nói, 10 VideoNote

8.6 AuthorMessage — tác giả trong API trò chuyện (0–4)

0 Nhà điều hành, 1 Khách hàng, 2 Bot, 3 Tài khoản Viber

Enum kéo dài 0–4; giá trị 4 không có giấy tờ. ** Lệnh gọi lại “tin nhắn mới” sử dụng ánh xạ ngược lại** - xem §6.2.

8,7 ChatMessageType (0–2)

0 Văn bản, 1 Ảnh, 2 Tệp

8,8 Bình luận replyStatus

null nhận xét của người dùng gửi đến, "pending" câu trả lời của chúng tôi đang xếp hàng đợi, "sent" đã gửi, "failure" giao hàng không thành công.

---

Câu hỏi mở

Ba điểm trong đó thông số kỹ thuật nội bộ và Swagger do mã tạo ra không đồng nhất. một yêu cầu bằng mã thông báo thực sẽ giải quyết tất cả chúng; cho đến lúc đó, hãy viết cho khách hàng một cách phòng thủ.

#	Câu hỏi	Đặc điểm kỹ thuật	vênh váo	Cách kiểm tra
1	Tiêu đề xác thực cho /api/meta/*	X-Authorization-Key	chỉ Bearer được khai báo	curl -i -H "X-Authorization-Key: <token>" ".../api/meta/posts?perPage=1" — mong đợi 200, không phải 401
2	Trường bộ đếm trong phản hồi Meta	totalCount	total	Yêu cầu tương tự - đọc khóa JSON gốc
3	loại author.type và mã trạng thái reply	"meta_user" / "owner", 202 có thân	int [0,1], 200 không có thân	curl -i .../api/meta/comments?perPage=1 cộng với câu trả lời kiểm tra

Hướng dẫn tạm thời:

• bộ đếm - đọc total ?? totalCount;
• author.type — chấp nhận cả chuỗi và số nguyên (0 ↔ meta_user, 1 ↔ owner, ánh xạ cần được xác nhận);
• reply — coi bất kỳ 2xx nào là thành công, không yêu cầu nội dung, lấy trạng thái cuối cùng từ lệnh gọi lại source: 13.

---

Ghi chú thực hiện

• Quy trình xác thực khác nhau tùy theo nhóm điểm cuối — /api/meta/* sử dụng X-Authorization-Key, trò chuyện và các toán tử sử dụng Bearer, restapi đều chấp nhận.
• Phân trang được đánh vần theo hai cách — per_page trên /api/chat/chats, perPage trên /api/meta/* và /api/chat/callback-events.
• multipart/form-data các trường là PascalCase có ký hiệu dấu chấm (Media.File, Media.Type).
• Các trường rỗng bị bỏ qua trong lệnh gọi lại — khóa vắng mặt có nghĩa là null.
• phone thường là null trên Instagram. Xác định khách hàng bằng instagramUser.id / metaUserId và cửa hàng theo instaAccount.id (giá trị bộ lọc entityId).
• Story.Id từ lệnh gọi lại có thể được chuyển thẳng trở lại dưới dạng id / postId tới Meta API.
• Kiểm tra expiresAt của toán tử JWT trước khi sử dụng nó trong liên kết sâu hoặc tiện ích.