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

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 ที่เก็บไว้ไม่ใช่ชนิดที่อ่านกลับได้

{
  "id": "0192f0...",
  "kind": "threecx",
  "name": "Main PBX",
  "isActive": true,
  "baseUrl": "https://pbx.example.com",
  "username": "apiuser"
}

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"}}'

{ "ok": true }

DELETE /providers/{id}

ลบ config ของ provider

Scopes: manage_provider_config

{ "ok": 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" }