Bộ dữ liệu Telesales (Datasets)
Bộ dữ liệu (Dataset) là đơn vị cấu hình schema cho một chiến dịch Telesales — chứa:
- Trường tuỳ chỉnh cho lead (
phase=lead) — dữ liệu nhập trước khi gọi (VD số hợp đồng, sản phẩm, giá trị đơn hàng) - Trường tuỳ chỉnh cho cuộc gọi (
phase=attempt) — kết quả agent điền lúc wrap-up (VD ngày cam kết, phương thức thanh toán, ghi chú) - Danh sách mã kết quả (dispositions) áp dụng cho chiến dịch dùng bộ dữ liệu này
- Hiển thị conditional — field chỉ hiện khi mã kết quả nằm trong danh sách
disposition_in(VD "Ngày cam kết" chỉ hiện khi disposition = "Promise-to-Pay")
Từ 14/08/2026, mọi chiến dịch mới bắt buộc gắn với 1 bộ dữ liệu. Chiến dịch cũ được ánh xạ tự động sang bộ dữ liệu mặc định của tenant. API /api/custom-fields cho 2 entity TelesalesLead + TelesalesCallAttempt đã ngừng phục vụ (410 Gone) — xem trang Custom Fields để biết chi tiết.
Quyền truy cập
| Endpoint | Quyền yêu cầu |
|---|---|
GET (đọc) | Module telesales cấp viewer trở lên |
POST/PUT/DELETE (ghi) | Permission manage_telesales_dataset (tier admin) |
POST /api/v1/telesales/datasets/{code}/leads (push lead) | Sanctum PAT với ability telesales:push |
Cấu trúc bộ dữ liệu
Mỗi bộ dữ liệu có cấu trúc:
| Trường | Kiểu | Mô tả |
|---|---|---|
id | integer | Auto-increment |
code | string | Unique per tenant, dùng trong URL push lead |
name | string | Tên hiển thị (VD "FinanceCorp Life Insurance — Renewal") |
description | string | Mô tả ngắn |
industry_tag | string | null | Enum tuỳ chọn: insurance, finance, tourism, healthcare, realestate, survey, other |
is_default | boolean | 1 bộ mặc định per tenant (auto-select trong wizard tạo chiến dịch) |
is_active | boolean | false = ẩn khỏi list, không dùng được cho chiến dịch mới |
fields[] | array | Danh sách trường tuỳ chỉnh (chi tiết dưới) |
dispositions[] | array | Danh sách mã kết quả áp dụng (N-N link với telesales_dispositions) |
field_count | integer | Cache count |
disposition_count | integer | Cache count |
Mỗi trường (field) có cấu trúc:
| Trường | Kiểu | Mô tả |
|---|---|---|
id | integer | |
field_code | string | Unique per dataset, snake_case (VD policy_number) |
label | string | Nhãn hiển thị |
type | string | Enum: text, textarea, number, date, datetime, select, multiselect, phone, email, boolean |
required | boolean | Bắt buộc khi push lead / submit disposition |
options | array | null | Cho type select/multiselect: [{value, label}, ...] |
visible_when | object | null | Điều kiện hiển thị, VD {"disposition_in": ["RN-02", "RI-02"]} |
phase | string | lead hoặc attempt |
help_text | string | null | Gợi ý hiển thị dưới input |
display_order | integer | Thứ tự trong form |
GET /api/telesales/datasets — Danh sách bộ dữ liệu
Trả về tất cả bộ dữ liệu của tenant.
GET /api/telesales/datasets
Authorization: Bearer <api_token>
Accept: application/jsonQuery params:
| Param | Mô tả |
|---|---|
is_active | true (mặc định) chỉ trả bộ active. false để bao gồm bộ đã lưu trữ. |
industry_tag | Filter theo ngành (VD insurance) |
Response 200 — trả danh sách bộ dữ liệu kèm mảng fields[] nested:
{
"data": [
{
"id": 5,
"tenant_id": 1,
"code": "sample_life_renewal",
"name": "FinanceCorp Life Insurance — Renewal",
"description": "Chiến dịch nhắc phí + tái tục hợp đồng bảo hiểm",
"industry_tag": "insurance",
"template_source_id": 2,
"layout": null,
"is_active": true,
"is_default": true,
"created_at": "2026-08-14T10:00:00+00:00",
"updated_at": "2026-08-14T10:00:00+00:00",
"fields": [
{
"id": 101,
"dataset_id": 5,
"field_code": "full_name",
"label": "Họ tên",
"type": "text",
"required": true,
"options": null,
"help_text": null,
"phase": "lead",
"display_order": 10,
"is_active": true,
"visible_when": null
}
]
}
]
}Lưu ý:
dispositions[]không trả kèm trong endpoint list — dùngGET /api/telesales/datasets/{id}/dispositionsđể lấy riêng.
GET /api/telesales/datasets/{id} — Chi tiết bộ dữ liệu
Trả về full metadata + fields + dispositions.
GET /api/telesales/datasets/5
Authorization: Bearer <api_token>Response 200:
{
"data": {
"id": 5,
"code": "sample_life_renewal",
"name": "FinanceCorp Life Insurance — Renewal",
"description": "...",
"industry_tag": "insurance",
"is_default": true,
"is_active": true,
"fields": [
{
"id": 101,
"field_code": "full_name",
"label": "Họ tên",
"type": "text",
"required": true,
"phase": "lead",
"display_order": 10
},
{
"id": 102,
"field_code": "policy_number",
"label": "Số hợp đồng",
"type": "text",
"required": true,
"phase": "lead",
"help_text": "Định dạng POL-YYYY-NNNN",
"display_order": 20
},
{
"id": 103,
"field_code": "annual_premium",
"label": "Phí bảo hiểm hàng năm",
"type": "number",
"required": false,
"phase": "lead",
"display_order": 30
},
{
"id": 201,
"field_code": "commitment_date",
"label": "Ngày cam kết thanh toán",
"type": "date",
"required": true,
"phase": "attempt",
"visible_when": {
"disposition_in": ["RN-02", "RI-02"]
},
"display_order": 10
},
{
"id": 202,
"field_code": "payment_method",
"label": "Phương thức thanh toán",
"type": "select",
"options": [
{ "value": "cash", "label": "Tiền mặt" },
{ "value": "bank", "label": "Chuyển khoản" },
{ "value": "atm", "label": "Thẻ ATM" },
{ "value": "wallet", "label": "Ví điện tử" }
],
"phase": "attempt",
"visible_when": {
"disposition_in": ["RN-01", "RI-01"]
},
"display_order": 20
}
],
"template": {
"id": 2,
"code": "insurance_life",
"name": "Bảo hiểm nhân thọ",
"industry_tag": "insurance",
"description": "Nhắc phí + tái tục hợp đồng bảo hiểm nhân thọ",
"is_system": true,
"tenant_id": null,
"default_fields": [
{ "field_code": "policy_number", "label": "Số hợp đồng", "type": "text", "required": true, "phase": "lead", "display_order": 10 }
],
"created_at": "2026-08-14 14:20:31"
}
}
}Lưu ý: response không trả
dispositions[]embed — dùngGET /api/telesales/datasets/{id}/dispositionsđể lấy riêng danh sách mã kết quả áp dụng.Block
template(nếu có) là preset ngành lúc tạo dataset — chỉ để tham chiếu, không đồng bộ với field hiện tại.
POST /api/telesales/datasets/{id}/fields — Tạo trường mới
POST /api/telesales/datasets/5/fields
Authorization: Bearer <api_token>
Content-Type: application/json
{
"field_code": "policy_number",
"label": "Số hợp đồng",
"type": "text",
"required": true,
"phase": "lead",
"display_order": 20,
"help_text": "Định dạng POL-YYYY-NNNN"
}Response 201 trả về field vừa tạo:
{
"data": {
"id": 102,
"dataset_id": 5,
"field_code": "policy_number",
"label": "Số hợp đồng",
"type": "text",
"required": true,
"phase": "lead",
"display_order": 20
}
}Validation:
field_codephải khớp regex^[a-z][a-z0-9_]{0,63}$và unique trong datasettypephải nằm trong danh sách hỗ trợ- Với type
select/multiselect, bắt buộc cóoptions(array of{value, label}) phasebắt buộcleadhoặcattempt
Error 409 nếu trùng code trong dataset:
{ "error": "field_code_duplicate" }PUT /api/telesales/datasets/{id}/fields/{fid} — Sửa trường
Không cho phép đổi field_code, type, phase sau khi tạo (data đã lưu có thể bị corrupt). Cho phép đổi label, required, options, visible_when, help_text, display_order.
PUT /api/telesales/datasets/5/fields/102
Content-Type: application/json
{
"label": "Mã hợp đồng (Policy No.)",
"required": false,
"help_text": "Có thể để trống nếu chưa có"
}Response 200:
{
"data": {
"id": 102,
"dataset_id": 5,
"field_code": "policy_number",
"label": "Mã hợp đồng (Policy No.)",
"type": "text",
"required": false,
"options": null,
"help_text": "Có thể để trống nếu chưa có",
"phase": "lead",
"display_order": 20,
"is_active": true,
"visible_when": null
}
}DELETE /api/telesales/datasets/{id}/fields/{fid} — Xoá trường
Soft delete: is_active=false. Data đã lưu trong custom_fields JSON của leads/attempts vẫn giữ. Có thể restore bằng PUT ... {"is_active": true}.
POST /api/telesales/datasets/{id}/fields/reorder — Sắp xếp lại thứ tự
POST /api/telesales/datasets/5/fields/reorder
Content-Type: application/json
{
"order": [
{ "id": 101, "display_order": 10 },
{ "id": 102, "display_order": 20 },
{ "id": 103, "display_order": 30 }
]
}Validation: field order (mảng) bắt buộc — chứa mọi field cần sắp xếp. Mỗi phần tử phải có id (int) + display_order (int).
Response 200:
{ "ok": true, "count": 3 }Error 422 nếu có id không thuộc dataset (bảo vệ khỏi gõ nhầm id sang bộ khác):
{
"error": "invalid_field_ids",
"message": "Có field id không thuộc bộ dữ liệu này",
"invalid": [999999]
}Catalog mã kết quả chung của tenant
Ngoài danh sách mã kết quả đã gán riêng cho từng dataset (endpoint phía dưới), tenant có 1 catalog chung chứa tất cả mã kết quả có thể dùng — quản lý qua nhóm endpoint /api/telesales/dispositions.
GET /api/telesales/dispositions — Toàn bộ catalog
GET /api/telesales/dispositions
Authorization: Bearer <api_token>
Accept: application/jsonResponse 200 — array full mã kết quả của tenant, sort theo sort_order rồi code:
{
"data": [
{
"id": 1,
"code": "sale",
"label": "Bán được (Sale)",
"description": null,
"category": "contact",
"is_final": true,
"is_conversion": true,
"trigger_callback": false,
"trigger_dnc": false,
"trigger_ticket": false,
"default_retry_delay_minutes": null,
"color": "#10B981",
"is_system": true,
"sort_order": 10,
"created_at": "2026-05-19T15:36:48+00:00"
}
]
}is_system=true→ mã hệ thống, KHÔNG cho xoá/đổi code (chỉ đổi label/color).category∈contact | callback | no_contact | remove.is_final=true→ sau khi ghi disposition này, lead chuyển sang trạng thái đóng, không tự retry.trigger_*→ hook tự động (mở CB queue / thêm DNC / tạo ticket CSKH).
POST /api/telesales/dispositions — Tạo mã mới
POST /api/telesales/dispositions
Content-Type: application/json
{
"code": "RN-06",
"label": "Renewal · Đề nghị chuyển gói",
"category": "contact",
"is_final": false,
"is_conversion": false,
"trigger_callback": true,
"default_retry_delay_minutes": 1440,
"color": "#F59E0B",
"sort_order": 15
}codephải unique trong tenant, snake_case hoặcXX-NN.- Không thể tạo trùng
codevới mã hệ thống.
PUT /api/telesales/dispositions/{id} — Sửa
Cho phép đổi mọi field trừ code và cờ is_system.
DELETE /api/telesales/dispositions/{id} — Xoá
- Chỉ xoá được mã không phải hệ thống và chưa được gán vào bất kỳ dataset nào.
- Nếu đang được ≥1 dataset dùng → HTTP 409 kèm list dataset id để admin gỡ trước.
GET /api/telesales/datasets/{id}/dispositions — Danh sách mã kết quả áp dụng
GET /api/telesales/datasets/5/dispositionsResponse 200 — array các mã kết quả đã gán cho bộ dữ liệu (subset của catalog telesales_dispositions chung của tenant):
{
"data": [
{
"disposition_code": "CB-01",
"display_order": 0,
"label": "Hẹn gọi lại",
"category": "callback",
"is_conversion": 0
},
{
"disposition_code": "RN-01",
"display_order": 1,
"label": "Renewal — Thành công đã thu",
"category": "contact",
"is_conversion": 1
}
]
}PUT /api/telesales/datasets/{id}/dispositions — Cập nhật mã kết quả áp dụng
Replace toàn bộ list mã kết quả áp dụng cho dataset (idempotent).
PUT /api/telesales/datasets/5/dispositions
Content-Type: application/json
{
"dispositions": [
"RN-01", "RN-02", "RN-03", "RN-04",
"RI-01", "RI-02", "RI-03",
"CB-01", "DO-01", "OT-01"
]
}Response 200:
{ "ok": true, "count": 10 }Validation: mọi mã trong list dispositions phải tồn tại trong catalog telesales_dispositions của tenant (không nhất thiết đã gán vào dataset). Mã không hợp lệ → HTTP 422:
{
"error": "invalid_dispositions",
"invalid": ["XX-99"]
}Push lead từ hệ thống ngoài
2 endpoint public để đối tác tích hợp CRM/hệ thống ngoài đẩy lead vào chiến dịch Zorio:
POST /api/v1/telesales/datasets/{dataset_code}/leads— bulk push (tối đa 500 lead/request)POST /api/v1/telesales/datasets/{dataset_code}/leads/single— single push (1 lead/request, response REST-ful, rate limit riêng 300/min)
→ Xem chi tiết + sample code + response mẫu tại section Push lead từ hệ thống ngoài (Ingest API) trong trang Khách hàng tiềm năng (Leads).
Pipeline kiểm tra khi ghi custom_fields (phase=attempt)
Khi agent submit disposition qua POST /api/telesales/calls/{uuid}/disposition, giá trị custom_fields được validate theo schema phase=attempt của dataset của chiến dịch. Pipeline 5 bước:
- Từ chối field không có trong dataset — key không match → 422
unknown_field - Chuyển đổi kiểu dữ liệu —
"42"→ int;"true"→ bool - Áp dụng validation — required, min/max, options membership
- Filter theo
visible_when— field không match disposition đang gửi → bị bỏ qua (không lưu) - Persist vào
telesales_call_attempts.custom_fieldsJSON
Response 200 kèm custom_fields_report:
{
"data": { "attempt_id": 999 },
"custom_fields_report": {
"summary": {
"total_fields": 3,
"accepted": 2,
"rejected": 1,
"filtered_by_visible_when": 0
},
"errors": [
{
"field": "commitment_date",
"error": "missing_required",
"message": "Trường \"Ngày cam kết thanh toán\" bắt buộc khi disposition = RN-02"
}
]
}
}Migration từ Custom Fields cũ
Nếu integration của bạn trước đây gọi /api/custom-fields cho 2 entity Telesales, xem hướng dẫn migration đầy đủ tại trang Custom Fields.
Tóm tắt các bước:
- Gọi
GET /api/telesales/datasets→ cache list bộ dữ liệu của tenant - Với mỗi bộ dữ liệu quan tâm, gọi
GET /api/telesales/datasets/{id}→ cache fields + dispositions - Thay mọi call
GET /api/custom-fields?entity=TelesalesLeadbằng đọcfields[]từ dataset (filterphase='lead') - Thay mọi call
POST/PUT/DELETE /api/custom-fieldsbằng endpoint dataset tương ứng - Khi push lead qua endpoint mới, dùng response
datasetblock để confirm
Sample code
Python (requests)
import requests
BASE = "https://api.zorio.vn"
TOKEN = "your_api_token"
headers = {"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}
# List datasets
datasets = requests.get(f"{BASE}/api/telesales/datasets", headers=headers).json()
# Get schema
dataset = requests.get(f"{BASE}/api/telesales/datasets/5", headers=headers).json()['data']
lead_fields = [f for f in dataset['fields'] if f['phase'] == 'lead']
# Push lead
result = requests.post(
f"{BASE}/api/v1/telesales/datasets/sample_life_renewal/leads",
headers=headers,
json={
"leads": [{"full_name": "Alice", "phone": "0900000001",
"lead_data": {"policy_number": "POL-2024-0001"}}],
"campaign_code": "SAMPLE_RENEWAL_202608"
}
).json()
print(f"Inserted {result['inserted']} into dataset {result['dataset']['name']}")Node.js (axios)
const axios = require('axios');
const client = axios.create({
baseURL: 'https://api.zorio.vn',
headers: { Authorization: `Bearer ${process.env.ZORIO_TOKEN}` },
});
// Push lead batch
const { data } = await client.post('/api/v1/telesales/datasets/sample_life_renewal/leads', {
leads: [
{ full_name: 'Alice', phone: '0900000001',
lead_data: { policy_number: 'POL-2024-0001' } },
],
campaign_code: 'SAMPLE_RENEWAL_202608',
});
console.log(`Inserted ${data.inserted} into dataset ${data.dataset.name}`);cURL
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"leads": [
{ "full_name": "Alice", "phone": "0900000001",
"lead_data": { "policy_number": "POL-2024-0001" } }
],
"campaign_code": "SAMPLE_RENEWAL_202608"
}' \
https://api.zorio.vn/api/v1/telesales/datasets/sample_life_renewal/leadsFAQ
Q1. Dataset có nested (parent-child) không?
A: Chưa. Mỗi dataset độc lập. Nếu muốn share field common, hiện phải copy sang từng dataset.
Q2. Chuyển dataset cho chiến dịch đang chạy được không?
A: Không khuyến nghị. Lead đã import theo schema cũ → data sẽ mismatch. Nên tạo chiến dịch mới với dataset khác.
Q3. Xoá dataset đang dùng cho chiến dịch được không?
A: Không. Trả 422 dataset_in_use. Phải xoá/lưu trữ chiến dịch trước.
Q4. Bulk create/update field không?
A: Chưa hỗ trợ. Loop từng call. Sẽ bổ sung trong bản v1.18+.
Q5. Webhook nào fire khi lead push qua dataset endpoint?
A: telesales.lead.imported — fire per-lead sau khi INSERT thành công. Subscribe trong Portal → Webhooks.
