Truy cập API & MCP

Truy cập API & MCP

Metricgram cung cấp API công khai và máy chủ MCP để kết nối công cụ, dashboard, tự động hóa hoặc client AI của bạn với dữ liệu và thao tác có sẵn trong tài khoản.

Máy chủ MCP có trong mọi gói trả phí và trong 14 ngày dùng thử miễn phí. Client AI có thể kết nối bằng OAuth (dán URL máy chủ và phê duyệt quyền truy cập) hoặc bằng token API. REST API yêu cầu quyền truy cập Elite. Nếu tài khoản của bạn không bao gồm tính năng này, phần API có thể bị khóa hoặc hiển thị thông báo nâng cấp.

Tìm ở đâu

Mở Tích hợp > MCP hoặc Tích hợp > API trong bảng quản lý. Tài khoản có quyền truy cập có thể tạo token API, xem token đang hoạt động, thu hồi token và xem tài liệu kỹ thuật có sẵn cho gói của mình.

Token hoạt động như thế nào

• Token thuộc về tài khoản người dùng Metricgram của bạn, không thuộc về một nhóm riêng lẻ.
• Token có thể truy cập các nhóm và tài nguyên mà tài khoản của bạn có quyền quản lý.
• Token bao gồm quyền cho các khu vực như nhóm, thành viên, tin nhắn, tự động hóa, người đăng ký, phân tích, phiếu hỗ trợ, giới thiệu và MCP.
• Một số endpoint chỉ đọc dữ liệu; một số khác có thể tạo, cập nhật, kiểm duyệt hoặc kích hoạt hành động tùy theo quyền của token.
• Giá trị token chỉ hiển thị một lần khi tạo. Hãy lưu trữ an toàn.

Đây không phải API chỉ đọc. Tùy phạm vi token, client có thể sửa cấu hình hoặc thực hiện hành động kiểm duyệt và gửi tin nhắn. Hãy bắt đầu với quyền đọc cần thiết, chỉ bật quyền ghi cho quy trình cụ thể, và tạo token riêng để có thể thu hồi từng công cụ độc lập.

Telegram Bot API qua MCP

Máy chủ MCP cũng cung cấp Telegram Bot API giới hạn theo từng nhóm, để AI agent có thể thao tác trong nhóm của bạn thông qua bot Metricgram hoặc bot tùy chỉnh của bạn.

• Dùng telegram_api_methods để liệt kê các phương thức token của bạn được gọi, và telegram_bot_api để gọi bất kỳ phương thức nào trong số đó với tham số Bot API chính thức.
• Các công cụ có kiểu dữ liệu đáp ứng công việc hằng ngày: send_telegram_message, send_telegram_media, send_telegram_poll, pin_telegram_message, manage_forum_topic, create_telegram_invite_link và nhiều công cụ khác.
• Cuộc trò chuyện luôn là một trong các nhóm của chính bạn. Bạn không bao giờ truyền chat_id; Metricgram tự suy ra từ group_id.
• Thao tác Telegram dùng phạm vi quyền riêng: telegram:read, telegram:write, telegram:moderate và telegram:admin. Token được tạo trước khi có các phạm vi quyền này phải được tạo lại để sử dụng chúng.
• Media phải là URL HTTPS công khai hoặc file_id của Telegram, và nút inline chỉ có thể mở URL hoặc sao chép văn bản.
• Công cụ ghi chấp nhận idempotency_key tùy chọn, nên một lệnh gọi được thử lại sẽ không thực hiện hai lần.

Xác thực và giới hạn

Request API sử dụng header Authorization: Bearer mg_.... Giới hạn mặc định là 600 request mỗi phút cho mỗi token, và biểu mẫu token cho phép chọn giá trị trong khoảng tối thiểu và tối đa mà ứng dụng cho phép.

Nếu token bị thu hồi, tài khoản mất quyền API hoặc gói không còn bao gồm API & MCP, request dùng token đó sẽ bị từ chối.

Thực hành tốt

• Tạo token riêng cho từng công cụ bên ngoài.
• Dùng tên rõ ràng để biết mỗi token được dùng ở đâu.
• Thu hồi token không còn cần nữa.
• Không chia sẻ token trong cuộc trò chuyện, ảnh chụp màn hình, phiếu hỗ trợ hoặc kho mã công khai.

Với client hỗ trợ OAuth, xem lại quyền được yêu cầu trước khi chấp thuận. MCP và REST API có bề mặt thao tác khác nhau; đừng cấp quyền quản trị Telegram cho một công cụ chỉ cần đọc thống kê.