เริ่มต้นใช้งาน

Call Recording AI API ให้ business ส่งสายโทรเข้ามาในระบบ, query record, ดู transcript / summary และสั่งให้ AI ประมวลผลใหม่ ทุก endpoint ผูกกับ business ของ token เท่านั้น

ค่า	รายละเอียด
Base URL	https://phone.mcloud.co.th/api/v1
Auth	Authorization: Bearer crk_...
Content	application/json
Rate limit	600 req / min

# ทดสอบว่า API token ใช้งานได้
curl https://phone.mcloud.co.th/api/v1/meta/whoami \
  -H "Authorization: Bearer crk_..."

Quickstart

5 นาทีสู่ call แรก

1. สร้าง API token

Dashboard → Business → API Tokens → สร้าง token พร้อมเลือก scopes โดย token จะแสดง เพียงครั้งเดียว — คัดลอกแล้วเก็บไว้ที่ปลอดภัย

2. ตรวจสอบ token

เรียก /meta/whoami ก่อน — ถ้าได้ 200 พร้อม business + scopes กลับมา แปลว่าทุกอย่างถูกต้อง

3. Ingest recording

ส่ง metadata มาที่ POST /recordings พร้อม audioPresignedUploadUrl: true — server จะ return presigned URL ให้ PUT ไฟล์เสียงขึ้น storage โดยตรง

4. Trigger AI

เรียก POST /recordings/{id}/reextract เพื่อให้ระบบถอดเสียง + สรุปใหม่ตาม provider ที่ business เลือก

# 1. ตรวจสอบ token
curl https://phone.mcloud.co.th/api/v1/meta/whoami \
  -H "Authorization: Bearer crk_..."

# 2. ส่ง metadata + ขอ upload URL
curl -X POST https://phone.mcloud.co.th/api/v1/recordings \
  -H "Authorization: Bearer crk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "dataId": "rec_2026_05_20_001",
    "callAt": "2026-05-20T08:14:00+07:00",
    "direction": "in",
    "customerPhone": "+66812345678",
    "audioPresignedUploadUrl": true
  }'

# 3. อัปโหลดไฟล์เสียง
curl -X PUT "<uploadUrl>" \
  --data-binary "@call.wav"

# 4. สั่ง AI
curl -X POST https://phone.mcloud.co.th/api/v1/recordings/$ID/reextract \
  -H "Authorization: Bearer crk_..."

const headers = { authorization: 'Bearer crk_...' };

// 1. who am I
await fetch('https://phone.mcloud.co.th/api/v1/meta/whoami', { headers });

// 2. ingest
const r = await fetch('https://phone.mcloud.co.th/api/v1/recordings', {
  method: 'POST',
  headers: { ...headers, 'content-type': 'application/json' },
  body: JSON.stringify({
    dataId: 'rec_2026_05_20_001',
    callAt: '2026-05-20T08:14:00+07:00',
    direction: 'in',
    audioPresignedUploadUrl: true,
  }),
});
const { id, uploadUrl } = await r.json();

// 3. upload
await fetch(uploadUrl, { method: 'PUT', body: audioBlob });

// 4. AI
await fetch(`https://phone.mcloud.co.th/api/v1/recordings/${id}/reextract`, {
  method: 'POST',
  headers,
});

import httpx

r = httpx.get(
    'https://phone.mcloud.co.th/api/v1/meta/whoami',
    headers={'authorization': 'Bearer crk_...'},
)
print(r.json())

Authentication

ทุก request ต้องมี header Authorization: Bearer crk_... โดย token ถูก hash เก็บ — server เก็บแค่ prefix + last-used timestamp เพื่อใช้ debug

Scopes

Token รับ subset ของ business permissions ตามที่เลือกตอนสร้าง

Scope	ความหมาย
view_recording_all	อ่าน recording ทั้งหมดใน business
view_recording_self	อ่านเฉพาะที่ link กับ user เอง
manage_recording_review	แก้ score / tag / comment
manage_call_recording	ingest / delete / re-extract
manage_recording_link	ผูก recording → user

