RM Platform API
Tài liệu hướng dẫn đưa chat AI và live chat của RM Platform vào sản phẩm của bạn — nhúng vào website, hoặc cho người dùng đã đăng nhập ở hệ thống của bạn vào thẳng khung chat với đúng danh tính (SSO theo chuẩn OAuth 2.0).
1. Môi trường
RM Platform có môi trường riêng cho phát triển/thử nghiệm và production. URL nền tảng (gọi là PLATFORM_URL trong toàn bộ tài liệu) là địa chỉ gốc cho mọi đường dẫn nhúng và xác thực.
| Môi trường | URL nền tảng (PLATFORM_URL) | Mục đích |
|---|---|---|
| Development | https://app.simplize.dev | Phát triển và thử nghiệm tích hợp. |
| Production | Sẽ cung cấp sau | Sử dụng trong ứng dụng thực tế. |
Nền tảng là một OAuth 2.0 / OpenID Connect provider chuẩn: mọi endpoint xác thực được công bố tại {PLATFORM_URL}/.well-known/openid-configuration, khoá ký công bố tại {PLATFORM_URL}/.well-known/jwks.json.
URL production sẽ được Simplize cung cấp sau. Trước đó, vui lòng sử dụng môi trường Development.
Thông tin Simplize cung cấp
| Thông tin | Mô tả | Bí mật? | Dùng cho |
|---|---|---|---|
| PLATFORM_URL | URL nền tảng (ví dụ https://app.simplize.dev) | Không | Mọi đường dẫn nhúng và xác thực |
| Access token | Định danh công khai của ứng dụng chat AI | Không | Nhúng bong bóng chat, trang chat |
| Channel ID | Định danh công khai của kênh live chat | Không | Nhúng live chat |
| client_id | Định danh Ứng dụng OAuth của bạn trên nền tảng | Không | Đăng nhập SSO |
| client_secret | Khoá ký assertion, chỉ giữ ở server | Có | Đăng nhập SSO |
Trên Portal, client_id / client_secret được cấp tại Cài đặt → Cấu hình chung → Ứng dụng OAuth → Tạo ứng dụng; trên môi trường Development, Simplize cấp sẵn và gửi cho bạn.
Chỉ client_secret là thông tin bí mật — tuyệt đối không đưa xuống FE hay commit vào mã nguồn. Các thông tin còn lại là định danh công khai, có thể để ở phía client.
2. Khái niệm cơ bản
| Khái niệm | Ý nghĩa |
|---|---|
| Ứng dụng chat AI | Trợ lý AI bạn tạo trên Portal. Định danh công khai là access token, lấy ở trang ứng dụng → Nhúng vào trang web. |
| Kênh live chat | Kênh hỗ trợ có tư vấn viên (và chatbot kịch bản). Định danh công khai là channel ID, lấy ở kênh → tab Nhúng. |
| Ứng dụng OAuth | Bản ghi cấp client_id / client_secret cho hệ thống của bạn. Một ứng dụng OAuth dùng chung cho mọi khung chat của cùng workspace. |
| Identity assertion | JWT ngắn hạn do backend của bạn ký (RFC 7523), nói "người này là user X của tôi". Nền tảng đổi nó lấy một phiên. |
3. Đưa khung chat vào sản phẩm
Bạn không cần tự dựng giao diện:
- Bong bóng chat AI — nút nổi ở góc màn hình (
{PLATFORM_URL}/chat/embed.js). - Trang chat AI toàn màn hình —
{PLATFORM_URL}/chat/{token}hoặc iframe{PLATFORM_URL}/chat/embed/chatbot/{token}. - Live chat — bong bóng ở góc màn hình (
{PLATFORM_URL}/chat/livechat-embed.js).
Xem Nhúng vào trang web.
4. Tự động đăng nhập người dùng
Cho người dùng đã đăng nhập ở hệ thống của bạn vào thẳng khung chat với đúng danh tính, không phải đăng nhập lại. Backend của bạn ký một assertion, khung chat tự đổi lấy phiên ở POST {PLATFORM_URL}/api/oauth2/token. Nếu bạn tự dựng giao diện, gọi thẳng endpoint ấy.