چرخهٔ یک جلسه و نام‌گذاری گوینده‌ها

جلسه‌ای که می‌فرستید در پس‌زمینه پردازش می‌شود: لُب رونوشت آن را می‌نویسد، شاید منتظر نام گوینده‌ها بماند و بعد لُب جلسه را می‌سازد. این صفحه یک جلسه را از پاسخ 202 تا READY دنبال می‌کند و می‌گوید در این میان چه چیزهایی ممکن است آن را نگه دارد.

وضعیت‌ها

GET /recordings/{id}/status مقدار status جلسه را برمی‌گرداند:

`status`	معنا
`QUEUED`	لُب صدا را دریافت کرده و جلسه در نوبت است
`TRANSCRIBING`	رونوشت جلسه از روی صدا نوشته می‌شود
`NAMING`	رونوشت آماده است و جلسه منتظر نام گوینده‌ها، یا رد شدن از نام‌گذاری، است
`GENERATING`	لُب جلسه نوشته می‌شود
`READY`	آماده است و می‌توانید جلسهٔ کامل را بخوانید
`FAILED`	متوقف شد و `error.code` دلیلش را می‌گوید

هر جلسه در راه رسیدن به READY از QUEUED، TRANSCRIBING و GENERATING می‌گذرد. تنها مرحله‌ای که ممکن است پیش نیاید NAMING است؛ بخش نام‌گذاری گوینده‌ها را ببینید.
وضعیت ممکن است به عقب هم برگردد. تلاش دوباره جلسهٔ FAILED را به همان مرحله‌ای برمی‌گرداند که شکست خورده بود. وقتی صاحب حساب در برنامه لُب را دوباره می‌سازد («ساخت دوبارهٔ لُب»)، جلسهٔ READY تا آماده شدن لُب تازه دوباره GENERATING می‌شود. وقتی هم در صفحهٔ نام‌گذاری «بررسی دوبارهٔ جلسه» را انتخاب کند، جلسه به QUEUED برمی‌گردد.
اگر هر دقیقه یک بار وضعیت را بخوانید، همهٔ وضعیت‌ها را نمی‌بینید. منتظر وضعیت خاصی نمانید: هر وقت NAMING، READY یا FAILED را دیدید، کار همان مرحله را انجام دهید.
وقتی جلسه حذف شود، پاسخ وضعیت آن 404 است.

این‌که هر چند وقت یک بار بپرسید و چطور چند جلسه را با هم دنبال کنید، در پرس‌وجوی دوره‌ای و فید رویدادها آمده است.

هزینهٔ یک جلسه

پاسخ 202 از POST /recordings فیلد minutes را دارد: طول صدا، به‌اضافهٔ هزینهٔ افزودهٔ واژگان وقتی useKeyterms به کار برود، به‌اضافهٔ پیوست.

از لحظه‌ای که لُب جلسه را می‌پذیرد، این دقیقه‌ها کنار گذاشته می‌شوند: جلسهٔ بعدی‌ای که می‌فرستید نمی‌تواند آن‌ها را خرج کند.
هزینه یک بار گرفته می‌شود، وقتی رونوشت آماده شود. پس جلسه‌ای که در NAMING منتظر بماند، یا هنگام نوشتن لُب شکست بخورد، هزینه‌اش را پرداخته است.
جلسه‌ای که تبدیلش به رونوشت شکست بخورد هزینه‌ای ندارد؛ جلسه‌ای هم که پیش از آماده شدن رونوشت حذف شود هزینه‌ای ندارد.
اگر لُب در نهایت نتواند از پیوست استفاده کند، دقیقه‌های پیوست از هزینه کم می‌شوند.

این‌که وقتی موجودی کم بیاید چه می‌شود، و سقف روزانهٔ توکن، در دقیقه‌ها، سقف‌ها و محدودیت‌ها آمده است.

نام‌گذاری گوینده‌ها

چرا جلسه منتظر می‌ماند

وقتی در رونوشت دو صدا یا بیشتر باشد، لُب ممکن است در NAMING بایستد تا صاحب حساب پیش از نوشته شدن لُب، گوینده‌ها را نام‌گذاری کند؛ آن‌وقت تصمیم‌ها و اقدام‌ها به نام واقعی افراد نوشته می‌شوند، نه «گوینده ۱». این‌که جلسه بایستد یا نه، و چقدر، به تنظیم «نام‌گذاری گوینده‌ها»ی صاحب حساب در برنامه بستگی دارد:

