CareChat Bot API

Bot là một tài khoản đặc biệt trên CareChat do bạn tạo ra và điều khiển bằng mã (token). Bot dùng được cho hai việc:

• Gửi thông báo một chiều: đơn hàng mới, OTP nội bộ, cảnh báo máy chủ, nhắc lịch... tới một người hoặc cả nhóm.
• Nối hội thoại hai chiều: nhận tin người dùng gửi cho bot (qua getUpdates hoặc webhook) rồi trả lời bằng chatbot, CRM, hệ thống CSKH của bạn.

Người dùng tìm bot bằng @username trong ô tìm kiếm tin nhắn của CareChat, bấm Bắt đầu, hoặc thêm bot vào nhóm như thêm một thành viên. Bot chỉ nhắn được cho người đã bắt đầu chat với bot và nhóm có bot - không thể tự nhắn người lạ.

1. Đăng nhập my.carechat.vn/bots → Tạo bot: đặt tên và username (kết thúc bằng bot, vd shop_bot). Sao chép token dạng 123:AbCd....
2. Trên CareChat, người nhận tìm @shop_bot → mở chat → bấm Bắt đầu (gửi /start). Muốn gửi vào nhóm: thêm @shop_bot vào nhóm.
3. Gọi getUpdates để thấy tin /start và lấy message.chat.id (hoặc gọi getChats để liệt kê mọi cuộc trò chuyện bot đang ở).
4. Gửi tin bằng sendMessage với chat_id vừa lấy.

Kiểm tra token:

curl "https://api.carechat.vn/api/chatapp/bot/123:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-Xy/getMe"

Mọi method có dạng:

https://api.carechat.vn/api/chatapp/bot/<TOKEN>/<method>

• Dùng GET hoặc POST. Tham số gửi qua query string, JSON (application/json), form (application/x-www-form-urlencoded) hoặc multipart/form-data (bắt buộc khi tải file ảnh lên).
• Tên method không phân biệt hoa thường. Dữ liệu và kết quả dùng UTF-8.
• Thành công: HTTP 200 với {"ok": true, "result": ...}. Lỗi: mã HTTP bằng error_code kèm description mô tả lý do (tiếng Việt).

{
  "ok": false,
  "error_code": 400,
  "description": "Không tìm thấy cuộc trò chuyện (chat_id sai hoặc bot không ở trong cuộc trò chuyện này)"
}

Mỗi cuộc trò chuyện có một mã số công khai chat_id (giống Telegram). Bot dùng mã này để gửi tin; mã có sẵn trong mọi tin / cập nhật bot nhận được ở message.chat.id.

Gửi tin văn bản

sendMessage gửi tối đa 4000 ký tự (hỗ trợ emoji, xuống dòng). Muốn trả lời một tin cụ thể thì thêm reply_to_message_id.

curl -X POST "https://api.carechat.vn/api/chatapp/bot/123:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-Xy/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": -1001234567890, "text": "Đơn hàng #1024 đã giao thành công ✅"}'

Gửi ảnh

sendPhoto nhận file tải lên (multipart, trường photo) hoặc URL ảnh http(s) công khai. JPEG / PNG / GIF / WebP, tối đa 10 MB, kèm chú thích caption.

# Tải file ảnh lên (multipart)
curl -X POST "https://api.carechat.vn/api/chatapp/bot/123:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-Xy/sendPhoto" \
  -F chat_id=1234567890 \
  -F caption="Hoá đơn tháng 10" \
  -F [email protected]

# Hoặc đưa URL ảnh công khai
curl -X POST "https://api.carechat.vn/api/chatapp/bot/123:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-Xy/sendPhoto" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 1234567890, "photo": "https://example.com/banner.jpg", "caption": "Khuyến mãi"}'

Sửa / xoá tin đã gửi

Lưu result.message_id sau khi gửi để sửa nội dung bằng editMessageText (vd cập nhật trạng thái đơn) hoặc thu hồi bằng deleteMessage.

