شروع سریع: فرستادن یک جلسه

در این صفحه یک جلسه را با curl از ابتدا تا انتها در لُب پیش می‌برید: توکن می‌سازید، صدای جلسه را می‌فرستید، وضعیتش را دنبال می‌کنید، نام‌گذاری گوینده‌ها را به صاحب حساب می‌سپارید و لُب را می‌خوانید. همهٔ کار چند دقیقه طول می‌کشد که بیشترش انتظار است.

۱. ساختن توکن

توکن را در برنامهٔ لُب می‌سازید، و توکن‌ها فقط تا وقتی کار می‌کنند که «حالت توسعه‌دهنده» روشن باشد.

1. در برنامه «حساب» را باز کنید و در بخش «توسعه‌دهندگان»، «حالت توسعه‌دهنده» را روشن کنید. این حالت به‌طور پیش‌فرض خاموش است؛ وقتی روشنش کنید، «اتصال‌ها» زیر آن نمایان می‌شود.

2. «اتصال‌ها» را باز کنید و «ساخت توکن» را بزنید، یا مستقیم به app.lobbe.ai/connections/tokens/new بروید.

3. برای توکن نامی بنویسید. زیر «جلسه‌ها»، «ارسال جلسه» را انتخاب کنید و «خواندن» را که از پیش انتخاب شده نگه دارید. زمان انقضا را انتخاب کنید و «ساخت توکن» را بزنید.

4. توکن فقط همین یک بار نمایش داده می‌شود. آن را کپی کنید و در یک متغیر محیطی نگه دارید:

   export LOBBE_TOKEN=lobbe_…

اگر فرم «ارسال جلسه» را نشان نمی‌دهد، فرستادن جلسه با توکن هنوز برای حساب شما روشن نشده است. نسخهٔ فقط‌خواندنیِ انتهای همین صفحه تنها با «خواندن» کار می‌کند.

۲. بررسی توکن

curl https://app.lobbe.ai/api/v1/whoami \
  -H "Authorization: Bearer $LOBBE_TOKEN"

پاسخ می‌گوید توکن متعلق به کیست و چه کارهایی می‌تواند بکند:

{
  "schemaVersion": 1,
  "owner": { "type": "user", "id": "USER_ID", "displayName": "Sara" },
  "token": {
    "id": "TOKEN_ID",
    "name": "n8n office",
    "scopes": ["recordings:read", "recordings:write"],
    "dailyMinuteCap": null,
    "usedMinutes24h": 0,
    "expiresAt": "2027-01-17T09:12:00.000Z"
  },
  "wallet": null,
  "limits": { "maxUploadMb": 300, "maxRecordingMinutes": 240 }
}

wallet برای توکنی که دسترسی account:read ندارد null است. limits بزرگ‌ترین فایل و طولانی‌ترین جلسه‌ای است که لُب همین حالا می‌پذیرد؛ دقیقه‌ها، سقف‌ها و محدودیت‌ها را ببینید. همهٔ فیلدها در GET /whoami آمده‌اند.

اگر پاسخ این درخواست 401 یا 403 بود، error.code مشکل را می‌گوید؛ 403 DEVELOPER_MODE_OFF یعنی «حالت توسعه‌دهنده» خاموش است. همهٔ کدها در خطاها آمده‌اند.

۳. فرستادن جلسه

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

بدنهٔ درخواست multipart/form-data است: فایل در فیلد audio می‌آید و نوعش پس از ;type=. لُب با 202 پاسخ می‌دهد:

{
  "schemaVersion": 1,
  "recording": {
    "id": "MEETING_ID",
    "status": "QUEUED",
    "minutes": 42,
    "recordedAt": "2026-10-19T08:30:00.000Z",
    "statusUrl": "https://app.lobbe.ai/api/v1/recordings/MEETING_ID/status",
    "bundleUrl": null,
    "url": "https://app.lobbe.ai/m/MEETING_ID"
  }
}

