Meetings
การประชุมและนัดหมายของคุณเอง ทั้งที่พิมพ์ลงปฏิทินเอง ที่สร้างจากไฟล์เสียง/บทถอดเสียงแล้วให้ AI สรุปให้ และไฟล์เสียงที่บันทึกจาก Meet อ่านได้ ค้นได้ทั้งชื่อและคำพูดในการประชุม สร้างนัดหมาย อัปโหลดไฟล์ให้ AI สรุป แก้ไข ติ๊กงาน และลบได้
การประชุมเป็นของแต่ละคน การประชุมเก็บอยู่ในพื้นที่ Meet ส่วนตัวของแต่ละคน ไม่ได้อยู่ในธุรกิจ และธุรกิจมองไม่เห็นการประชุมของสมาชิก Business key (หรือ account key ที่ส่ง
X-Business-Id: <business id>) จะได้รายการว่าง ("items": [],"total": 0) ได้404กับทุก meeting id และเขียนอะไรไม่ได้ (403 personal_space_required)ให้เรียกด้วย account key พร้อม
X-Business-Id: personalค่าสงวนนี้หมายถึงพื้นที่ของเจ้าของ key เสมอ จึงไม่ต้องรู้ id ของพื้นที่ (/meta/whoamiและ/businessesไม่แสดงพื้นที่นี้) ถ้าส่งpersonalไป endpoint อื่นที่ไม่ใช่ของการประชุมจะได้403 insufficient_scopeทุกตัว และ business key ที่ส่งpersonalจะได้403 account_key_requiredดูเพิ่มที่ เริ่มต้นใช้งาน → API key ระดับบัญชี
Scopes: view_meeting_all · view_meeting_self (อ่าน) · manage_meeting (เขียน)
Account key ที่ส่ง X-Business-Id: personal ได้ทั้งสาม scope จึงอ่านและจัดการได้ทุกการประชุมในพื้นที่ของคุณ ส่วน API key ที่มีแค่ view_meeting_self จะเห็นเฉพาะการประชุมที่ตัวเองเป็นเจ้าของ (ownerUserId) ซึ่งเป็นกติกาเดียวกับที่หน้าเว็บบังคับ
businessId ของแต่ละการประชุมคือ id ของพื้นที่ของคุณ พื้นที่นี้ไม่ใช่ธุรกิจ จึงไม่อยู่ในรายการธุรกิจของคุณ
GET /meetings
ค้นหา/ไล่รายการการประชุม เรียงตาม startAt ใหม่สุดก่อน
รายการนี้ ไม่มีเนื้อสรุป มาด้วย — สรุปเก็บอยู่ใน object storage และต้องดึงแยกทีละรายการ ใช้ GET /meetings/{id} เมื่อต้องการอ่านเนื้อหาจริง
| Param | Type | Note |
|---|---|---|
limit | int | 1–200, ค่าเริ่มต้น 20 |
offset | int | ค่าเริ่มต้น 0 |
status | scheduled | confirmed | cancelled | completed | optional |
kind | appointment | recording | recording = สร้างจากไฟล์เสียง/บทถอดเสียง (กลุ่มที่มีสรุป AI) |
aiStatus | pending | processing | completed | failed | off | สถานะการวิเคราะห์ (off = ไม่ได้ขอให้ AI สรุป หรือยกเลิก / เลือกไม่สรุปตอนจบการบันทึก — ไฟล์เสียงและบทถอดเสียงที่ทำเสร็จแล้วยังอยู่ และจะคงเป็น off จนกว่าจะมีคนสั่งสรุป · ถ้ายกเลิกการสรุปใหม่ของการประชุมที่มีบทสรุปอยู่แล้ว สถานะจะกลับเป็น completed พร้อมบทสรุปเดิม) |
meetingType | string | ป้ายบนปฏิทินที่คุณตั้งเอง ("sales", "standup") ต้องตรงทุกตัวอักษร |
startFrom | date | เริ่มช่วง (รวมวันนั้น) — YYYY-MM-DD = 00:00 ตาม tz |
startTo | date | จบช่วง (รวมวันนั้น) — YYYY-MM-DD = 23:59:59.999 ตาม tz |
tz | IANA zone | เขตเวลาที่ใช้กับวันที่ที่ไม่ได้ระบุเวลา ค่าเริ่มต้น Asia/Bangkok |
hasSummary | true | false | กรองเฉพาะรายการที่มี/ไม่มีสรุป AI |
search | string | ค้นคำที่อยู่ในหัวข้อ คำอธิบาย และสถานที่ (ค้นคำพูดในการประชุมใช้ GET /meetings/transcripts/search) |
sortDir | asc | desc | ค่าเริ่มต้น desc |
curl "https://phone.mcloud.co.th/api/v1/meetings?hasSummary=true&limit=5" \
-H "Authorization: Bearer crk_<account key>" \
-H "X-Business-Id: personal"
ตอบกลับ { items, total, limit, offset } โดยแต่ละ item มี id, title, kind, status, startAt, endAt, durationMs, sentiment, actionItemsTotal, actionItemsDone, aiStatus, hasSummary, hasTranscript, hasAudio
GET /meetings/{id}
การประชุมรายการเดียว พร้อมสรุปที่ AI เขียนไว้
นอกจากฟิลด์เดียวกับในรายการ จะได้เพิ่ม:
| Field | Type | Note |
|---|---|---|
attendees | array | { name, email, role, responseStatus } |
summary | object | null | null เมื่อยังวิเคราะห์ไม่เสร็จ วิเคราะห์ไม่สำเร็จ หรือเป็นนัดหมายที่ไม่มีไฟล์ |
meetCode | string | null | รหัสห้อง Meet (ลิงก์คือ /meet/<code>) — null = ไม่มีลิงก์ Meet |
meetOpenDoor | boolean | null | true = ใครมีลิงก์เข้าห้องได้ทันทีขณะคุณหรือผู้ร่วมจัดอยู่ในห้อง · false = ทุกคนต้องขอเข้าร่วม · null = ไม่มีลิงก์ Meet |
ทุกฟิลด์ใน summary เป็น optional (เพราะ AI เป็นผู้เขียน): executiveSummary, keyDecisions, actionItems ({ text, owner, dueDate, priority, done }), keyTopics, risks, openQuestions, nextSteps, sentiment, tone, language
การประชุมที่ยังไม่มีสรุปตอบ 200 ไม่ใช่ 404 — "มีอยู่จริงแต่ยังวิเคราะห์ไม่เสร็จ" เป็นคำตอบจริง ดูสาเหตุได้จาก aiStatus และ aiError
curl https://phone.mcloud.co.th/api/v1/meetings/<meeting id> \
-H "Authorization: Bearer crk_<account key>" \
-H "X-Business-Id: personal"
GET /meetings/{id}/transcript
สิ่งที่พูดในการประชุมครั้งนั้น เรียงทีละช่วงพร้อมคนพูดและเวลา แยกจาก GET /meetings/{id} เพราะบทถอดเสียงยาวได้ไม่จำกัด
| Field | Type | Note |
|---|---|---|
format | segments | notes | none | segments = แยกเป็นช่วงคำพูด · notes = ข้อความที่วางไว้ซึ่งไม่ได้เป็นบทสนทนา (อยู่ใน notes) · none = ยังไม่มีบทถอดเสียง |
segments | array | { index, speaker, startMs, endMs, text } — startMs/endMs เป็น null เมื่อบทถอดเสียงไม่มีเวลา (เช่น บทสนทนาที่วางเอง) |
notes | string | null | มีค่าเมื่อ format เป็น notes |
aiStatus | string | ถ้ายัง pending/processing บทถอดเสียงยังมาไม่ครบ |
ยังไม่มีบทถอดเสียงตอบ 200 พร้อม format: "none" ไม่ใช่ 404
GET /meetings/transcripts/search
ค้นคำหรือวลีใน สิ่งที่พูด ในทุกการประชุมของคุณ ("ใครพูดถึงงบประมาณบ้าง") ไม่สนตัวพิมพ์เล็กใหญ่และการขึ้นบรรทัดใหม่
| Param | Type | Note |
|---|---|---|
q | string | จำเป็น 2–200 ตัวอักษร |
startFrom / startTo / tz | date | ช่วงวันที่ของการประชุม แบบเดียวกับ GET /meetings |
limit | int | จำนวนช่วงที่ตรงคำค้นสูงสุด 1–200 ค่าเริ่มต้น 50 |
maxMeetings | int | จำนวนการประชุมที่อ่าน (ใหม่สุดก่อน) 1–100 ค่าเริ่มต้น 50 |
ตอบ { query, items, meetingsScanned, meetingsMatched, truncated, moreMeetings } แต่ละ item เป็น { meetingId, title, startAt, index, speaker, startMs, text } — ใช้ index เปิดบทสนทนารอบ ๆ ได้จาก GET /meetings/{id}/transcript
บทถอดเสียงเก็บอยู่ใน object storage ระบบจึงอ่านเฉพาะการประชุมล่าสุด
maxMeetingsรายการในช่วงวันที่ ถ้าmoreMeetingsเป็นtrueแปลว่ายังมีการประชุมเก่ากว่านั้นที่ไม่ได้อ่าน ให้แคบช่วงวันที่ลงแล้วค้นใหม่ ก่อนจะสรุปว่าไม่มีใครพูด
POST /meetings
สร้างนัดหมายบนปฏิทินของคุณ ใช้กติกาเดียวกับหน้าต่างนัดหมายบนเว็บ เจ้าของคือเจ้าของ key เสมอ (ownerUserId ที่ส่งมาจะถูกข้าม)
| Field | Type | Note |
|---|---|---|
title | string | จำเป็น สูงสุด 300 ตัวอักษร |
startAt | ISO-8601 | จำเป็น ต้องมี offset เช่น 2026-11-10T09:00:00+07:00 |
endAt | ISO-8601 | null | ต้องหลัง startAt |
description · location | string | null | |
meetingType | sales | interview | standup | review | client | internal | other | ค่าเริ่มต้น internal |
status | scheduled | confirmed | cancelled | completed | ค่าเริ่มต้น scheduled |
allDay · timezone | ค่าเริ่มต้น false · Asia/Bangkok | |
recurrenceFreq · recurrenceInterval · recurrenceUntil | การนัดซ้ำ (none | daily | weekly | monthly) | |
attendees | array | { displayName, email, role } สูงสุด 100 คน |
reminders | array | { offsetMinutes } สูงสุด 10 รายการ |
withMeetLink | boolean | true = สร้างห้อง Meet ให้ด้วย |
meetOpenDoor | boolean | ใช้กับนัดที่มีลิงก์ Meet: true = ใครมีลิงก์เข้าห้องได้ทันที ไม่ต้องกดรับ (ขณะคุณหรือผู้ร่วมจัดอยู่ในห้อง ถ้ายังไม่มีใครจะรอแล้วเข้าเอง) · ค่าเริ่มต้น false = ทุกคนต้องขอเข้าร่วม |
ตอบ 201 พร้อมการประชุม และ meetCode (รหัสห้อง Meet) meetOpenDoor กับ meetLinkFailed — ถ้าเป็น true แปลว่าบันทึกนัดหมายแล้ว แต่สร้างห้อง Meet ไม่สำเร็จ
curl -X POST https://phone.mcloud.co.th/api/v1/meetings \
-H "Authorization: Bearer crk_<account key>" \
-H "X-Business-Id: personal" \
-H "Content-Type: application/json" \
--data-binary @appointment.json
PATCH /meetings/{id}
แก้ไขการประชุม เฉพาะฟิลด์ที่ส่งมา ฟิลด์ที่ไม่ได้ส่งจะคงค่าเดิม (รวมผู้เข้าร่วมและการแจ้งเตือน) ฟิลด์ที่ใช้ได้เหมือน POST /meetings ทุกตัว ถ้าส่งฟิลด์ที่ไม่รู้จักจะได้ 422 ถ้าส่ง attendees หรือ reminders มา รายการใหม่จะแทนที่รายการเดิมทั้งหมด
การเปลี่ยนชื่อการประชุมที่บันทึกจาก Meet จะเปลี่ยนชื่อห้องที่บันทึกด้วย เหมือนบนเว็บ meetOpenDoor เปลี่ยนค่าห้องทันที แม้กำลังประชุมอยู่ ถ้าเลื่อนเวลาเริ่มตอนที่มีคนรออยู่ในห้องแล้ว นับถอยหลังในห้องจะเลื่อนตาม (เลื่อนมาเป็นตอนนี้หรือก่อนหน้า = เริ่มประชุมเลย)
DELETE /meetings/{id}
ย้ายการประชุมไปถังขยะ (กู้คืนได้จากถังขยะเหมือนลบบนเว็บ) การประชุมที่นัดซ้ำจะไปทั้งชุด ถ้ามีห้อง Meet กำลังบันทึกเข้าการประชุมนี้อยู่จะได้ 409 meeting_live_recording
POST /meetings/upload
อัปโหลดไฟล์เสียงการประชุมให้ AI ถอดเสียงและสรุป ส่งเป็น multipart/form-data
| Field | Type | Note |
|---|---|---|
file | file | จำเป็น ไฟล์เสียง สูงสุด 500 MB |
meetingId | uuid | ใส่ไฟล์ให้การประชุมที่มีอยู่แล้ว (เช่น นัดหมาย) — ข้อมูลเดิมของการประชุมนั้นจะถูกแทนที่ |
title | string | ชื่อการประชุมใหม่ ถ้าไม่ใส่จะใช้ชื่อไฟล์ |
startAt | ISO-8601 | เวลาประชุม ถ้าไม่ใส่จะใช้เวลาตอนอัปโหลด |
durationMs | int | ความยาว ถ้ารู้ |
ตอบ 202 { id, aiStatus: "pending" } แล้ว AI จะทำงานต่อเบื้องหลัง ดูความคืบหน้าจาก aiStatus หรือรับแจ้งผ่าน callback (ดูด้านล่าง)
- ใช้ สิทธิ์สรุปด้วย AI ของ Meet ของเจ้าของ key 1 ครั้ง (ไม่ตัดเครดิตธุรกิจ) ถ้าสิทธิ์หมดจะได้
402 meet_ai_quota_exhaustedก่อน ระบบจะอ่านไฟล์ - ไฟล์ใหญ่ให้ส่งมาที่โดเมนของ API ตามที่หน้าเริ่มต้นใช้งานระบุ ไม่ใช่โดเมนหน้าเว็บ
413 audio_file_too_large·415 audio_unsupported_format·409 meeting_live_recording(มีห้อง Meet กำลังบันทึกเข้าการประชุมนั้น)
curl -X POST https://phone.mcloud.co.th/api/v1/meetings/upload \
-H "Authorization: Bearer crk_<account key>" \
-H "X-Business-Id: personal" \
-F "file=@weekly-sync.m4a" \
-F "title=Weekly sync"
POST /meetings/text
ส่งบทถอดเสียงหรือบันทึกที่พิมพ์/วางเองให้ AI สรุป เป็น JSON
| Field | Type | Note |
|---|---|---|
text | string | จำเป็น สูงสุด 2,000,000 ตัวอักษร ถ้าเป็นบทสนทนาแบบ "ชื่อ: คำพูด" จะแยกเป็นช่วงคำพูดให้ |
inputKind | transcript | notes | ค่าเริ่มต้น transcript |
title · startAt · meetingId | เหมือน POST /meetings/upload |
ตอบ 202 { id, aiStatus: "pending" } ใช้สิทธิ์สรุปด้วย AI ของ Meet 1 ครั้งเหมือนการอัปโหลด
POST /meetings/{id}/analyze
สั่งให้ AI สรุปใหม่ (และใช้ลองใหม่เมื่อ aiStatus เป็น failed) body ไม่บังคับ — { "graphOnly": true } = วาดแผนงานใหม่อย่างเดียว ข้อมูลที่จ่ายสิทธิ์ไปแล้วสรุปใหม่ได้ฟรี ข้อมูลเก่าก่อนมีระบบสิทธิ์จะใช้สิทธิ์ 1 ครั้ง ครั้งเดียว ตอบ 202
POST /meetings/{id}/cancel-analysis
ยกเลิกการสรุปที่กำลังรอหรือกำลังทำ ตอบสถานะที่เหลือ: off (ยังไม่เคยมีสรุป) หรือ completed (ยกเลิกการสรุปใหม่ สรุปเดิมยังอยู่) ไม่คืนสิทธิ์ แต่สั่งสรุปทีหลังได้ฟรี ถ้าไม่มีอะไรให้ยกเลิกจะได้ 409 meeting_ai_not_running
PATCH /meetings/{id}/action-items/{index}
ติ๊กงานที่ต้องทำว่าเสร็จ (หรือยังไม่เสร็จ) body { "done": true } โดย index คือลำดับของงานใน summary.actionItems (เริ่มที่ 0) ตอบ { meetingId, index, done, actionItemsTotal, actionItemsDone } ถ้าการประชุมยังไม่มีสรุปจะได้ 409 summary_not_ready
แจ้งเตือนเมื่อสรุปเสร็จ (callback)
ตั้ง URL ปลายทางของคุณด้วย PUT /callbacks พร้อม X-Business-Id: personal (scope manage_meeting) แล้วระบบจะ POST แจ้งเมื่อ AI สรุปการประชุมของคุณเสร็จ (meeting_completed) หรือทำไม่สำเร็จจนหมดรอบลองใหม่ (meeting_failed) ลายเซ็น header และการส่งซ้ำเหมือน callback ของสายทุกอย่าง ดูรายละเอียดที่หน้า Callbacks
ข้อผิดพลาดของการเขียน
| Status | Code | เกิดเมื่อ |
|---|---|---|
400 | invalid_json · expected_multipart · audio_file_required | body อ่านไม่ได้ / ไม่ใช่ multipart / ไม่มีไฟล์ |
402 | meet_ai_quota_exhausted | สิทธิ์สรุปด้วย AI ของ Meet หมด |
403 | personal_space_required | เรียกการเขียนโดยไม่ได้ส่ง X-Business-Id: personal |
403 | insufficient_scope | key ไม่มี manage_meeting |
404 | not_found · action_item_not_found | ไม่มีการประชุม / งานนี้ในพื้นที่ของคุณ |
409 | meeting_live_recording · meeting_ai_not_running · summary_not_ready | มีห้อง Meet กำลังบันทึก / ไม่มีการสรุปให้ยกเลิก / ยังไม่มีสรุป |
413 · 415 | audio_file_too_large · audio_unsupported_format | ไฟล์ใหญ่เกิน / ชนิดไฟล์ไม่รองรับ |
422 | validation_failed | ข้อมูลไม่ถูกต้อง — issues บอกว่าผิดตรงไหน |