Mỗi khi người dùng nhắn cho bot, sửa tin, hoặc thêm / mời bot ra khỏi nhóm, CareChat tạo một cập nhật (Update) có update_id tăng dần. Cách đơn giản nhất để nhận là long polling: gọi getUpdates với timeout tới 50 giây - không có tin thì máy chủ giữ kết nối và trả về ngay khi có tin mới.

• Gửi offset = update_id lớn nhất đã xử lý + 1 để xác nhận; các cập nhật cũ hơn bị xoá khỏi hàng đợi.
• Cập nhật chưa xác nhận được giữ 24 giờ, tối đa 1000 cập nhật mỗi bot (quá thì bỏ cái cũ nhất).
• Không dùng được getUpdates khi bot đang đặt webhook (lỗi 409).

// Bot trả lời tự động bằng long polling (không cần máy chủ có IP / tên miền công khai)
let offset = 0;

while (true) {
  const res = await fetch(`${API}/getUpdates?timeout=50&offset=${offset}`);
  const { ok, result, description } = await res.json();
  if (!ok) {
    console.error(description);
    await new Promise((r) => setTimeout(r, 5000));
    continue;
  }
  for (const update of result) {
    offset = update.update_id + 1; // lần gọi sau xác nhận đã xử lý
    const msg = update.message;
    if (!msg?.text) continue;
    if (msg.text.startsWith('/start')) {
      await sendMessage(msg.chat.id, `Chào ${msg.from.first_name}! Mã chat của bạn là ${msg.chat.id}`);
    } else {
      await sendMessage(msg.chat.id, 'Shop đã nhận tin, nhân viên sẽ phản hồi sớm.');
    }
  }
}

Một cập nhật tin nhắn:

{
  "update_id": 1042,
  "message": {
    "message_id": 8812,
    "from": { "id": 315, "is_bot": false, "first_name": "Nguyễn Văn A" },
    "chat": { "id": 4829104731, "type": "private", "first_name": "Nguyễn Văn A" },
    "date": 1791709842,
    "text": "/start",
    "entities": [{ "type": "bot_command", "offset": 0, "length": 6 }]
  }
}

Có máy chủ HTTPS công khai thì đặt webhook: mỗi cập nhật được POST (JSON một Update) tới URL của bạn ngay khi phát sinh, không cần giữ kết nối polling.

curl -X POST "https://api.carechat.vn/api/chatapp/bot/123:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-Xy/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://shop.example.com/carechat/webhook", "secret_token": "chuoi_bi_mat_cua_ban"}'

• URL phải là https://, cổng 443, 80, 88 hoặc 8443, tên miền trỏ ra Internet (không nhận IP nội bộ).
• Header X-CareChat-Bot-Api-Secret-Token (và X-Telegram-Bot-Api-Secret-Token cho thư viện Telegram) mang secret_token bạn đặt - hãy kiểm tra để chặn request giả.
• Trả mã 2xx trong 15 giây = đã nhận. Lỗi / quá giờ thì CareChat gửi lại theo đúng thứ tự, giãn cách 5 giây tăng dần tới 10 phút, trong 24 giờ. Xem lỗi gần nhất bằng getWebhookInfo hoặc ở trang Bot.
• Gỡ webhook để quay lại polling: deleteWebhook (thêm drop_pending_updates=true để bỏ cập nhật đang chờ).

import express from 'express';

const app = express();
app.use(express.json());

app.post('/carechat/webhook', async (req, res) => {
  // Chỉ nhận request mang đúng secret_token đã đặt ở setWebhook
  if (req.get('X-CareChat-Bot-Api-Secret-Token') !== process.env.CARECHAT_WEBHOOK_SECRET) {
    return res.sendStatus(403);
  }
  res.sendStatus(200); // trả 2xx ngay, xử lý sau (quá 15 giây bị tính là lỗi và gửi lại)

  const msg = req.body.message;
  if (msg?.text) await sendMessage(msg.chat.id, 'Shop đã nhận: ' + msg.text);
});

