Tài liệu hướng dẫn sử dụng Nui Chatbot API

documentation.md

Hướng dẫn sử dụng API của NuiChatbot:

• Bạn cần lấy token (đầu NUIEAA...) từ web của NuiChatbot.
• Đối với những chỗ trong code của bạn tạo request tới https://graph.facebook.com/..., chuyển thành http://api.chatbot.ngxson.com/graph/...
• Bỏ những chỗ có version, ví dụ /v2.6/messages thì phải sửa thành /messages
• Bỏ https, thay bằng http [2]
• Nui Chatbot API chỉ hỗ trợ các endpoint và method như bảng sau:

graph.facebook.com	api.chatbot.ngxson.com	method	Ghi chú
/{user-id}	/graph/{user-id}	GET
/me/messages	/graph/me/messages	POST
/me/messenger_profile	/graph/me/messenger_profile	POST, GET
/{page-id}/broadcast_messages	/graph/{page-id}/broadcast_messages	POST	[1]
/{page-id}/message_creatives	/graph/{page-id}/message_creatives	POST	[1]
/me/conversations	/graph/me/conversations	GET	[3]
/{thread-id}	/graph/{thread-id}	GET	[3]
/{thread-id}/messages	/graph/{thread-id}/messages	GET	[3]

• Ví dụ: https://graph.facebook.com/v2.6/me/messages sẽ phải đổi thành http://api.chatbot.ngxson.com/graph/me/messages
• Lưu ý quan trọng: Đừng quên tham khảo Giới hạn số lần gặp lỗi

[1]: Broadcast API đã bị facebook ngừng hỗ trợ

[2]: Nếu bạn cần dùng đến https, hãy dùng domain nuichatbot.herokuapp.com. Tuy nhiên, mình không chắc về sự ổn định của domain này (một ngày nào đó, có thể địa chỉ này sẽ bị thay đổi)

[3]: Endpoint này mới được thêm vào kể từ 05/01/2022. Nếu bạn đã lấy token trước ngày này, bạn cần inbox page, bấm đăng nhập để chatbot trả lại nút đăng nhập mới, sau đó lấy token mới thì mới có thể dùng endpoint này

Giới hạn số lần gặp lỗi

Để tránh bị spam lỗi, và cũng là đảm bảo các bạn chú ý hơn về hiệu năng server, chúng mình sẽ có các giới hạn số lần lỗi.

Lỗi có thể do gửi sai dạng dữ liệu, gửi tin nhắn ngoài khung 24+1,... Để tránh vượt giới hạn, bên server bạn phải đc lập trình để nhớ và không lặp lại request lỗi.

Bộ đếm số lỗi sẽ đc reset vào lúc 4 giờ 20 hằng ngày

Đối với webhook

• Tham khảo tại: Yêu cầu đối với webhook

Đối với Graph API

• Khi số lỗi đạt đến "warning level", bạn sẽ thấy cảnh báo ở màn hình đăng nhập Nui Chatbot.
• Nếu vượt quá "max level", token bạn đang dùng sẽ bị khóa. Bạn sẽ cần lên web NuiChatbot để lấy token mới.

endpoint	warning level	max level
/graph/{user-id}	3500 lỗi / ngày	6000 lỗi / ngày
/graph/me/messages	8000 lỗi / ngày	14000 lỗi / ngày
/graph/me/messenger_profile	50 lỗi / ngày	150 lỗi / ngày
/graph/me/broadcast_messages	50 lỗi / ngày	150 lỗi / ngày
/graph/me/message_creatives	50 lỗi / ngày	150 lỗi / ngày
/graph/me/conversations	3500 lỗi / ngày	6000 lỗi / ngày
/graph/{thread-id}	3500 lỗi / ngày	6000 lỗi / ngày
/graph/{thread-id}/messages	3500 lỗi / ngày	6000 lỗi / ngày

---

Liên hệ

Mọi liên lạc (báo lỗi, hỏi đáp, tư vấn,...) hãy gửi email cho mình qua địa chỉ contact@ngxson.com

• Trên tiêu đề nhớ nêu rõ là hỏi về Nui Chatbot
• Trong nội dung email, hãy nêu rõ vấn đề bạn gặp phải. Nên có ảnh chụp màn hình hoặc video quay lại màn hình.
• Hạn chế nhắn tin qua facebook cá nhân (vì mình thường không reply tin nhắn chờ)

webhook.md

NuiChatbot - Yêu cầu đối với webhook

Để đảm bảo chắc chắn bên server bạn nhận đc webhook, cũng như hiệu năng server NuiChatbot, webhook cần đạt những tiêu chuẩn nhất định. Các tiêu chuẩn này được mình làm giống với webhook chuẩn của facebook nhất có thể:

• Phản hồi tất cả sự kiện webhook bằng code 200.
• Phản hồi tất cả sự kiện webhook trong tối đa 12 giây.

Nếu nhận đc code khác 200 hoặc timeout (quá 12s), NuiChatbot sẽ tự động gửi lại tối đa 6 lần, với khoảng thời gian tăng dần (lần lượt là 5s, 10s, 20s, 30s, 30s, 60s). Nếu gửi đến lần thứ 3 mà không thành công, hệ thống sẽ đếm đây là 1 lần lỗi. Giới hạn số lần lỗi như sau:

• Nếu quá 600 lỗi, bạn sẽ nhận đc 1 cảnh báo
• Nếu quá 800 lỗi, bạn sẽ bị xóa webhook

Khi bị xóa webhook, bạn cần lên web NuiChatbot để cài lại webhook. Bộ đếm số lỗi sẽ đc reset vào 4h20 hằng ngày, hoặc ngay khi bạn đặt lại webhook

Gợi ý để tránh gặp lỗi webhook

• Bạn nên trả lại code 200 ngay sau khi nhận webhook, sau đó mới xử lý nội dung.
• Đảm bảo server của bạn luôn trả lại code 200, ngày cả khi process chính bị down (tức cần có process phụ thay thế).