Chiến dịch (Campaigns)

Nhóm endpoint quản trị chiến dịch outbound: tạo mới, điều khiển vòng đời (launch/pause/resume/archive/clone), thống kê hiệu suất + chuỗi thời gian, và quản lý đội ngũ agent gán vào từng chiến dịch. Vòng đời từng cuộc gọi (initiate / status / hangup / disposition) cũng được mô tả ở cuối trang để tiện đối tác tích hợp.

3.1 Tạo chiến dịch

POST /api/telesales/campaigns

Request body fields

Field	Type	Required	Mô tả	Giá trị hợp lệ
name	string	✅	Tên chiến dịch, unique trong tài khoản	max 150 ký tự
description	string	optional	Mô tả ngắn	max 500 ký tự
dialer_mode	string	✅	Chế độ quay số	manual / preview / progressive / predictive
caller_id_group_id	integer	✅	ID nhóm xoay vòng caller-ID (xem §Caller-ID rotation groups)	Phải tồn tại + status=active
script_id	integer	optional	ID kịch bản hội thoại gán cho chiến dịch	Phải tồn tại
ring_timeout_sec	integer	optional	Thời gian đổ chuông tối đa (giây)	5-120 (default 25)
preview_window_sec	integer	optional	Thời gian agent xem trước lead khi dialer_mode=preview	0-60 (default 10)
priority	integer	optional	Mức ưu tiên — số càng lớn càng ưu tiên	0-1000 (default 100)
max_attempts	integer	optional	Số lần thử lại tối đa cho 1 lead	1-20 (default 5)
pdpl_enforce	bool	optional	Bật khung giờ pháp lý (PDPL/TCPA)	true / false (default true)
abandon_rate_limit_pct	float	optional	Ngưỡng abandon rate tối đa (% — predictive mode)	0.0-10.0 (default 3.0)
time_window	object	optional	Khung giờ gọi cho phép theo từng ngày trong tuần	Key: mon/tue/wed/thu/fri/sat/sun → mảng {from,to} HH:MM

Giá trị dialer_mode:

• manual — agent tự bấm số gọi từng cuộc.
• preview — hệ thống đẩy lead cho agent xem trước rồi mới quay số.
• progressive — hệ thống tự quay số khi có agent rảnh.
• predictive — hệ thống quay số trước cả khi agent rảnh (giới hạn tuân thủ qua abandon_rate_limit_pct).

Body:

{
  "name": "Outbound Sales Q3-2026",
  "description": "Q3 outbound campaign",
  "dialer_mode": "progressive",
  "caller_id_group_id": 3,
  "script_id": 12,
  "ring_timeout_sec": 25,
  "preview_window_sec": 10,
  "priority": 100,
  "max_attempts": 5,
  "pdpl_enforce": true,
  "abandon_rate_limit_pct": 3.0,
  "time_window": {
    "mon": [{"from": "08:00", "to": "17:30"}],
    "tue": [{"from": "08:00", "to": "17:30"}],
    "wed": [{"from": "08:00", "to": "17:30"}],
    "thu": [{"from": "08:00", "to": "17:30"}],
    "fri": [{"from": "08:00", "to": "17:30"}],
    "sat": [{"from": "08:00", "to": "12:00"}]
  }
}

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
id	integer	ID chiến dịch
name	string	Tên chiến dịch
description	string|null	Mô tả ngắn
status	string	Trạng thái vòng đời	draft / active / paused / archived
dialer_mode	string	Chế độ quay số	manual / preview / progressive / predictive
caller_id_group_id	integer	ID nhóm caller-ID rotation
script_id	integer|null	ID script
ring_timeout_sec	integer	Thời gian đổ chuông tối đa	5-120
preview_window_sec	integer	Cửa sổ preview	0-60
priority	integer	Mức ưu tiên	0-1000
max_attempts	integer	Số lần thử lại tối đa	1-20
pdpl_enforce	bool	Bật khung giờ PDPL
abandon_rate_limit_pct	float	Ngưỡng abandon rate (predictive)	0.0-10.0
time_window	object	Khung giờ gọi theo ngày
total_leads	integer	Số lead đã import vào chiến dịch
created_by	integer	ID user tạo chiến dịch
created_at	datetime	Thời điểm tạo (ISO 8601 UTC)
updated_at	datetime	Thời điểm cập nhật cuối