تنظیم	`speakerNamingMode`	چه می‌شود
«بپرس»	`FORCE_ON`	جلسه منتظر می‌ماند تا گوینده‌ها نام‌گذاری شوند یا از نام‌گذاری رد شوند، یا تا `naming.deadline` بگذرد
«بپرس، ولی منتظر نمان»	`AUTO`	مدت کوتاهی منتظر می‌ماند و بعد خودش ادامه می‌دهد
«حدس خودکار»	`FORCE_OFF`	هرگز منتظر نمی‌ماند و لُب هر جا بتواند نام‌ها را حدس می‌زند

جلسه‌ای که فقط یک صدا دارد هم ممکن است مدت کوتاهی در NAMING بایستد تا اگر کسی صفحه را نگاه می‌کند، بتواند نام آن گوینده را بنویسد. لُب برای این مورد به صاحب حساب اعلانی نمی‌فرستد.

توکنی که دسترسی account:read دارد این تنظیم را از settings.speakerNamingMode در GET /account می‌خواند.

در مرحلهٔ `NAMING`

پاسخ وضعیت فیلد naming را دارد:

"naming": {
  "url": "https://app.lobbe.ai/m/MEETING_ID?name=speakers",
  "deadline": "2026-10-20T08:45:00.000Z"
}

naming.url صفحهٔ نام‌گذاری گوینده‌های جلسه را در برنامه باز می‌کند؛ صاحب حساب آن‌جا صدای هر گوینده را می‌شنود و نامش را می‌نویسد. این لینک فقط برای صاحب حساب و وقتی وارد حساب شده باشد باز می‌شود، پس فرستادنش در پیام‌رسان یا ایمیل بی‌خطر است. اگر بعد از گذشتن جلسه از این مرحله باز شود، فقط خود جلسه را نشان می‌دهد.
naming.deadline زمانی است که لُب بدون نام‌ها ادامه می‌دهد. در همان لحظه یا چند دقیقه بعد، لُب با نام‌هایی نوشته می‌شود که خودش می‌تواند بگذارد (مثلاً نام گوینده‌هایی که صدایشان را می‌شناسد)، و صاحب حساب بعداً هم می‌تواند گوینده‌ها را نام‌گذاری کند. فاصلهٔ این زمان به تنظیم بستگی دارد: با «بپرس، ولی منتظر نمان» کوتاه است و با «بپرس» چند ساعت.
naming.deadline ممکن است null باشد، با تنظیم «بپرس»: در این صورت لُب بی‌پایان منتظر صاحب حساب می‌ماند.
این زمان ممکن است دیرتر شود، وقتی صاحب حساب صفحهٔ نام‌گذاری را باز می‌کند. پس آن را از آخرین پاسخ وضعیت بخوانید، نه از اولین.

رد شدن از نام‌گذاری

POST /recordings/{id}/naming با بدنهٔ { "action": "skip" } همان کاری را می‌کند که دکمهٔ «رد شدن» در صفحهٔ نام‌گذاری می‌کند: هر صدایی که کسی نامش را ننوشته، اگر لُب پیشنهادی برایش داشته باشد، همان نام را می‌گیرد و لُب نوشته می‌شود.

curl https://app.lobbe.ai/api/v1/recordings/MEETING_ID/naming \
  -H "Authorization: Bearer $LOBBE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "skip" }'

پاسخ 200 همراه با وضعیت جلسه است، همان بدنه‌ای که GET /recordings/{id}/status برمی‌گرداند.
اگر جلسه در NAMING نباشد (از آن گذشته یا هنوز به آن نرسیده باشد)، پاسخ 409 NOT_NAMING است. به‌جای رد شدنِ دوباره، وضعیتش را بخوانید.
skip تنها کاری است که توکن این‌جا می‌تواند بکند و توکن نمی‌تواند نام بنویسد. نام‌گذاری کار صاحب حساب است، از راه naming.url.
رد شدن هزینه‌ای ندارد. به دسترسی recordings:write نیاز دارد و فقط روی جلسه‌های خود شما کار می‌کند، نه جلسه‌های سری‌ای که عضوش هستید؛ بدون recordings:read هم فقط روی جلسه‌هایی که همین توکن فرستاده است.

رد شدن از نام‌گذاری هنگام فرستادن جلسه

برای این‌که جلسه اصلاً در NAMING نایستد، naming=skip را همراه جلسه بفرستید:

curl https://app.lobbe.ai/api/v1/recordings \
  -H "Authorization: Bearer $LOBBE_TOKEN" \
  -F "audio=@meeting.m4a;type=audio/mp4" \
  -F naming=skip

جلسه از رونوشت یک‌راست به نوشتن لُب می‌رود و صداها همان‌طور نام می‌گیرند که با رد شدن از نام‌گذاری. بدون آن (naming=default)، تنظیم «نام‌گذاری گوینده‌ها»ی صاحب حساب تصمیم می‌گیرد.

