Click-to-Call

Khởi tạo cuộc gọi 2-leg từ API: A-leg dial agent extension → khi nhấc → B-leg dial số khách → bridge.

POST /api/pbx/calls/click-to-call

Request body fields

Field	Type	Required	Mô tả	Giá trị hợp lệ
from_extension	string	✅	Máy nhánh agent (A-leg)	Phải tồn tại + status=active. Regex ^[0-9]{3,10}$
to_phone	string	✅	Số đích cần gọi (B-leg)	Regex ^[0-9+]+$, 3-32 ký tự
caller_id	string	optional	Số hiển thị khi gọi ra	Fallback extension.outbound_caller_id hoặc from_extension. Tốt nhất chọn từ /api/pbx/caller-ids
trunk_id	integer	optional	ID trunk gọi ra (ưu tiên cao hơn trunk_name)	Phải tồn tại + status=active. KHÔNG truyền → fallback dialplan default (dialplan default Zorio PBX tự pick trunk theo LCR/number-pool)
trunk_name	string	optional	Tên trunk thay thế trunk_id	max 100 ký tự
headers	object	optional	Custom SIP headers — Zorio sẽ prefix X- và gắn vào INVITE B-leg	Key regex [A-Za-z0-9_-], value max 200 ký tự

Request Body (JSON) — Mode 1: auto routing (không truyền trunk)

{
  "from_extension": "1001",
  "to_phone": "0987654321"
}

Request Body (JSON) — Mode 2: force trunk + caller-id + CRM tracking header

{
  "from_extension": "1001",
  "to_phone": "0987654321",
  "caller_id": "0900000020",
  "trunk_id": 4,
  "headers": { "CRM-Lead-Id": "LEAD-42" }
}

Response body fields — 202 (Accepted, cuộc gọi đã enqueue)

Field	Type	Mô tả
call_uuid	string	UUID logic của cuộc gọi (CRM dùng để track xuyên suốt webhook events)
a_leg_uuid	string	UUID A-leg (kênh tới agent ext)
b_leg_uuid	string	UUID B-leg (kênh tới số khách)
from_extension	string	Echo từ request
to_phone	string	Echo từ request
caller_id	string	Số hiển thị thực tế đã resolve
trunk_id	integer|null	ID trunk đã chọn (null nếu dùng dialplan default)
trunk_name	string|null	Tên trunk đã chọn (null nếu dùng dialplan default)
routing_mode	string	direct_gateway (có trunk được chọn) hoặc dialplan_default (dùng dialplan routing)
status	string	queued (chưa kết nối). Sau đó CRM theo dõi qua webhook pbx.call.ringing / pbx.call.answered / pbx.call.hangup

Response Body (JSON) — 202

{
  "data": {
    "call_uuid": "1ac30fff-0968-452f-9a9f-56c21fc8fe3f",
    "a_leg_uuid": "fc22be63-271d-4842-859d-0ebba9f13c8a",
    "b_leg_uuid": "64486cf6-0577-46a4-81e9-23ca31f46249",
    "from_extension": "1001",
    "to_phone": "0987654321",
    "caller_id": "1001",
    "trunk_id": 4,
    "trunk_name": "POC",
    "routing_mode": "direct_gateway",
    "status": "queued"
  }
}

Rate limit

10 req / phút / token (riêng group này — chống abuse spam call).

Pattern hoạt động

A-leg dial agent ext → khi nhấc → B-leg dial số khách → bridge. CRM khách nhận event pbx.call.answered cho A-leg trước, sau đó pbx.call.answered cho B-leg.

1. Client gọi   POST /api/pbx/calls/click-to-call → 202 với call_uuid
2. Zorio        Webhook pbx.call.ringing → A-leg ext đổ chuông
3. Agent nhấc   Webhook pbx.call.answered (A-leg)
4. Zorio        Bridge dial B-leg ra số khách
5. Khách nhấc   Webhook pbx.call.answered (B-leg)
6. Cuộc gọi diễn ra
7. Cúp máy      Webhook pbx.call.hangup + pbx.cdr.created