Gửi WhatsApp qua API tích hợp

Xác thực

Xác thực sử dụng một Local API Key trong thân yêu cầu (`api_key`), không phải là tiêu đề HTTP. Mỗi doanh nghiệp có một Local API Key (UUID) được tạo tự động khi doanh nghiệp được tạo.

Cách lấy Local API Key

1. Đăng nhập vào bảng điều khiển cshub tại /app.
2. Mở Cài đặt → API Key (hoặc Hồ sơ → Tích hợp).
3. Sao chép Local API Key. Bạn có thể tạo lại nó bất cứ lúc nào — khóa cũ sẽ trở nên không hợp lệ ngay lập tức.

Điểm cuối

Một điểm cuối duy nhất bao phủ mọi tin nhắn WhatsApp Không chính thức (whatsmeow) gửi đi. Chọn phương thức = text cho các tin nhắn tự do, hoặc phương thức = template để gửi một mẫu mà bạn đã cấu hình trong bảng điều khiển.

Các trường thân yêu cầu

Thân yêu cầu là JSON. Các trường dưới đây tương đương với whatscrmhub Laravel — di chuyển từ phiên bản cũ hơn, hình dạng yêu cầu là giống hệt nhau.

Ví dụ yêu cầu

1. Gửi một tin nhắn văn bản đơn giản

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "6281234567890",
    "method": "text",
    "text": "Halo, makasih udah order ya!"
  }'

2. Gửi một mẫu với việc thay thế biến

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "6281234567890",
    "method": "template",
    "template": "<TEMPLATE_ID>",
    "variables": {
      "$name": "Pak Budi",
      "$order_id": "INV-20260602-001"
    }
  }'

3. Gửi đến một nhóm (sử dụng JID nhóm)

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "120363012345678901@g.us",
    "method": "text",
    "text": "Pengumuman: order minggu ini ditutup pukul 17:00.",
    "is_group": true
  }'

Phản hồi thành công (200 OK)

{
  "status": true,
  "message": "berhasil mengirim pesan"
}

Mã lỗi & cách khắc phục

Ghi chú & giới hạn

• Có một giới hạn daily_send theo từng thiết bị. Tránh gửi hơn ~10 tin nhắn/giây từ một thiết bị duy nhất để tránh bị cấm WhatsApp.
• Nếu doanh nghiệp của bạn có `api_device_use = required`, trường `device_key` là bắt buộc. Nếu nó là tùy chọn, máy chủ sẽ chọn một thiết bị hoạt động dựa trên cài đặt `whatsapp_sender_notif` (`sequence` / `spin` / `random`).
• Việc thay thế biến sử dụng `str_replace` — các placeholder có thể là bất kỳ chuỗi nào (ví dụ: `$name`, `{name}`, `[NAME]`). Nó chỉ cần khớp chính xác với văn bản bên trong tin nhắn mẫu.
• Luôn định dạng mà không có "+" và không có khoảng trắng/dấu gạch ngang. Ví dụ: 6281234567890 (Indonesia), 60123456789 (Malaysia). Đối với các nhóm, sử dụng JID đầy đủ với hậu tố `@g.us`.
• Phiên bản MVP: tải lên tệp nhị phân qua multipart/form-data chưa được hỗ trợ. Để gửi phương tiện, sử dụng phương thức=template với một mẫu đã có hình ảnh được cấu hình trong bảng điều khiển.

API Tích hợp vs API Bảng điều khiển Nội bộ

cshub cố ý giữ hai con đường gửi tin nhắn. API Tích hợp dành cho các nhà phát triển bên thứ ba và tự động hóa; API Nội bộ cung cấp năng lượng cho bảng điều khiển web cshub và ứng dụng di động. Đối tượng khác nhau, xác thực khác nhau, hình dạng phản hồi khác nhau.