id را نگه دارید. minutes هزینهٔ این جلسه است که از موجودی شما خرج می‌شود. فیلدهای دیگری که می‌توانید بفرستید (زمان برگزاری جلسه، عنوان، سری، نوع ضبط، زبان لُب و نام‌گذاری) در POST /recordings آمده‌اند. برای این‌که بتوانید درخواست را بی‌خطر دوباره بفرستید و جلسهٔ دومی ساخته نشود، هدر Idempotency-Key را بفرستید: تکرارپذیری و تلاش دوباره را ببینید.

بدون ;type=، curl نوع فایل را application/octet-stream می‌فرستد. لُب بیشتر فایل‌های صوتی را باز هم از چند بایت اولشان می‌شناسد، اما نه همه را: پاسخ 400 VALIDATION با پیام Unsupported audio type یعنی لُب نتوانسته نوع فایل را تشخیص دهد، پس نوعش را بفرستید. فهرست فایل‌هایی که لُب می‌پذیرد و نوع هر کدام در دقیقه‌ها، سقف‌ها و محدودیت‌ها آمده است.

۴. انتظار برای آماده‌شدن

تقریباً هر یک دقیقه یک بار وضعیت جلسه را بخوانید:

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

مقدار status به این ترتیب پیش می‌رود:

status	چه اتفاقی می‌افتد
QUEUED	لُب صدا را دریافت کرده و جلسه در نوبت است
TRANSCRIBING	رونوشت جلسه از روی صدا نوشته می‌شود
NAMING	منتظر نام گوینده‌هاست؛ همهٔ جلسه‌ها در این مرحله نمی‌ایستند
GENERATING	لُب جلسه نوشته می‌شود
READY	آماده است: آن را بخوانید
FAILED	متوقف شد: error.code دلیلش را می‌گوید و error.retryable می‌گوید POST /recordings/{id}/retry کمکی می‌کند یا نه

FAILED همیشه پایان کار نیست: لُب مرحلهٔ شکست‌خورده را پس از کمی صبر خودش دوباره امتحان می‌کند، پس ممکن است وضعیت را درست وقتی بخوانید که FAILED است و جلسه بعد پیش برود. حلقهٔ پایین منتظر می‌ماند تا نوبت کار بعدی برسد. در FAILED، اگر error.retryable برابر true باشد، جلسه را دوباره اجرا می‌کند و منتظر می‌ماند، حداکثر سه بار؛ اگر شکست درست‌شدنی نباشد، یا با هر خطا، پاسخ را نشان می‌دهد و می‌ایستد (به jq نیاز دارد، و برای --fail-with-body به curl نسخهٔ ۷٫۷۶ یا بالاتر):

retries=0
while true; do
  body=$(curl -sS --fail-with-body https://app.lobbe.ai/api/v1/recordings/MEETING_ID/status \
    -H "Authorization: Bearer $LOBBE_TOKEN") || { echo "$body"; break; }
  status=$(jq -r .status <<<"$body")
  echo "$status"
  case "$status" in NAMING | READY) break ;; esac
  if [ "$status" = FAILED ]; then
    if [ "$(jq -r .error.retryable <<<"$body")" != true ] || [ "$retries" -ge 3 ]; then
      echo "$body"
      break
    fi
    retries=$((retries + 1))
    # 409 NOT_FAILED: it recovered by itself in the meantime. Keep waiting either way.
    body=$(curl -sS --fail-with-body -X POST \
      https://app.lobbe.ai/api/v1/recordings/MEETING_ID/retry \
      -H "Authorization: Bearer $LOBBE_TOKEN") ||
      [ "$(jq -r .error.code <<<"$body" 2>/dev/null)" = NOT_FAILED ] || { echo "$body"; break; }
  fi
  sleep 60
done

تلاش دوباره حتی وقتی لُب هنوز خودش مشغول امتحان دوبارهٔ آن مرحله است بی‌خطر است: اجرای دومی راه نمی‌اندازد و هزینهٔ تازه‌ای ندارد. FAILED و تلاش دوباره را ببینید.

