Meetings

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} เมื่อต้องการอ่านเนื้อหาจริง

ParamTypeNote
limitint1–200, ค่าเริ่มต้น 20
offsetintค่าเริ่มต้น 0
statusscheduled | confirmed | cancelled | completedoptional
kindappointment | recordingrecording = สร้างจากไฟล์เสียง/บทถอดเสียง (กลุ่มที่มีสรุป AI)
aiStatuspending | processing | completed | failed | offสถานะการวิเคราะห์ (off = ไม่ได้ขอให้ AI สรุป หรือยกเลิก / เลือกไม่สรุปตอนจบการบันทึก — ไฟล์เสียงและบทถอดเสียงที่ทำเสร็จแล้วยังอยู่ และจะคงเป็น off จนกว่าจะมีคนสั่งสรุป · ถ้ายกเลิกการสรุปใหม่ของการประชุมที่มีบทสรุปอยู่แล้ว สถานะจะกลับเป็น completed พร้อมบทสรุปเดิม)
meetingTypestringป้ายบนปฏิทินที่คุณตั้งเอง ("sales", "standup") ต้องตรงทุกตัวอักษร
startFromdateเริ่มช่วง (รวมวันนั้น) — YYYY-MM-DD = 00:00 ตาม tz
startTodateจบช่วง (รวมวันนั้น) — YYYY-MM-DD = 23:59:59.999 ตาม tz
tzIANA zoneเขตเวลาที่ใช้กับวันที่ที่ไม่ได้ระบุเวลา ค่าเริ่มต้น Asia/Bangkok
hasSummarytrue | falseกรองเฉพาะรายการที่มี/ไม่มีสรุป AI
searchstringค้นคำที่อยู่ในหัวข้อ คำอธิบาย และสถานที่ (ค้นคำพูดในการประชุมใช้ GET /meetings/transcripts/search)
sortDirasc | 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 เขียนไว้

นอกจากฟิลด์เดียวกับในรายการ จะได้เพิ่ม:

FieldTypeNote
attendeesarray{ name, email, role, responseStatus }
summaryobject | nullnull เมื่อยังวิเคราะห์ไม่เสร็จ วิเคราะห์ไม่สำเร็จ หรือเป็นนัดหมายที่ไม่มีไฟล์
meetCodestring | nullรหัสห้อง Meet (ลิงก์คือ /meet/<code>) — null = ไม่มีลิงก์ Meet
meetOpenDoorboolean | nulltrue = ใครมีลิงก์เข้าห้องได้ทันทีขณะคุณหรือผู้ร่วมจัดอยู่ในห้อง · 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} เพราะบทถอดเสียงยาวได้ไม่จำกัด

FieldTypeNote
formatsegments | notes | nonesegments = แยกเป็นช่วงคำพูด · notes = ข้อความที่วางไว้ซึ่งไม่ได้เป็นบทสนทนา (อยู่ใน notes) · none = ยังไม่มีบทถอดเสียง
segmentsarray{ index, speaker, startMs, endMs, text } — startMs/endMs เป็น null เมื่อบทถอดเสียงไม่มีเวลา (เช่น บทสนทนาที่วางเอง)
notesstring | nullมีค่าเมื่อ format เป็น notes
aiStatusstringถ้ายัง pending/processing บทถอดเสียงยังมาไม่ครบ

ยังไม่มีบทถอดเสียงตอบ 200 พร้อม format: "none" ไม่ใช่ 404

GET /meetings/transcripts/search

ค้นคำหรือวลีใน สิ่งที่พูด ในทุกการประชุมของคุณ ("ใครพูดถึงงบประมาณบ้าง") ไม่สนตัวพิมพ์เล็กใหญ่และการขึ้นบรรทัดใหม่

ParamTypeNote
qstringจำเป็น 2–200 ตัวอักษร
startFrom / startTo / tzdateช่วงวันที่ของการประชุม แบบเดียวกับ GET /meetings
limitintจำนวนช่วงที่ตรงคำค้นสูงสุด 1–200 ค่าเริ่มต้น 50
maxMeetingsintจำนวนการประชุมที่อ่าน (ใหม่สุดก่อน) 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 ที่ส่งมาจะถูกข้าม)

FieldTypeNote
titlestringจำเป็น สูงสุด 300 ตัวอักษร
startAtISO-8601จำเป็น ต้องมี offset เช่น 2026-11-10T09:00:00+07:00
endAtISO-8601 | nullต้องหลัง startAt
description · locationstring | null
meetingTypesales | interview | standup | review | client | internal | otherค่าเริ่มต้น internal
statusscheduled | confirmed | cancelled | completedค่าเริ่มต้น scheduled
allDay · timezoneค่าเริ่มต้น false · Asia/Bangkok
recurrenceFreq · recurrenceInterval · recurrenceUntilการนัดซ้ำ (none | daily | weekly | monthly)
attendeesarray{ displayName, email, role } สูงสุด 100 คน
remindersarray{ offsetMinutes } สูงสุด 10 รายการ
withMeetLinkbooleantrue = สร้างห้อง Meet ให้ด้วย
meetOpenDoorbooleanใช้กับนัดที่มีลิงก์ 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

FieldTypeNote
filefileจำเป็น ไฟล์เสียง สูงสุด 500 MB
meetingIduuidใส่ไฟล์ให้การประชุมที่มีอยู่แล้ว (เช่น นัดหมาย) — ข้อมูลเดิมของการประชุมนั้นจะถูกแทนที่
titlestringชื่อการประชุมใหม่ ถ้าไม่ใส่จะใช้ชื่อไฟล์
startAtISO-8601เวลาประชุม ถ้าไม่ใส่จะใช้เวลาตอนอัปโหลด
durationMsintความยาว ถ้ารู้

ตอบ 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

FieldTypeNote
textstringจำเป็น สูงสุด 2,000,000 ตัวอักษร ถ้าเป็นบทสนทนาแบบ "ชื่อ: คำพูด" จะแยกเป็นช่วงคำพูดให้
inputKindtranscript | 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

ข้อผิดพลาดของการเขียน

StatusCodeเกิดเมื่อ
400invalid_json · expected_multipart · audio_file_requiredbody อ่านไม่ได้ / ไม่ใช่ multipart / ไม่มีไฟล์
402meet_ai_quota_exhaustedสิทธิ์สรุปด้วย AI ของ Meet หมด
403personal_space_requiredเรียกการเขียนโดยไม่ได้ส่ง X-Business-Id: personal
403insufficient_scopekey ไม่มี manage_meeting
404not_found · action_item_not_foundไม่มีการประชุม / งานนี้ในพื้นที่ของคุณ
409meeting_live_recording · meeting_ai_not_running · summary_not_readyมีห้อง Meet กำลังบันทึก / ไม่มีการสรุปให้ยกเลิก / ยังไม่มีสรุป
413 · 415audio_file_too_large · audio_unsupported_formatไฟล์ใหญ่เกิน / ชนิดไฟล์ไม่รองรับ
422validation_failedข้อมูลไม่ถูกต้อง — issues บอกว่าผิดตรงไหน