Providers

ข้อมูล credential สำหรับเชื่อมต่อระบบโทรศัพท์ของ business — การเชื่อมต่อที่ดึง recording เข้ามาจาก PBX หรือ carrier ของคุณ รองรับสองชนิด: threecx (3CX PBX) และ dtac (DTAC carrier)

Account key: ทุก request ด้านล่างต้องส่ง X-Business-Id: <business id> เพื่อเลือก business ที่จะทำงานด้วย (ถ้าไม่ส่งจะได้ 400 business_required) business key ไม่สนใจ header นี้ — มันผูกกับ business เดียวอยู่แล้ว ดูเพิ่มที่ Getting started → API Key ระดับบัญชี

Secret เป็นแบบ write-only provider เก็บ credential รวมถึง password คุณส่ง password ตอน create/update ได้ แต่ GET จะไม่คืน password กลับมา — response ของการอ่านจะแสดงแค่ baseUrl กับ username ส่วน list endpoint จะแสดง preview ที่ถูกปิดบังแทน

GET /providers

ดู provider ที่ตั้งค่าไว้สำหรับ business นี้

Scopes: manage_provider_config

curl https://phone.mcloud.co.th/api/v1/providers \
  -H "Authorization: Bearer crk_..."

{
  "items": [
    {
      "id": "0192f0...",
      "kind": "threecx",
      "name": "Main PBX",
      "isActive": true,
      "preview": "apiuser @ pbx.example.com",
      "createdAt": "2026-05-01T00:00:00Z"
    }
  ]
}

POST /providers

สร้าง provider — รูปร่างของ object config ขึ้นกับ kind (ดูด้านล่าง)

Scopes: manage_provider_config

Param	Type	Note
kind	"threecx" | "dtac"	required
name	string (2-60)	required
config	object	required — รูปร่างขึ้นกับ kind
isActive	boolean	optional (default true)

config สำหรับ threecx:

Field	Type	Note
baseUrl	url	required
username	string	required
password	string	required (write-only)
headless	boolean	optional

config สำหรับ dtac:

Field	Type	Note
baseUrl	url	optional
username	string	required
password	string	required (write-only)
pollIntervalMinutes	int 5-1440	optional

เงื่อนไขการเก็บสาย — config.agentFilter (ทั้งสองชนิด, optional):

เก็บเฉพาะสายของ agent ที่เลือก ทำงาน ก่อนดาวน์โหลด สายที่ถูกกรองออกจะไม่ถูก transcode วิเคราะห์ หรือคิดเงิน ไม่ใส่ (หรือใช้ mode: "all") = เก็บทุกสาย ดูค่า keys ที่ใช้ได้จาก GET /providers/{id}/people

Field	Type	Note
mode	"all" | "include" | "exclude"	default "all"
keys	string[]	agent ที่จะเก็บ/ยกเว้น — 3CX: extension · DTAC: user id
directions	("in" | "out")[]	optional — ไม่ใส่ = ทั้งสองทิศ
minDurationSec	int 0-3600	optional — ตัดสายที่สั้นกว่านี้

curl -X POST https://phone.mcloud.co.th/api/v1/providers \
  -H "Authorization: Bearer crk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "threecx",
    "name": "Main PBX",
    "config": {
      "baseUrl": "https://pbx.example.com",
      "username": "apiuser",
      "password": "s3cret"
    },
    "isActive": true
  }'

{ "id": "0192f0..." }

GET /providers/{id}

ดึง provider หนึ่งตัว — จะไม่คืน password มีแค่ baseUrl กับ username

Scopes: manage_provider_config

Error	Status	เมื่อไหร่
provider_not_found	404	ไม่มี provider นี้ใน business นี้
provider_kind_not_supported	422	kind ที่เก็บไว้ไม่ใช่ชนิดที่อ่านกลับได้

response จะมีเงื่อนไขการเก็บสาย (agentFilter) ด้วย หรือเป็น null ถ้าไม่ได้ตั้งไว้

{
  "id": "0192f0...",
  "kind": "threecx",
  "name": "Main PBX",
  "isActive": true,
  "baseUrl": "https://pbx.example.com",
  "username": "apiuser",
  "agentFilter": {
    "mode": "include",
    "keys": ["12110", "12117"],
    "directions": ["in", "out"],
    "minDurationSec": 10
  }
}

PATCH /providers/{id}

แก้ provider — config จะถูก merge กับค่าที่เก็บไว้ ดังนั้นส่งเฉพาะ key ที่ต้องการเปลี่ยนได้ (เช่นเปลี่ยน password โดยไม่ต้องส่ง baseUrl ซ้ำ)

Scopes: manage_provider_config

Param	Type	Note
name	string (2-60)	optional
config	object	optional — merge เข้ากับ config ที่เก็บไว้
isActive	boolean	optional

curl -X PATCH https://phone.mcloud.co.th/api/v1/providers/$ID \
  -H "Authorization: Bearer crk_..." \
  -H "Content-Type: application/json" \
  -d '{"config":{"password":"r0tated"}}'

ตั้งเงื่อนไขการเก็บสายด้วยวิธีเดียวกัน — ส่ง config.agentFilter (merge เข้าไป จึงไม่กระทบ credential):

curl -X PATCH https://phone.mcloud.co.th/api/v1/providers/$ID \
  -H "Authorization: Bearer crk_..." \
  -H "Content-Type: application/json" \
  -d '{"config":{"agentFilter":{"mode":"include","keys":["12110","12117"]}}}'

{ "ok": true }

DELETE /providers/{id}

ลบ config ของ provider

Scopes: manage_provider_config

{ "ok": true }

GET /providers/{id}/people

ดึงรายชื่อ agent/คนที่เลือกได้ของ provider นี้ เพื่อหา key ที่ใช้ตั้งเงื่อนไขการเก็บสาย (config.agentFilter.keys) เป็นการ เรียกสดไปที่ provider (directory extension ของ 3CX / รายชื่อ user ของ DTAC) จึงอาจใช้เวลาสองสามวินาที

Scopes: manage_provider_config

Field	ความหมาย
key	ค่าที่ใส่ใน agentFilter.keys — extension (3CX) / user id (DTAC)
name	ชื่อที่แสดง
detail	extension (3CX) หรือเบอร์โทร (DTAC)
active	agent เปิดใช้งานอยู่ที่ provider หรือไม่

Error	Status	เมื่อไหร่
provider_not_found	404	ไม่มี provider นี้ใน business นี้
provider_kind_not_supported	422	kind ที่เก็บไว้ไม่ใช่ provider โทรศัพท์
provider_people_unavailable	502	login/ดึงรายชื่อจาก provider ล้มเหลว (credential ผิด หรือ provider ล่ม)

curl https://phone.mcloud.co.th/api/v1/providers/$ID/people \
  -H "Authorization: Bearer crk_..."

{
  "provider": "threecx",
  "people": [
    { "key": "12110", "name": "Jintana Promdee", "detail": "ext 12110", "active": true }
  ]
}

POST /providers/{id}/test

ทดสอบการเชื่อมต่อด้วย credential ที่เก็บไว้ — คืน 200 ทั้งสองกรณี การเชื่อมต่อล้มเหลวจะแจ้งใน body ไม่ใช่เป็น HTTP error

Scopes: manage_provider_config

curl -X POST https://phone.mcloud.co.th/api/v1/providers/$ID/test \
  -H "Authorization: Bearer crk_..."

{ "ok": true }

{ "ok": false, "error": "authentication failed" }