Agent API Reference

🤖 Agent API Reference

Thông tin nhanh

• Base URL: https://api.salehay.com
• Auth: Header X-Agent-Token: agent_xxx (tạo tại Admin → Settings → Agent Tokens)
• Rate Limit: Mặc định 60 req/phút (cấu hình per-token)
• Scoped Permissions: Mỗi token có danh sách scopes riêng
• Response: application/json

Xem thêm: Agent Tokens · Webhooks · MCP Server

Xác thực

Mỗi request phải gửi header X-Agent-Token:

curl -H "X-Agent-Token: agent_abc123def456..." https://api.salehay.com/api/agent/analytics

Scopes

Token cần scope phù hợp cho mỗi endpoint:

Scope	Quyền
leads:read	Tìm kiếm, đọc leads
leads:write	Tạo mới, cập nhật leads
bookings:read	Đọc bookings
calls:write	Ghi nhận cuộc gọi
messages:write	Gửi/log tin nhắn
analytics:read	Đọc analytics
*	Toàn quyền

---

1. Tạo Lead mới

POST /api/agent/leads

Scope: leads:write

Request Body:

{
  "phone": "0901234567",
  "name": "Nguyễn Văn A",
  "email": "a@gmail.com",
  "source": "agent",
  "service_interest": "Massage Trị Liệu",
  "note": "Khách quan tâm gói cao cấp",
  "priority": "high",
  "custom_fields": { "budget": "5tr" }
}

Field	Type	Bắt buộc	Mô tả
phone	string	✅	SĐT Việt Nam (bắt đầu 0, 9-11 số)
name	string	❌	Tên khách hàng
email	string	❌	Email
source	string	❌	Nguồn: facebook, google, tiktok, zalo, website, agent (default: agent)
service_interest	string	❌	Dịch vụ quan tâm
note	string	❌	Ghi chú
priority	string	❌	low, normal (default), high
custom_fields	object	❌	Fields tùy chỉnh { "key": "value" }

Response 201:

{
  "ok": true,
  "lead_id": "uuid",
  "customer_id": "uuid",
  "status": "new"
}

Mẹo

Hệ thống tự động tạo Customer nếu phone chưa tồn tại, hoặc liên kết với Customer đã có. Webhook lead.created được fire tự động.

---

2. Tìm kiếm Lead

GET /api/agent/leads/search?q=0901&status=new&limit=20

Scope: leads:read

Param	Type	Bắt buộc	Mô tả
q	string	❌*	Tìm theo SĐT hoặc tên (ILIKE)
status	string	❌*	Filter: new, contacted, appointment_set, qualified, converted, lost
limit	number	❌	Max kết quả (default 20, max 50)

*Ít nhất một trong q hoặc status là bắt buộc.

Response 200:

{
  "leads": [
    {
      "id": "uuid",
      "status": "new",
      "priority": "high",
      "source": "facebook",
      "service_interest": "Massage",
      "phone": "0901234567",
      "name": "Nguyễn Văn A",
      "email": "a@gmail.com",
      "created_at": "2026-03-17T..."
    }
  ],
  "total": 1
}

---

3. Cập nhật Lead

PATCH /api/agent/leads/:id

Scope: leads:write

Request Body:

{
  "status": "contacted",
  "priority": "high",
  "note": "Đã gọi, khách đồng ý hẹn thứ 5"
}

Field	Type	Bắt buộc	Mô tả
status	string	❌*	Trạng thái mới
priority	string	❌*	low, normal, high
note	string	❌*	Ghi chú cập nhật

*Ít nhất một field là bắt buộc.

Trạng thái hợp lệ:

new → contacted → appointment_set → showed_up → qualified → converted
                                  → no_show → reschedule
                                                         → lost

Response 200:

{ "ok": true, "lead_id": "uuid", "status": "contacted" }

Ghi chú

Webhook lead.updated được fire tự động khi cập nhật thành công. Activity log cũng được ghi tự động.

---

4. Ghi nhận Cuộc gọi

POST /api/agent/calls/log

Scope: calls:write

Request Body:

{
  "lead_id": "uuid",
  "outcome": "answered",
  "duration_seconds": 120,
  "note": "Khách đồng ý hẹn thứ 5",
  "sub_outcome": "appointment_set"
}

Field	Type	Bắt buộc	Mô tả
lead_id	uuid	❌*	UUID của lead
booking_id	uuid	❌*	UUID của booking (thay thế lead_id)
outcome	string	✅	answered, no_answer, busy, voicemail, rejected
duration_seconds	number	❌	Thời lượng cuộc gọi (giây)
note	string	❌	Ghi chú cuộc gọi
sub_outcome	string	❌	Kết quả phụ
reject_reason	string	❌	Lý do từ chối (nếu outcome=rejected)