Token แสดง ครั้งเดียว ตอนสร้าง หากหาย ให้ revoke แล้วออกใหม่

# Request — ต้องแนบ Bearer token
GET /api/v1/recordings HTTP/1.1
Host: phone.mcloud.co.th
Authorization: Bearer crk_a1b2c3d4...

# Response — 401 หากไม่มี
{
  "error": { "code": "missing_token" }
}

API Key ระดับบัญชี

API key มี สองระดับ — ทั้งคู่เรียก endpoint v1 ชุดเดียวกัน

	Business key	Account key
สร้างที่	Business → API Tokens	Settings → API Keys
ผูกกับ	business เดียว	ไม่ผูก (ต่อผู้ใช้)
Scopes	subset ที่เลือก	Owner เต็ม (manage_all) บน ทุก business ที่คุณเป็นสมาชิก
Header เพิ่ม	—	X-Business-Id: <businessId> (จำเป็นเมื่อเรียก data endpoint)

Business key ถูกผูกกับ business ที่สร้างโดยอัตโนมัติ ส่วน Account key ไม่ผูก — มันทำงานกับ business ที่คุณระบุใน header X-Business-Id ด้วยสิทธิ์ Owner เต็ม

⚠️ ข้อควรระวังด้านความปลอดภัย — Account key มีอำนาจเทียบเท่ากับการล็อกอินเป็น Owner ของ business ทั้งหมด ของคุณ และข้าม scope ของ token ระดับ business เก็บไว้เหมือนรหัสผ่าน อย่าส่งไปฝั่ง browser หรือ commit ลง repo และให้ revoke ทันทีหากหลุด

1. สร้าง Account key

Dashboard → Settings → API Keys → สร้าง key เช่นเดียวกับ business token, key จะแสดง เพียงครั้งเดียว — คัดลอกแล้วเก็บไว้ที่ปลอดภัย

2. ดู business id ของคุณ

เรียก /meta/whoami โดยไม่ใส่ X-Business-Id — Account key จะตอบ level: "account" พร้อมรายการ business ที่ใช้ได้

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

{
  "level": "account",
  "userId": "...",
  "scopes": ["manage_all"],
  "businesses": [
    { "id": "b1...", "name": "Acme Sales", "slug": "acme-sales" },
    { "id": "b2...", "name": "Acme Support", "slug": "acme-support" }
  ]
}

(ส่วน Business key จะตอบ { "level": "business", "business": { … }, "scopes": [...] })

3. เรียก data endpoint พร้อม X-Business-Id

ทุก data call (recordings, collections) ต้อง แนบ X-Business-Id เพื่อเลือก business ที่จะทำงานด้วย

curl https://phone.mcloud.co.th/api/v1/recordings \
  -H "Authorization: Bearer crk_..." \
  -H "X-Business-Id: b1..."

ถ้าไม่ใส่ header จะได้ 400 business_required และถ้าชี้ไปที่ business ที่คุณไม่ได้เป็นสมาชิก (หรือ id ผิดรูปแบบ) จะได้ 403 forbidden_business

Errors

ทุก error ตอบ JSON ทรงเดียวกัน — code เป็น machine-readable string

Status	Code	เกิดเมื่อ
400	business_required	Account key เรียก data endpoint โดยไม่มี/ว่าง X-Business-Id
401	missing_token	ไม่มี Authorization header
401	invalid_token	Token ผิด / หมดอายุ
401	token_disabled	Token ถูก revoke
403	insufficient_scope	Token ขาด permission
403	forbidden_business	Account key ชี้ไปที่ business ที่เจ้าของเข้าถึงไม่ได้ หรือ business id ผิดรูปแบบ
404	not_found	Resource ไม่อยู่ในขอบเขต business
422	validation_failed	Payload ไม่ถูกต้อง
429	rate_limited	เรียกเร็วเกินไป
500	internal_error	Server ผิดพลาด — แจ้งทีม

HTTP/1.1 403 Forbidden
content-type: application/json

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token lacks 'view_recording_all'"
  }
}