🤖 Agent API Reference

Base URL: https://salehay.comAuth: X-Agent-Token: sk_live_xxx · Rate: 100 req/phút · Format: JSON

Xem thêm: Cài đặt Agent · MCP Server · Webhooks

Xác thực

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

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

Tạo token tại: salehay.com/app → Cài đặt → API Keys

Scopes

Scope	Quyền	Endpoints
leads:read	Tìm kiếm leads	Search
leads:write	Tạo, cập nhật leads	Create, Update
calls:write	Ghi nhận cuộc gọi	Log Call
messages:write	Gửi/log tin nhắn	Send Message
bookings:read	Xem lịch hẹn	Get Bookings
analytics:read	Xem analytics	Get Analytics
*	Toàn quyền	Tất cả

---

1. Tạo Lead

POST /api/agent/leads

Scope: leads:write · Tự tạo Customer nếu phone chưa có · Fire webhook lead.created

curl -X POST https://salehay.com/api/agent/leads \
  -H "X-Agent-Token: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0901234567",
    "name": "Nguyễn Văn A",
    "email": "a@gmail.com",
    "source": "agent",
    "service_interest": "Gói khám tổng quát",
    "note": "Quan tâm gói cao cấp",
    "priority": "high"
  }'

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

Response 201:

{
  "ok": true,
  "lead_id": "6d1a8403-bfec-49ae-8c1a-10f6c7a64df3",
  "customer_id": "b2da69ae-5c1b-44b3-946f-dce3ebe97293",
  "status": "new"
}

---

2. Tìm kiếm Lead

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

Scope: leads:read · Cần ít nhất q hoặc status

Param	Type	Bắt buộc	Mô tả
q	string	❌*	SĐT hoặc tên (ILIKE)
status	string	❌*	new · contacted · appointment_set · qualified · converted · lost
limit	number		Max kết quả (mặc định 20, tối đa 50)

Response 200:

{
  "leads": [
    {
      "id": "uuid", "status": "new", "priority": "high",
      "phone": "0901234567", "name": "Nguyễn Văn A",
      "source": "agent", "service_interest": "Gói khám",
      "created_at": "2026-03-17T..."
    }
  ],
  "total": 1
}

---

3. Cập nhật Lead

PATCH /api/agent/leads/:id

Scope: leads:write · Auto-log activity · Fire webhook lead.updated

curl -X PATCH https://salehay.com/api/agent/leads/UUID \
  -H "X-Agent-Token: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "contacted", "note": "Đã gọi, khách quan tâm" }'

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ú

Ít nhất 1 field bắt buộc

Luồng trạng thái:

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

---

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

POST /api/agent/calls/log

Scope: calls:write · Nếu outcome=answered + lead status new → tự chuyển contacted

curl -X POST https://salehay.com/api/agent/calls/log \
  -H "X-Agent-Token: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "uuid",
    "outcome": "answered",
    "duration_seconds": 180,
    "note": "Khách đồng ý hẹn khám"
  }'

Field	Type	Bắt buộc	Mô tả
lead_id	uuid	❌*	Lead UUID
booking_id	uuid	❌*	Booking UUID (thay lead_id)
outcome	string	✅	answered · no_answer · busy · voicemail · rejected
duration_seconds	number		Thời lượng (giây)
note	string		Ghi chú

Ít nhất lead_id hoặc booking_id bắt buộc

---

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

GET /api/agent/bookings/today

Scope: bookings:read · Không cần params

Response 200:

{
  "bookings": [
    { "id": "uuid", "status": "pending", "service": "Gói khám",
      "date": "2026-03-17", "time_slot": "09:00",
      "phone": "0901234567", "name": "Nguyễn Văn A" }
  ],
  "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 · Ghi vào activity log (không gửi tin thực tế)

curl -X POST https://salehay.com/api/agent/messages/send \
  -H "X-Agent-Token: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "uuid",
    "channel": "zalo",
    "message_text": "Xin chào, nhắc lịch hẹn ngày mai 9h ạ!"
  }'

Field	Type	Bắt buộc	Mô tả
lead_id	uuid	❌*	Lead UUID
customer_id	uuid	❌*	Customer UUID
channel	string	✅	zalo · sms · whatsapp · telegram
message_text	string		Nội dung
template_name	string		Tên template

---

7. Analytics

GET /api/agent/analytics

Scope: analytics:read · Không cần params

Response 200:

{
  "pipeline": { "new": 12, "contacted": 8, "appointment_set": 5, "converted": 15 },
  "today": { "new_leads": 3, "bookings": { "total": 8, "pending": 3, "confirmed": 5 } },
  "hot_leads": [{ "id": "uuid", "phone": "0901234567", "name": "A", "priority": "high" }],
  "conversion_30d": { "converted": 15, "total": 50, "rate": "30.0%" }
}

---

Error Codes

Status	Ý nghĩa
200	OK
201	Tạo mới OK
400	Thiếu field / sai format
401	Token thiếu hoặc sai
403	Token thiếu scope
404	Lead/Booking không tìm thấy
429	Quá rate limit

MCP Tools Mapping

MCP Tool	HTTP Endpoint
crm_create_lead	POST /api/agent/leads
crm_search	GET /api/agent/leads/search
crm_update_lead	PATCH /api/agent/leads/:id
crm_log_call	POST /api/agent/calls/log
crm_get_bookings	GET /api/agent/bookings/today
crm_send_message	POST /api/agent/messages/send
crm_get_analytics	GET /api/agent/analytics