API gửi tin nhắn Zalo cá nhân

Cho hệ thống khác (CRM, website, phần mềm bán hàng…) ra lệnh cho kênh Zalo cá nhân của PenAI gửi tin nhắn: theo số điện thoại hoặc theo UID, có thể kèm ảnh.

Áp dụng cho PenAI từ bản 1.3.0 trở lên · Cập nhật 06/10/2026

Tổng quan

PenAI có hai đường để gửi tin Zalo từ bên ngoài:

Trong bài, https://TEN-MIEN-PENAI là địa chỉ bản PenAI của bạn (ví dụ https://penai.congty.vn).

Chuẩn bị

1. Kênh Zalo cá nhân đã kết nối. Dashboard → Channels → thêm kênh loại zalo_personal → Kết nối QR → quét bằng Zalo trên điện thoại.
2. Khóa API. Dashboard → 🔑 Khóa API (tích hợp) → tạo khóa với vai trò Vận hành (operator) trở lên. Khóa có dạng psk_… và chỉ hiện một lần — lưu lại ngay. Khóa vai trò "Chỉ xem" không gửi được tin. Hướng dẫn từng bước có hình: Lấy khóa API.

Mọi lệnh gọi đều kèm header (phần đầu của yêu cầu HTTP):

Authorization: Bearer psk_xxxxxxxxxxxxxxxx
Content-Type: application/json

1. Lấy mã kênh Zalo

Trả về các kênh Zalo mà khóa được dùng, kèm trạng thái kết nối. Lấy trường id làm CHANNEL_ID cho các lệnh bên dưới.

curl https://TEN-MIEN-PENAI/v1/zalo-inbox/channels \
  -H "Authorization: Bearer psk_xxx"

{
  "channels": [
    {
      "id": "3f0c1a2b-....-....-....-............",
      "name": "Zalo CSKH",
      "enabled": true,
      "connected": true,
      "account": { "id": "1234567890123456789", "name": "Nguyễn Văn A" }
    }
  ]
}

connected: false nghĩa là kênh đã mất đăng nhập — cần vào Dashboard quét QR lại trước khi gửi.

2. Gửi tin theo số điện thoại hoặc UID

Đây là lệnh chính. Truyền một trong hai: phone hoặc to.

Phải có ít nhất text hoặc image; có thể gửi cả hai.

Ví dụ: gửi theo số điện thoại, kèm ảnh

curl -X POST https://TEN-MIEN-PENAI/v1/zalo-inbox/CHANNEL_ID/new \
  -H "Authorization: Bearer psk_xxx" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

Nội dung file body.json (lưu dạng UTF-8):

{
  "phone": "0912345678",
  "text": "Chào anh, đơn hàng #1024 đã được giao cho đơn vị vận chuyển.",
  "image": "https://example.com/hoa-don-1024.jpg"
}

Ví dụ: gửi theo UID, chỉ có chữ

{ "to": "1234567890123456789", "text": "Lịch hẹn của anh là 9h sáng mai." }

Ví dụ: gửi vào nhóm

{ "to": "9876543210987654321", "peerKind": "group", "text": "Báo cáo cuối ngày đã sẵn sàng." }

Kết quả thành công

{ "sent": true, "threadId": "1234567890123456789", "peerKind": "direct" }

threadId chính là UID của người nhận (hoặc ID nhóm). Khi gửi theo số điện thoại, hãy lưu lại threadId để lần sau gửi thẳng bằng to — nhanh hơn và không phải tra Zalo lần nữa.

3. Tra UID từ số điện thoại (không gửi tin)

curl "https://TEN-MIEN-PENAI/v1/zalo-inbox/CHANNEL_ID/find-phone?phone=0912345678" \
  -H "Authorization: Bearer psk_xxx"

{ "found": true, "user": { "uid": "1234567890123456789", "name": "Trần Thị B", "avatar": "https://..." } }

Không tìm thấy: { "found": false, "user": null }. Trường hợp này có thể do số chưa dùng Zalo hoặc người đó tắt "cho phép tìm qua số điện thoại" — API không phân biệt được hai trường hợp.

4. Gửi vào hội thoại đã có

Dùng khi đã biết THREAD_ID (UID người nhận hoặc ID nhóm). Body giống lệnh ở mục 2 nhưng không có to/phone:

{ "text": "Cảm ơn anh đã phản hồi.", "image": "https://example.com/anh.png" }

Kết quả:

{ "sent": true, "msgIds": ["6871234567890"] }

5. Các API Inbox khác

Mã lỗi

Khi lỗi, API trả JSON dạng { "error": "mô tả", "code": "MÃ" }.

Kết nối ứng dụng AI (MCP)

Địa chỉ MCP của bạn: https://TEN-MIEN-PENAI/mcp — xem và sao chép ở Dashboard → 🔗 Kết nối AI bên ngoài.

• Claude: Settings → Connectors → Add custom connector → dán địa chỉ → Connect.
• ChatGPT: Settings → Apps & Connectors → Advanced → bật Developer mode → Create → dán địa chỉ, chọn OAuth.

Trình duyệt mở trang cấp quyền của PenAI: đăng nhập bằng tài khoản Dashboard, tick quyền rồi bấm Cấp quyền. Mật khẩu không chuyển cho ứng dụng AI.

Khác với REST API, đường MCP có sẵn hai lớp bảo vệ:

• Chống gửi trùng: truyền request_id (một mã UUID) cho mỗi tin; thử lại cùng tin thì giữ nguyên mã — PenAI sẽ không gửi lần hai.
• Giãn nhịp: mỗi kênh 1 tin / 2 giây; gửi dồn nhận RATE_LIMITED kèm retry_after_seconds (số giây cần chờ).

Lưu ý quan trọng

• Zalo cá nhân không phải kênh chính thức cho gửi hàng loạt. Kết nối dùng cơ chế của Zalo Web; gửi nhiều tin cho người lạ trong thời gian ngắn có thể làm tài khoản bị Zalo giới hạn hoặc khóa. Nên gửi cách nhau vài giây và ưu tiên người đã từng nhắn với tài khoản.
• REST API không tự chống gửi trùng. Gọi lệnh gửi hai lần là gửi hai tin. Hệ thống của bạn cần tự ghi nhận tin nào đã gửi; khi gặp lỗi 502 thì kiểm tra trước, đừng tự động gửi lại.
• Gửi theo UID không kiểm tra trước. UID sai sẽ được Zalo từ chối ở bước gửi (lỗi 422).
• Không gửi được cho chính UID của tài khoản đang kết nối.
• Một tài khoản — một nơi đăng nhập Zalo Web. Mở Zalo Web trên trình duyệt bằng cùng tài khoản có thể làm PenAI mất kết nối.
• Tin gửi qua REST API hiện trong Inbox Zalo như tin do người trực gửi; AI sẽ tạm im trong hội thoại đó theo số phút ở Inbox → ⚙️ Cài đặt (mặc định 30 phút).