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

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

Errors

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

Status	Code	เกิดเมื่อ
401	missing_token	ไม่มี Authorization header
401	invalid_token	Token ผิด / หมดอายุ
401	token_disabled	Token ถูก revoke
403	insufficient_scope	Token ขาด permission
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'"
  }
}