app.listen(3000);

Chủ / quản trị nhóm thêm bot bằng @username như thêm thành viên. Bot nhận cập nhật my_chat_member (trạng thái member) kèm chat_id của nhóm; bị mời ra thì trạng thái left.

{
  "update_id": 1043,
  "my_chat_member": {
    "chat": { "id": -1007426193058, "type": "group", "title": "Kho Hà Nội" },
    "from": { "id": 315, "is_bot": false, "first_name": "Nguyễn Văn A" },
    "date": 1791709900,
    "old_chat_member": { "user": { "id": 57, "is_bot": true, "first_name": "CSKH Shop", "username": "shop_bot" }, "status": "left" },
    "new_chat_member": { "user": { "id": 57, "is_bot": true, "first_name": "CSKH Shop", "username": "shop_bot" }, "status": "member" }
  }
}

Chế độ riêng tư (mặc định bật): trong nhóm bot chỉ nhận tin bắt đầu bằng lệnh /... (vd /baocao, /baocao@shop_bot), tin có nhắc @shop_bot và tin trả lời tin của bot. Tắt chế độ này ở trang Bot → Cài đặt nếu bot cần đọc mọi tin trong nhóm. Chat riêng luôn nhận mọi tin. Bot không nhận tin của bot khác.

Update

Có update_id và đúng một trong các trường: message (tin mới), edited_message (tin vừa sửa), my_chat_member (bot được thêm vào / rời cuộc trò chuyện; người dùng mở chat riêng với bot cũng tạo cập nhật này).

User

{ "id": 315, "is_bot": false, "first_name": "Nguyễn Văn A" }
// Bot: { "id": 57, "is_bot": true, "first_name": "CSKH Shop", "username": "shop_bot" }

Để bảo vệ người dùng, Bot API không trả email / số điện thoại của họ.

Chat

Message

{
  "message_id": 8812,
  "from": User,
  "chat": { "id": -1007426193058, "type": "group", "title": "Kho Hà Nội" },
  "date": 1791709842,            // Unix time (giây)
  "edit_date": 1791709900,       // có khi tin đã sửa
  "text": "Nội dung",            // tin văn bản
  "entities": [ { "type": "bot_command", "offset": 0, "length": 6 } ],
  "caption": "Chú thích",        // tin ảnh
  "photo": [ { "file_id": "991", "file_unique_id": "991", "width": 1280, "height": 720, "file_size": 183022 } ],
  "photos": [ ... ],             // tin nhiều ảnh: đủ mọi ảnh (photo chỉ có ảnh đầu)
  "reply_to_message": Message    // tin được trả lời (một tầng)
}

Tên method, tham số và đối tượng đặt theo Telegram nên nhiều thư viện Telegram dùng lại được bằng cách đổi địa chỉ API (vd python-telegram-bot base_url="https://api.carechat.vn/api/chatapp/bot/"). Khác biệt chính:

• Chỉ hỗ trợ các method liệt kê ở trên; gọi method khác nhận 404.
• Tin hiển thị văn bản thuần, chưa định dạng HTML / Markdown (parse_mode bị bỏ qua).
• Nhóm có type là group (không có supergroup / channel). photo chỉ có một kích thước.
• Tải file qua /botfile/<TOKEN>/<file_id> thay vì /file/bot<TOKEN>/<file_path>.
• Có thêm getChats và trường photos (tin nhiều ảnh).

• Token là mật khẩu của bot: chỉ để ở máy chủ (biến môi trường), không đưa vào mã chạy trên trình duyệt / app.
• Lộ token: vào trang Bot → Đổi token, token cũ hết hiệu lực ngay.
• Webhook: luôn đặt secret_token và kiểm tra header trước khi xử lý.
• Tắt bot (trang Bot → Cài đặt) để tạm dừng mọi lời gọi API mà không mất cấu hình.