Response 201:

{
  "data": {
    "id": 36,
    "name": "Outbound Sales Q3-2026",
    "description": "Q3 outbound campaign",
    "status": "draft",
    "dialer_mode": "progressive",
    "caller_id_group_id": 3,
    "script_id": 12,
    "ring_timeout_sec": 25,
    "preview_window_sec": 10,
    "priority": 100,
    "max_attempts": 5,
    "pdpl_enforce": true,
    "abandon_rate_limit_pct": 3.0,
    "time_window": { "mon": [{"from":"08:00","to":"17:30"}], "...": "..." },
    "total_leads": 0,
    "created_by": 7,
    "created_at": "2026-06-06T06:00:00Z",
    "updated_at": "2026-06-06T06:00:00Z"
  }
}

Response 422 (validate sai):

{
  "message": "The given data was invalid.",
  "errors": {
    "dialer_mode": ["The selected dialer mode is invalid."],
    "caller_id_group_id": ["The selected caller id group id is invalid."]
  }
}

3.2 Điều khiển vòng đời chiến dịch

Endpoint	Hành động	Response
POST /api/telesales/campaigns/{id}/launch	draft → active	{ "data": { "id":36, "status":"active", "launched_at":"...Z" } }
POST /api/telesales/campaigns/{id}/pause	active → paused	{ "data": { "id":36, "status":"paused" } }
POST /api/telesales/campaigns/{id}/resume	paused → active	{ "data": { "id":36, "status":"active" } }
POST /api/telesales/campaigns/{id}/archive	→ archived	{ "data": { "id":36, "status":"archived" } }
POST /api/telesales/campaigns/{id}/clone	→ bản draft mới	{ "data": { "id":42, "status":"draft", "name":"... (clone)" } }
PUT /api/telesales/campaigns/{id}	Cập nhật field	trả về toàn bộ object chiến dịch
DELETE /api/telesales/campaigns/{id}	Xoá mềm	204 No Content

3.3 Danh sách / chi tiết / thống kê

GET /api/telesales/campaigns — danh sách

Query parameters

Field	Type	Required	Mô tả	Giá trị hợp lệ
status	string	optional	Lọc theo trạng thái vòng đời	draft / active / paused / archived
dialer_mode	string	optional	Lọc theo chế độ quay số	manual / preview / progressive / predictive
q	string	optional	Tìm theo name (LIKE %keyword%)
page	integer	optional	Số trang	≥ 1 (default 1)
per_page	integer	optional	Bản ghi mỗi trang	1-200 (default 50)

Response fields (mỗi item trong data[])

Field	Type	Mô tả	Giá trị hợp lệ
id	integer	ID chiến dịch
name	string	Tên chiến dịch
status	string	Trạng thái vòng đời	draft / active / paused / archived
dialer_mode	string	Chế độ quay số	manual / preview / progressive / predictive
total_leads	integer	Tổng số lead đã import
dialled	integer	Số lần đã quay số
answered	integer	Số cuộc bắt máy
converted	integer	Số cuộc chuyển đổi thành công
asr_pct	float	Answer-Seizure Ratio (%) = answered/dialled*100	0-100

Response 200:

{
  "data": [
    { "id": 36, "name": "Outbound Sales Q3-2026", "status": "active",
      "dialer_mode": "progressive", "total_leads": 487, "dialled": 312,
      "answered": 198, "converted": 47, "asr_pct": 63.5 }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }
}