اگر چند جلسه را دنبال می‌کنید، به‌جای خواندن وضعیت تک‌تک آن‌ها رویدادها را بخوانید: GET /events.

۵. نام‌گذاری گوینده‌ها، یا رد شدن از آن

در مرحلهٔ NAMING، پاسخ وضعیت فیلد naming را هم دارد:

{
  "schemaVersion": 1,
  "id": "MEETING_ID",
  "status": "NAMING",
  "title": null,
  "error": null,
  "naming": {
    "url": "https://app.lobbe.ai/m/MEETING_ID?name=speakers",
    "deadline": "2026-10-20T08:45:00.000Z"
  },
  "bundleUrl": null,
  "url": "https://app.lobbe.ai/m/MEETING_ID"
}

دو راه دارید:

• naming.url را به صاحب حساب بدهید. این لینک نام‌گذاری گوینده‌های جلسه را در برنامه باز می‌کند، آن هم فقط برای صاحب حساب و وقتی وارد حساب شده است؛ پس فرستادنش در پیام‌رسان یا ایمیل بی‌خطر است.

• از نام‌گذاری رد شوید:

  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 همراه با وضعیت جلسه است. اگر جلسه در مرحلهٔ NAMING نباشد، پاسخ 409 NOT_NAMING است.

اگر هیچ‌کدام از این دو کار انجام نشود، لُب از زمان naming.deadline به بعد بدون نام گوینده‌ها ادامه می‌دهد؛ اگر این مقدار null باشد، منتظر شما می‌ماند. برای این‌که جلسه اصلاً در این مرحله نایستد، هنگام فرستادن جلسه -F naming=skip را هم بفرستید.

۶. خواندن لُب

وقتی وضعیت READY شد:

curl "https://app.lobbe.ai/api/v1/recordings/MEETING_ID/bundle?format=markdown" \
  -H "Authorization: Bearer $LOBBE_TOKEN"

پاسخ یک سند Markdown است: عنوان، مشخصات جلسه، بخش‌های لُب و رونوشت. بدون ?format=markdown همین محتوا را به‌صورت JSON می‌گیرید؛ فیلدهایش در GET /recordings/{id}/bundle آمده است. خواندن جلسهٔ کامل به دسترسی recordings:read نیاز دارد.

با توکن فقط‌خواندنی

توکنی که فقط «خواندن» دارد نمی‌تواند جلسه بفرستد، اما جلسه‌های آمادهٔ شما را می‌خواند:

export LOBBE_TOKEN=lobbe_…

# Check the token
curl https://app.lobbe.ai/api/v1/whoami \
  -H "Authorization: Bearer $LOBBE_TOKEN"

# Your finished meetings, newest first
curl https://app.lobbe.ai/api/v1/recordings/ready \
  -H "Authorization: Bearer $LOBBE_TOKEN"

# One whole meeting, as Markdown
curl "https://app.lobbe.ai/api/v1/recordings/MEETING_ID/bundle?format=markdown" \
  -H "Authorization: Bearer $LOBBE_TOKEN"

یادداشت

ارسال جلسه، ساختن و ویرایش سری، تغییر تنظیمات، جست‌وجو و پرسش با توکن به‌تدریج روشن می‌شوند. اگر فرم «اتصال‌ها» دسترسی‌ای را پیشنهاد نمی‌دهد، آن دسترسی هنوز برای حساب شما فعال نشده است.

قدم بعد

• توکن‌ها و دسترسی‌ها: «حالت توسعه‌دهنده»، هشت دسترسی، سقف روزانه و کارهایی که هیچ توکنی نمی‌تواند بکند.
• دقیقه‌ها، سقف‌ها و محدودیت‌ها: چه چیزی دقیقه خرج می‌کند، سقف درخواست‌ها و محدودیت‌های ارسال فایل.
• مرجع API: همهٔ مسیرها، فیلدها و خطاهایشان.