*Ít nhất lead_id hoặc booking_id là bắt buộc.

Response 201:

{ "ok": true, "call_id": "uuid" }

Mẹo

Nếu outcome = "answered" và lead đang ở status new, hệ thống tự động chuyển status thành contacted. Webhook call.completed được fire.

---

5. Lịch hẹn hôm nay

GET /api/agent/bookings/today

Scope: bookings:read

Response 200:

{
  "bookings": [
    {
      "id": "uuid",
      "status": "pending",
      "service": "Massage Trị Liệu",
      "date": "2026-03-17",
      "time_slot": "09:00",
      "note": "Lần đầu",
      "phone": "0901234567",
      "name": "Nguyễn Văn A",
      "email": null
    }
  ],
  "stats": {
    "total": 8,
    "pending": 3,
    "confirmed": 5,
    "arrived": 0,
    "completed": 0,
    "cancelled": 0
  }
}

---

6. Gửi/Log tin nhắn

POST /api/agent/messages/send

Scope: messages:write

Request Body:

{
  "lead_id": "uuid",
  "channel": "zalo",
  "message_text": "Xin chào anh A, em nhắc lịch hẹn ngày mai nhé ạ!",
  "template_name": "booking_reminder"
}

Field	Type	Bắt buộc	Mô tả
lead_id	uuid	❌*	UUID của lead
customer_id	uuid	❌*	UUID của customer (thay thế lead_id)
channel	string	✅	zalo, whatsapp, sms, telegram
message_text	string	❌	Nội dung tin nhắn
template_name	string	❌	Tên template nếu dùng mẫu

*Ít nhất lead_id hoặc customer_id là bắt buộc.

Response 200:

{ "ok": true, "logged": true }

Ghi chú

Endpoint này ghi nhận việc gửi tin nhắn vào activity log. Việc gửi tin thực tế do agent platform (OpenFang/OpenClaw) xử lý qua channel adapters.

---

7. Phân tích dữ liệu (Analytics)

GET /api/agent/analytics

Scope: analytics:read

Response 200:

{
  "pipeline": {
    "new": 12,
    "contacted": 8,
    "appointment_set": 5,
    "showed_up": 3,
    "converted": 15,
    "lost": 7
  },
  "today": {
    "new_leads": 3,
    "bookings": { "total": 8, "pending": 3, "confirmed": 5 }
  },
  "hot_leads": [
    {
      "id": "uuid",
      "phone": "0901234567",
      "name": "Nguyễn Văn A",
      "status": "new",
      "priority": "high",
      "source": "facebook",
      "service_interest": "Massage",
      "created_at": "2026-03-17T..."
    }
  ],
  "conversion_30d": {
    "converted": 15,
    "total": 50,
    "rate": "30.0%"
  }
}

Field	Mô tả
pipeline	Số lượng leads theo từng status
today.new_leads	Leads mới tạo hôm nay
today.bookings	Tổng hợp bookings hôm nay
hot_leads	Top 10 leads ưu tiên cao (status new/contacted, priority high)
conversion_30d	Tỷ lệ chuyển đổi 30 ngày gần nhất

---

Error Codes

Status	Ý nghĩa
200	Thành công
201	Tạo mới thành công
400	Request không hợp lệ (thiếu field, sai format)
401	Agent token thiếu hoặc không hợp lệ
403	Token thiếu scope cần thiết
404	Không tìm thấy (lead, booking)
429	Rate limit exceeded — thử lại sau
500	Database error

Error Response Format:

{ "error": "Mô tả lỗi cụ thể" }

---

MCP Tools Mapping

Mỗi Agent API endpoint được expose qua MCP Server dưới dạng tool:

MCP Tool	Endpoint	Mô tả
crm_create_lead	POST /api/agent/leads	Tạo lead mới
crm_search	GET /api/agent/leads/search	Tìm kiếm leads
crm_update_lead	PATCH /api/agent/leads/:id	Cập nhật lead
crm_log_call	POST /api/agent/calls/log	Ghi nhận cuộc gọi
crm_get_bookings	GET /api/agent/bookings/today	Bookings hôm nay
crm_send_message	POST /api/agent/messages/send	Gửi/log tin nhắn
crm_get_analytics	GET /api/agent/analytics	Analytics

Xem chi tiết: MCP Server docs