GET /api/telesales/campaigns/{id}/stats — thống kê tổng hợp

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
dialled	integer	Tổng số lần quay số
answered	integer	Tổng số cuộc bắt máy
talked_over_30s	integer	Số cuộc có billsec ≥ 30
converted	integer	Số cuộc chuyển đổi (disposition is_final=true + outcome thành công)
answer_rate_pct	float	answered/dialled*100	0-100
conversion_rate_pct	float	converted/answered*100	0-100
asr_pct	float	Answer-Seizure Ratio (%)	0-100
aht_seconds	integer	Average Handle Time (giây) — trung bình thời gian xử lý mỗi cuộc
abandon_rate_pct	float	Tỷ lệ abandoned (% — chỉ tính trong predictive mode)	0-100
callbacks_pending	integer	Số callback đang chờ thực hiện

Response 200:

{
  "data": {
    "dialled": 312,
    "answered": 198,
    "talked_over_30s": 142,
    "converted": 47,
    "answer_rate_pct": 63.46,
    "conversion_rate_pct": 15.06,
    "asr_pct": 63.46,
    "aht_seconds": 184,
    "abandon_rate_pct": 1.8,
    "callbacks_pending": 23
  }
}

GET /api/telesales/campaigns/{id}/timeseries — chuỗi thời gian

Query parameters

Field	Type	Required	Mô tả	Giá trị hợp lệ
group_by	string	optional	Đơn vị group	hour / day / week (default day)
date_from	datetime	optional	Mốc bắt đầu (UTC ISO 8601)
date_to	datetime	optional	Mốc kết thúc (UTC ISO 8601)

Response fields (mỗi item trong data[])

Field	Type	Mô tả	Giá trị hợp lệ
bucket	string	Mốc thời gian — định dạng theo group_by	YYYY-MM-DD / YYYY-Www / YYYY-MM-DD HH:00:00
dialled	integer	Số lần quay số trong bucket
answered	integer	Số cuộc bắt máy trong bucket
converted	integer	Số cuộc chuyển đổi trong bucket

Response 200:

{
  "data": [
    { "bucket": "2026-06-01", "dialled": 80, "answered": 51, "converted": 12 },
    { "bucket": "2026-06-02", "dialled": 92, "answered": 60, "converted": 15 },
    { "bucket": "2026-06-03", "dialled": 75, "answered": 47, "converted":  9 }
  ],
  "meta": { "range": "7d" }
}

3.4 Quản lý agent của chiến dịch

Endpoint	Mục đích
GET /api/telesales/campaigns/{id}/agents	Danh sách agent đang gán vào chiến dịch
GET /api/telesales/campaigns/{id}/agents/available	Danh sách user đủ điều kiện gán (chưa thuộc chiến dịch khác xung đột, có role phù hợp)
POST /api/telesales/campaigns/{id}/agents	Gán một agent vào chiến dịch
PATCH /api/telesales/campaigns/{id}/agents/{userId}	Cập nhật role hoặc trạng thái của agent
DELETE /api/telesales/campaigns/{id}/agents/{userId}	Gỡ agent khỏi chiến dịch

GET /api/telesales/agents — danh sách agent của khách hàng

Đối tác tích hợp dùng để chọn user_id cho POST /api/telesales/campaigns/{id}/agents:

GET /api/telesales/agents?per_page=50&page=1

Query parameters

Field	Type	Required	Mô tả	Giá trị hợp lệ
q	string	optional	Tìm theo name / username / email (LIKE %keyword%)
role	string	optional	Lọc theo role	agent / supervisor / manager / ...
team_id	integer	optional	Lọc theo team
page	integer	optional	Số trang	≥ 1 (default 1)
per_page	integer	optional	Bản ghi mỗi trang	1-200 (default 50)

Response fields (mỗi item trong data[])

Field	Type	Mô tả	Giá trị hợp lệ
id	integer	User ID
name	string	Họ tên
username	string	Tên đăng nhập
email	string	Email
role	string	Vai trò trong hệ thống	agent / supervisor / manager
team_id	integer|null	ID team đang thuộc
extension	string|null	Số máy nhánh SIP đã gán
is_active	bool	User còn hoạt động không	true / false

Response 200:

{
  "data": [
    {
      "id": 25,
      "name": "Nguyen Van A",
      "username": "nguyenvana",
      "email": "nguyenvana@company.com",
      "role": "agent",
      "team_id": 3,
      "extension": "1001",
      "is_active": true
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 142 }
}

Chỉ trả về user có is_active=true, sắp xếp theo name.

Workflow gán agent vào chiến dịch:

# Bước 1: lấy danh sách agent có sẵn
GET /api/telesales/agents?role=agent

# Bước 2: gán user_id=25 vào chiến dịch
POST /api/telesales/campaigns/36/agents
{ "user_id": 25, "role": "agent" }

GET /api/telesales/campaigns/{id}/agents

Response fields (mỗi item trong data[])

Field	Type	Mô tả	Giá trị hợp lệ
user_id	integer	ID user agent
username	string	Tên đăng nhập
display_name	string	Tên hiển thị
campaign_id	integer	ID chiến dịch
role	string	Vai trò trong chiến dịch	agent / supervisor
extension	string|null	Số máy nhánh SIP
team_id	integer|null	ID team
team_name	string|null	Tên team
is_active	bool	User còn hoạt động không	true / false
assigned_at	datetime	Thời điểm gán vào chiến dịch (ISO 8601 UTC)

Response 200:

{
  "data": [
    {
      "user_id": 25,
      "username": "agent01",
      "display_name": "Nguyen Van A",
      "campaign_id": 36,
      "role": "agent",
      "extension": "2001",
      "team_id": 3,
      "team_name": "Sales A",
      "is_active": true,
      "assigned_at": "2026-06-06T06:10:00Z"
    }
  ]
}

GET /api/telesales/campaigns/{id}/agents/available

Response fields (mỗi item trong data[])

Field	Type	Mô tả	Giá trị hợp lệ
user_id	integer	ID user agent có thể gán
username	string	Tên đăng nhập
display_name	string	Tên hiển thị
extension	string|null	Số máy nhánh SIP
team_id	integer|null	ID team
team_name	string|null	Tên team
role	string	Vai trò hệ thống	agent / supervisor
is_active	bool	User còn hoạt động không	true / false

Response 200:

{
  "data": [
    {
      "user_id": 30,
      "username": "agent06",
      "display_name": "Tran Thi B",
      "extension": "2006",
      "team_id": 3,
      "team_name": "Sales A",
      "role": "agent",
      "is_active": true
    }
  ]
}

POST /api/telesales/campaigns/{id}/agents — gán agent

Request body fields

Field	Type	Required	Mô tả	Giá trị hợp lệ
user_id	integer	✅	ID user cần gán	Phải tồn tại + is_active=true + có extension SIP
role	string	optional	Vai trò trong chiến dịch	agent (default) / supervisor

Body:

{ "user_id": 25, "role": "agent" }

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
user_id	integer	ID user vừa gán
campaign_id	integer	ID chiến dịch
role	string	Vai trò trong chiến dịch	agent / supervisor
assigned_at	datetime	Thời điểm gán (ISO 8601 UTC)

Response 201:

{
  "data": {
    "user_id": 25,
    "campaign_id": 36,
    "role": "agent",
    "assigned_at": "2026-06-06T06:10:00Z"
  }
}

Response 422 — các trường hợp validate / xung đột:

// User không tồn tại hoặc đã ngừng hoạt động
{
  "message": "The given data was invalid.",
  "errors": { "user_id": ["The selected user id is invalid."] }
}

// User đã được gán vào chiến dịch khác (mỗi user chỉ thuộc 1 chiến dịch tại 1 thời điểm)
{
  "message": "Agent is already attached to another active campaign.",
  "errors": { "user_id": ["User 25 already assigned to campaign 38."] }
}

// User chưa được cấp extension SIP (không thể nhận cuộc gọi)
{
  "message": "User has no SIP extension assigned — cannot be assigned as an agent.",
  "errors": { "user_id": ["User 25 has no extension assigned."] }
}

// Role không hợp lệ (chỉ chấp nhận agent / supervisor)
{
  "message": "The given data was invalid.",
  "errors": { "role": ["The selected role is invalid."] }
}

PATCH /api/telesales/campaigns/{id}/agents/{userId} — cập nhật role

Request body fields

Field	Type	Required	Mô tả	Giá trị hợp lệ
role	string	✅	Vai trò mới trong chiến dịch	agent / supervisor

Body:

{ "role": "supervisor" }

Response 200:

{ "data": { "user_id": 25, "campaign_id": 36, "role": "supervisor", "assigned_at": "2026-06-06T06:10:00Z" } }

Response 404 — agent chưa được gán vào chiến dịch này:

{ "message": "Agent is not attached to this campaign." }

DELETE /api/telesales/campaigns/{id}/agents/{userId}

Response 204 No Content (thành công).

Response 422 — agent đang ở trên cuộc gọi:

{
  "message": "Cannot unassign an agent who is currently on a call.",
  "errors": { "user_id": ["Agent 25 is currently on call UUID xxx — wait for it to end or force-hangup first."] }
}

Lưu ý

Sau khi DELETE thành công, agent sẽ không nhận thêm cuộc gọi mới từ chiến dịch, nhưng cuộc gọi đang quay sẽ chạy đến lúc kết thúc. Trạng thái presence realtime tự đồng bộ trong vòng 5 giây.

---

7. Vòng đời cuộc gọi (Call Lifecycle)

Một cuộc gọi đi qua 4 bước chính do agent (hoặc hệ thống) khởi tạo trong phạm vi chiến dịch.

Mẹo

Nếu đối tác dùng Webphone SDK, toàn bộ 4 bước được đóng gói trong phone.call(number, options) — không cần gọi trực tiếp các endpoint dưới. Xem tài liệu Webphone SDK.

7.1 Khởi tạo cuộc gọi

POST /api/telesales/calls/initiate

Extension của agent được lấy từ profile của user đã xác thực — không cần truyền tay.

Request body fields

Field	Type	Required	Mô tả	Giá trị hợp lệ
campaign_id	integer	✅	ID chiến dịch agent đang chạy	Phải tồn tại + status=active + agent đã được gán
lead_id	integer	✅	ID lead cần quay số	Phải thuộc campaign_id + status không phải dnc/exhausted/converted

Body:

{
  "campaign_id": 36,
  "lead_id": 78912
}

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
uuid	string	UUID cuộc gọi — dùng cho mọi endpoint con (/status, /hangup, /disposition)	UUID v4
status	string	Trạng thái khởi tạo	originating
caller_id_used	string	Số gọi ra (caller-ID) được nhóm rotation chọn	E.164
lead_id	integer	ID lead
campaign_id	integer	ID chiến dịch

Response 200:

{
  "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
  "status": "originating",
  "caller_id_used": "0900000010",
  "lead_id": 78912,
  "campaign_id": 36
}

Response 422 (vi phạm PDPL window):

{
  "error": "pdpl_blocked",
  "message": "Outside the campaign calling window (08:00-17:30, Mon-Sat).",
  "next_eligible_at": "2026-06-07T01:00:00Z"
}

Response 422 (các lý do khác):

{
  "error": "lead_dnc",
  "message": "Lead phone is on the DNC list."
}

Các mã lỗi khác: lead_blocked, no_caller_id_available, max_attempts_reached.

7.2 Theo dõi trạng thái cuộc gọi

GET /api/telesales/calls/{uuid}/status

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
uuid	string	UUID cuộc gọi	UUID v4
state	string	Trạng thái hiện tại	originating / ringing / answered / wrap_up / closed
start_time	datetime	Thời điểm khởi tạo (ISO 8601 UTC)
answer_time	datetime|null	Thời điểm khách bắt máy	null nếu chưa bắt máy
end_time	datetime|null	Thời điểm kết thúc	null nếu chưa kết thúc
duration	integer|null	Tổng thời gian từ originate đến hangup (giây)
billsec	integer|null	Thời gian đàm thoại (giây) — từ answer_time đến end_time
result	string|null	Kết quả cuối — mapping từ hangup cause	answered / no_answer / busy / failed / cancelled
hangup_cause	string|null	Lý do hangup từ Zorio PBX	vd NORMAL_CLEARING / USER_BUSY
caller_id_used	string	Số gọi ra	E.164
agent_extension	string	Số máy nhánh của agent
destination_number	string	Số điện thoại đích (lead)

7.3 Cúp máy thủ công

POST /api/telesales/calls/{uuid}/hangup

Request body fields

Field	Type	Required	Mô tả	Giá trị hợp lệ
cause	string	optional	Lý do hangup tự đặt — lưu vào CDR để báo cáo	free text max 64 ký tự (default MANUAL_HANGUP)

Body (tuỳ chọn):

{ "cause": "MANUAL_HANGUP" }

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
uuid	string	UUID cuộc gọi	UUID v4
state	string	Trạng thái sau hangup	wrap_up (sang chờ agent disposition)
end_time	datetime	Thời điểm hangup (ISO 8601 UTC)
duration	integer	Tổng thời gian cuộc gọi (giây)
billsec	integer	Thời gian đàm thoại (giây)
hangup_cause	string	Lý do hangup (echo từ request hoặc tự sinh)

Response 200:

{
  "data": {
    "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
    "state": "wrap_up",
    "end_time": "2026-06-06T06:35:42Z",
    "duration": 222,
    "billsec": 213,
    "hangup_cause": "MANUAL_HANGUP"
  }
}

Response 404 — UUID không tồn tại hoặc không thuộc tài khoản:

{ "message": "Call not found." }

Response 422 — cuộc gọi đã kết thúc:

{
  "message": "Call has already ended, hangup is not possible.",
  "errors": { "uuid": ["Call already in state 'closed' since 2026-06-06T06:34:00Z."] }
}

Response 403 — agent thường cố cúp máy cuộc gọi của người khác mà chưa có quyền supervisor:

{ "message": "You are not allowed to hang up this call. Supervisor role is required to force hangup." }

7.4 Gửi kết quả cuộc gọi (Disposition)

POST /api/telesales/calls/{uuid}/disposition

Request body fields

Field	Type	Required	Mô tả	Giá trị hợp lệ
disposition_id	integer	✅	ID disposition (map từ code, vd SALE-OK)	Phải tồn tại + is_active=true
note	string	optional	Ghi chú text của agent	max 1000 ký tự
callback_at	datetime	optional	Lịch gọi lại (ISO 8601 UTC) — chỉ dùng khi disposition có trigger_callback=true	Phải lớn hơn thời điểm hiện tại
callback_agent_id	integer	optional	Sticky agent cho cuộc callback	User ID phải là agent của chiến dịch

Body:

{
  "disposition_id": 5,
  "note": "Customer committed, follow-up email scheduled",
  "callback_at": null,
  "callback_agent_id": null
}

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
uuid	string	UUID cuộc gọi	UUID v4
state	string	Trạng thái sau khi gửi disposition	closed
disposition	object	Chi tiết disposition vừa áp	{id, code, label, category}
disposition.id	integer	ID disposition
disposition.code	string	Code immutable (vd SALE-OK)
disposition.label	string	Nhãn hiển thị
disposition.category	string	Phân loại	contact / no_contact / callback / remove
lead_id	integer	ID lead
lead_status_after	string	Trạng thái lead sau khi áp disposition	pending / contacted / converted / dnc / exhausted
callback_scheduled	object|null	Thông tin callback (nếu có)	{callback_at, agent_id} hoặc null

Response 200:

{
  "data": {
    "uuid": "093e1024-82c6-49b3-8775-99edeb221898",
    "state": "closed",
    "disposition": { "id": 5, "code": "SALE-OK", "label": "Sale Success", "category": "contact" },
    "lead_id": 78912,
    "lead_status_after": "converted",
    "callback_scheduled": null
  }
}

Các trường outcome theo ngành nghề

Các trường outcome chuyên biệt (Payment Method, Appointment Date, Survey Result, Lead Score, Notes, ...) được khai báo qua custom field ở từng disposition do admin của khách hàng cấu hình. Schema chi tiết cho từng ngành (chăm sóc khách hàng, lịch hẹn dịch vụ, khảo sát mức độ hài lòng, ...) nằm trong gói cấu hình riêng riêng cho khách hàng.