`FAILED` و تلاش دوباره

در FAILED، پاسخ وضعیت فیلد error را دارد:

"error": { "code": "TRANSCRIBE_FAILED", "retryable": true }

error.code می‌گوید کدام مرحله شکست خورده است: TRANSCRIBE_FAILED یا GENERATE_FAILED. NO_SPEECH یعنی در صدا گفتاری نیست، و AUDIO_CORRUPT یعنی سرویس تبدیل گفتار به متن صدا را خراب دانسته و نپذیرفته است.
error.retryable می‌گوید تلاش دوباره کمکی می‌کند یا نه. برای NO_SPEECH و AUDIO_CORRUPT مقدارش false است: همان صدا دوباره همان‌طور شکست می‌خورد.
FAILED ممکن است موقت باشد. لُب مرحلهٔ شکست‌خورده را خودش دوباره امتحان می‌کند و ممکن است جلسه بی‌آنکه شما کاری بکنید ادامه پیدا کند. فید رویدادها recording.failed را فقط وقتی می‌فرستد که شکست قطعی باشد.

POST /recordings/{id}/retry مرحلهٔ شکست‌خورده را دوباره اجرا می‌کند (رونوشتی که آماده شده هیچ‌وقت دوباره نوشته نمی‌شود) و با وضعیت جلسه پاسخ 200 می‌دهد:

curl -X POST https://app.lobbe.ai/api/v1/recordings/MEETING_ID/retry \
  -H "Authorization: Bearer $LOBBE_TOKEN"

اگر جلسه FAILED نباشد، پاسخ 409 NOT_FAILED است.
تلاش دوباره هزینهٔ تازه‌ای ندارد: جلسه‌ای که هنگام نوشتن لُب شکست خورده هزینه‌اش را پیش‌تر پرداخته است، و جلسه‌ای که تبدیلش به رونوشت شکست خورده فقط یک بار هزینه می‌دهد، وقتی رونوشتش آماده شود.
اگر لُب هنوز خودش مشغول امتحان دوبارهٔ آن مرحله باشد، تلاش دوبارهٔ شما اجرای دومی راه نمی‌اندازد.
جلسهٔ AUDIO_CORRUPT دوباره اجرا نمی‌شود: پاسخ، وضعیت همان جلسه است که همچنان FAILED است.
جلسهٔ NO_SPEECH دوباره اجرا می‌شود. لُب اجازه می‌دهد در هر روز چند جلسهٔ بدون گفتار بی‌هزینه شکست بخورند؛ بیش از آن، جلسهٔ بدون گفتار لُبی خالی می‌گیرد و هزینه‌اش گرفته می‌شود. فقط وقتی دوباره امتحانش کنید که می‌دانید در صدا گفتاری هست.
تلاش دوباره به دسترسی recordings:write نیاز دارد و به همان جلسه‌هایی دسترسی دارد که رد شدن از نام‌گذاری.

زمان برگزاری جلسه

recordedAt زمانی است که جلسه برگزار شده است. آن را همراه جلسه بفرستید، به قالب ISO 8601 با اختلاف ساعت:

curl https://app.lobbe.ai/api/v1/recordings \
  -H "Authorization: Bearer $LOBBE_TOKEN" \
  -F "audio=@meeting.m4a;type=audio/mp4" \
  -F recordedAt=2026-10-19T10:30:00+03:30

اگر آن را نفرستید، recordedAt همان لحظه‌ای است که لُب جلسه را دریافت می‌کند.
این زمان می‌تواند تا ۵ دقیقه جلوتر از اکنون باشد (ساعت دستگاه‌ها کمی با هم فرق دارد) و نه پیش از سال ۲۰۰۰. هر مقدار دیگری پاسخ 400 VALIDATION می‌گیرد.
برنامه همین زمان را روی جلسه نشان می‌دهد و آرشیو و صفحه‌های سری را بر اساس آن مرتب می‌کند؛ پس جلسهٔ سه‌شنبهٔ گذشته که امروز فرستاده شود، کنار جلسه‌های سه‌شنبهٔ گذشته می‌نشیند. جست‌وجو هم بر اساس آن مرتب می‌کند و فیلترهای from و to آن همین زمان را می‌خوانند.
createdAt زمانی است که لُب جلسه را دریافت کرده است. فهرست جلسه‌های آماده (GET /recordings/ready) و فید رویدادها به همین ترتیب می‌مانند، پس اسکریپتی که آن‌ها را می‌خواند هیچ جلسه‌ای را به خاطر recordedAt قدیمی‌تر از دست نمی‌دهد.