---
read_when:
    - کار روی قابلیت‌ها یا Webhookهای Telegram
summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی ربات Telegram
title: Telegram
x-i18n:
    generated_at: "2026-07-27T15:06:58Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: f34067478f4a5a71ed8f18503234b4cfcf573ac740aa887b65d13d0e1f09ba54
    source_path: channels/telegram.md
    workflow: 16
---

آماده برای محیط عملیاتی جهت پیام‌های خصوصی ربات و گروه‌ها از طریق grammY. Long polling روش انتقال پیش‌فرض است؛ حالت Webhook اختیاری است.

<CardGroup cols={3}>
  <Card title="جفت‌سازی" icon="link" href="/fa/channels/pairing">
    سیاست پیش‌فرض پیام خصوصی برای Telegram، جفت‌سازی است.
  </Card>
  <Card title="عیب‌یابی کانال" icon="wrench" href="/fa/channels/troubleshooting">
    راهنماهای تشخیص و رفع اشکال میان‌کانالی.
  </Card>
  <Card title="پیکربندی Gateway" icon="settings" href="/fa/gateway/configuration">
    الگوها و نمونه‌های کامل پیکربندی کانال.
  </Card>
</CardGroup>

## راه‌اندازی سریع

<Steps>
  <Step title="توکن ربات را در BotFather ایجاد کنید">
    هر دو روش در پایان توکنی می‌دهند که در OpenClaw وارد می‌کنید — یکی را انتخاب کنید:

    - **روش گفت‌وگو**: Telegram را باز کنید، با **@BotFather** گفت‌وگو کنید (تأیید کنید که شناسه دقیقاً `@BotFather` است)، `/newbot` را اجرا کنید، دستورالعمل‌ها را دنبال کنید و توکن را ذخیره کنید.
    - **روش وب**: [برنامه وب BotFather](https://t.me/BotFather?startapp) را باز کنید — این برنامه در همه کلاینت‌های Telegram، از جمله [web.telegram.org](https://web.telegram.org)، اجرا می‌شود — ربات را در رابط کاربری ایجاد و توکن آن را کپی کنید.

  </Step>

  <Step title="توکن و سیاست پیام خصوصی را پیکربندی کنید">

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}
```

    جایگزین محیطی: `TELEGRAM_BOT_TOKEN` (فقط حساب پیش‌فرض؛ حساب‌های نام‌گذاری‌شده باید از `botToken` یا `tokenFile` استفاده کنند).
    Telegram از `openclaw channels login telegram` استفاده **نمی‌کند**؛ توکن را در پیکربندی/محیط تنظیم کنید، سپس Gateway را راه‌اندازی کنید.

  </Step>

  <Step title="Gateway را راه‌اندازی و نخستین پیام خصوصی را تأیید کنید">

```bash
openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```

    کدهای جفت‌سازی پس از 1 ساعت منقضی می‌شوند.

  </Step>

  <Step title="ربات را به یک گروه اضافه کنید">
    ربات را به گروه خود اضافه کنید، سپس دو شناسه موردنیاز برای دسترسی گروه را به‌دست آورید:

    - شناسه کاربری Telegram شما، برای `allowFrom` / `groupAllowFrom`
    - شناسه گفت‌وگوی گروهی Telegram، به‌عنوان کلید زیر `channels.telegram.groups`

    شناسه گفت‌وگوی گروهی را از `openclaw logs --follow`، یک ربات نمایش‌دهنده شناسه پیام‌های هدایت‌شده، یا `getUpdates` در Bot API دریافت کنید. پس از مجازشدن گروه، `/whoami@<bot_username>` شناسه‌های کاربر و گروه را تأیید می‌کند.

    شناسه‌های منفی سوپرگروه که با `-100` آغاز می‌شوند، شناسه گفت‌وگوی گروهی هستند. آن‌ها زیر `channels.telegram.groups` قرار می‌گیرند، نه `groupAllowFrom`.

  </Step>
</Steps>

<Note>
تفکیک توکن از حساب آگاه است: `tokenFile` بر `botToken` و آن نیز بر محیط اولویت دارد، و پیکربندی همیشه بر `TELEGRAM_BOT_TOKEN` اولویت دارد (که فقط برای حساب پیش‌فرض تفکیک می‌شود). پس از راه‌اندازی موفق، OpenClaw هویت ربات را تا 24 ساعت در حافظه نهان نگه می‌دارد تا راه‌اندازی‌های مجدد از یک فراخوانی اضافی `getMe` صرف‌نظر کنند؛ تغییر یا حذف توکن این حافظه نهان را پاک می‌کند.
</Note>

## تنظیمات سمت Telegram

<AccordionGroup>
  <Accordion title="حالت حریم خصوصی و مشاهده‌پذیری گروه">
    ربات‌های Telegram به‌طور پیش‌فرض از **Privacy Mode** استفاده می‌کنند که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند.

    برای مشاهده همه پیام‌های گروهی، یکی از این کارها را انجام دهید:

    - حالت حریم خصوصی را از طریق `/setprivacy` غیرفعال کنید، یا
    - ربات را مدیر گروه کنید.

    پس از تغییر حالت حریم خصوصی، ربات را در هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند.

  </Accordion>

  <Accordion title="مجوزهای گروه">
    وضعیت مدیریت در تنظیمات گروه Telegram کنترل می‌شود. ربات‌های مدیر همه پیام‌های گروهی را دریافت می‌کنند که برای رفتار همیشه‌فعال در گروه مفید است.
  </Accordion>

  <Accordion title="گزینه‌های مفید BotFather">

    - `/setjoingroups` — اجازه‌دادن/ندادن افزودن به گروه
    - `/setprivacy` — رفتار مشاهده‌پذیری در گروه

    اگر رابط کاربری را به فرمان‌های گفت‌وگو ترجیح می‌دهید، همین تنظیمات در [برنامه وب BotFather](https://t.me/BotFather?startapp) نیز در دسترس هستند.

  </Accordion>
</AccordionGroup>

## برنامه کوچک داشبورد

برای بازکردن داشبورد OpenClaw درون Telegram، `/dashboard` را در یک پیام خصوصی با ربات اجرا کنید.

الزامات:

- `gateway.tailscale.mode: "serve"` یا `"funnel"` برای URL منتشرشده HTTPS برنامه کوچک.
- شناسه عددی کاربری Telegram شما باید در `allowFrom` مؤثر حساب انتخاب‌شده یا در `commands.ownerAllowFrom` باشد.
- از پیام خصوصی استفاده کنید. در گروه‌ها، `/dashboard` با `open this in a DM with the bot` پاسخ می‌دهد و هیچ دکمه‌ای ارسال نمی‌کند.
- نصب‌های Docker: حالت‌های Serve/Funnel نیاز دارند که Gateway در کنار `tailscaled` به loopback متصل شود، که شبکه‌سازی bridge با پورت‌های منتشرشده نمی‌تواند آن را فراهم کند. کانتینر Gateway را با `network_mode: host` اجرا کنید و سوکت `tailscaled` میزبان (`/var/run/tailscale`) را همراه با CLI مربوط به `tailscale` در کانتینر mount کنید.

برنامه کوچک یک مسیر v1 مختص Tailscale است و از iframe در Telegram Web پشتیبانی نمی‌کند.

## کنترل دسترسی و فعال‌سازی

### هویت ربات در گروه

در گروه‌ها و موضوعات انجمن، اشاره صریح به شناسه پیکربندی‌شده ربات (برای مثال `@my_bot`) عامل انتخاب‌شده OpenClaw را خطاب قرار می‌دهد، حتی اگر نام شخصیت عامل با نام کاربری Telegram متفاوت باشد. سیاست سکوت گروه همچنان برای ترافیک نامرتبط اعمال می‌شود، اما خود شناسه ربات هرگز «شخص دیگری» نیست.

<Tabs>
  <Tab title="سیاست پیام خصوصی">
    `channels.telegram.dmPolicy` دسترسی پیام خصوصی را کنترل می‌کند:

    - `pairing` (پیش‌فرض)
    - `allowlist` (به حداقل یک شناسه فرستنده در `allowFrom` نیاز دارد)
    - `open` (نیاز دارد `allowFrom` شامل `"*"` باشد)
    - `disabled`

    `dmPolicy: "open"` همراه با `allowFrom: ["*"]` به هر حساب Telegram که نام کاربری ربات را پیدا یا حدس بزند اجازه می‌دهد به ربات فرمان دهد. از آن فقط برای ربات‌های عمداً عمومی با ابزارهای شدیداً محدود استفاده کنید؛ ربات‌های تک‌مالک باید از `allowlist` همراه با شناسه‌های عددی کاربر استفاده کنند.

    `channels.telegram.allowFrom` شناسه‌های عددی کاربران Telegram را می‌پذیرد. پیشوندهای `telegram:` / `tg:` پذیرفته و نرمال‌سازی می‌شوند.
    در پیکربندی‌های چندحسابی، یک `channels.telegram.allowFrom` محدودکننده در سطح بالا مرز ایمنی است: `allowFrom: ["*"]` در سطح حساب، آن حساب را عمومی نمی‌کند مگر اینکه فهرست مجاز مؤثرِ ادغام‌شده همچنان شامل یک نویسه عام صریح باشد.
    `dmPolicy: "allowlist"` همراه با `allowFrom` خالی، همه پیام‌های خصوصی را مسدود می‌کند و اعتبارسنجی پیکربندی آن را رد می‌کند.
    راه‌اندازی فقط شناسه‌های عددی کاربر را درخواست می‌کند. اگر پیکربندی شما ورودی‌های فهرست مجاز `@username` از یک راه‌اندازی قدیمی دارد، `openclaw doctor --fix` را اجرا کنید تا آن‌ها به شناسه‌های عددی تبدیل شوند (با حداکثر تلاش؛ نیازمند توکن ربات Telegram).
    اگر پیش‌تر به فایل‌های فهرست مجاز ذخیره جفت‌سازی متکی بودید، `openclaw doctor --fix` می‌تواند ورودی‌ها را برای جریان‌های فهرست مجاز در `channels.telegram.allowFrom` بازیابی کند (برای مثال، وقتی `dmPolicy: "allowlist"` هنوز هیچ شناسه صریحی ندارد).

    برای ربات‌های تک‌مالک، `dmPolicy: "allowlist"` با شناسه‌های عددی صریح `allowFrom` را به وابستگی به تأییدهای جفت‌سازی قبلی ترجیح دهید.

    سردرگمی رایج: تأیید جفت‌سازی پیام خصوصی به این معنا نیست که «این فرستنده در همه‌جا مجاز است». جفت‌سازی فقط دسترسی پیام خصوصی را اعطا می‌کند. اگر هنوز هیچ مالک فرمانی وجود نداشته باشد، نخستین جفت‌سازی تأییدشده همچنین `commands.ownerAllowFrom` را تنظیم می‌کند و یک حساب اپراتور صریح به فرمان‌های مختص مالک و تأییدهای exec می‌دهد. مجازبودن فرستنده در گروه همچنان از فهرست‌های مجاز صریح پیکربندی می‌آید.
    برای اینکه با یک هویت هم برای پیام‌های خصوصی و هم برای فرمان‌های گروهی مجاز باشید: شناسه عددی کاربری Telegram خود را در `channels.telegram.allowFrom` قرار دهید و برای فرمان‌های مختص مالک مطمئن شوید `commands.ownerAllowFrom` شامل `telegram:<your user id>` است.

    ### یافتن شناسه کاربری Telegram

    ایمن‌تر (بدون ربات شخص ثالث): به ربات خود پیام خصوصی بدهید، `openclaw logs --follow` را اجرا کنید و `from.id` را بخوانید.

    روش رسمی Bot API:

```bash
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```

    شخص ثالث (با حریم خصوصی کمتر): `@userinfobot` یا `@getidsbot`.

  </Tab>

  <Tab title="سیاست گروه و فهرست‌های مجاز">
    دو کنترل با هم اعمال می‌شوند:

    1. **کدام گروه‌ها مجاز هستند** (`channels.telegram.groups`)
       - بدون پیکربندی `groups`، `groupPolicy: "open"`: هر گروهی بررسی شناسه گروه را پشت سر می‌گذارد
       - بدون پیکربندی `groups`، `groupPolicy: "allowlist"` (پیش‌فرض): همه گروه‌ها مسدود می‌شوند تا ورودی‌های `groups` (یا `"*"`) را اضافه کنید
       - `groups` پیکربندی‌شده: به‌عنوان فهرست مجاز عمل می‌کند (شناسه‌های صریح یا `"*"`)

    2. **کدام فرستندگان در گروه‌ها مجاز هستند** (`channels.telegram.groupPolicy`)
       - `open` / `allowlist` (پیش‌فرض) / `disabled`

    `groupAllowFrom` فرستندگان گروه را فیلتر می‌کند؛ اگر تنظیم نشده باشد، Telegram به `allowFrom` بازمی‌گردد (نه ذخیره جفت‌سازی — مجوز فرستنده گروه هرگز تأییدهای ذخیره جفت‌سازی پیام خصوصی را به ارث نمی‌برد، که از `2026.2.25` یک مرز امنیتی است).
    ورودی‌های `groupAllowFrom` باید شناسه‌های عددی کاربران Telegram باشند (پیشوندهای `telegram:` / `tg:` نرمال‌سازی می‌شوند)؛ ورودی‌های غیرعددی نادیده گرفته می‌شوند. شناسه‌های گفت‌وگوی گروه یا سوپرگروه را اینجا قرار ندهید — شناسه‌های منفی گفت‌وگو زیر `channels.telegram.groups` قرار می‌گیرند.
    الگوی عملی برای ربات‌های تک‌مالک: شناسه کاربری خود را در `channels.telegram.allowFrom` تنظیم کنید، `groupAllowFrom` را تنظیم‌نشده بگذارید و گروه‌های هدف را زیر `channels.telegram.groups` مجاز کنید.
    اگر `channels.telegram` کاملاً در پیکربندی وجود نداشته باشد، زمان اجرا به‌طور پیش‌فرض از `groupPolicy="allowlist"` بسته در برابر خطا استفاده می‌کند، مگر اینکه `channels.defaults.groupPolicy` صریحاً تنظیم شده باشد.

    راه‌اندازی گروه مختص مالک:

```json5
{
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "pairing",
      allowFrom: ["<YOUR_TELEGRAM_USER_ID>"],
      groupPolicy: "allowlist",
      groups: {
        "<GROUP_CHAT_ID>": {
          requireMention: true,
        },
      },
    },
  },
}
```

    از داخل گروه با `@<bot_username> ping` آزمایش کنید. تا زمانی که `requireMention: true`، پیام‌های عادی گروه ربات را فعال نمی‌کنند.

    اجازه به هر عضو در یک گروه مشخص:

```json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}
```

    اجازه فقط به کاربران مشخص در یک گروه مشخص:

```json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["8734062810", "745123456"],
        },
      },
    },
  },
}
```

    <Warning>
      اشتباه رایج: `groupAllowFrom` فهرست مجاز گروه نیست.

      - شناسه‌های منفی گفت‌وگوی گروه/سوپرگروه Telegram (`-1001234567890`) زیر `channels.telegram.groups` قرار می‌گیرند.
      - شناسه‌های کاربران Telegram (`8734062810`) زیر `groupAllowFrom` قرار می‌گیرند تا مشخص شود کدام افراد درون یک گروه مجاز می‌توانند ربات را فعال کنند.
      - از `groupAllowFrom: ["*"]` فقط برای اجازه‌دادن به هر عضو یک گروه مجاز جهت صحبت با ربات استفاده کنید.

    </Warning>

  </Tab>

  <Tab title="رفتار اشاره">
    پاسخ‌های گروهی به‌طور پیش‌فرض نیازمند اشاره هستند. اشاره می‌تواند از این موارد باشد:

    - یک اشاره بومی `@botusername`، یا
    - یک الگوی اشاره در `agents.entries.*.groupChat.mentionPatterns` یا `messages.groupChat.mentionPatterns`

    گزینه‌های سطح نشست (فقط وضعیت، بدون ماندگاری): `/activation always`، `/activation mention`. برای ماندگاری از پیکربندی استفاده کنید:

```json5
{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}
```

    زمینه تاریخچه گروه همیشه فعال است و با `historyLimit` محدود می‌شود. برای غیرفعال‌کردن پنجره تاریخچه گروه، `channels.telegram.historyLimit: 0` را تنظیم کنید. `openclaw doctor --fix` کلید بازنشسته `includeGroupHistoryContext` را حذف می‌کند.

    دریافت شناسه گفت‌وگوی گروه: یک پیام گروهی را به `@userinfobot` / `@getidsbot` هدایت کنید، `chat.id` را از `openclaw logs --follow` بخوانید، `getUpdates` در Bot API را بررسی کنید، یا پس از مجازشدن گروه، `/whoami@<bot_username>` را اجرا کنید.

  </Tab>
</Tabs>

## رفتار زمان اجرا

- Telegram درون فرایند Gateway اجرا می‌شود.
- مسیریابی قطعی است: پاسخ پیام ورودی Telegram به Telegram بازمی‌گردد (مدل کانال‌ها را انتخاب نمی‌کند).
- پیام‌های ورودی به پوش مشترک کانال همراه با فراداده پاسخ، جای‌نگهدارهای رسانه و بافت پایدارشده زنجیره پاسخ برای پاسخ‌هایی که Gateway مشاهده کرده است، نرمال‌سازی می‌شوند.
- نشست‌های گروه بر اساس شناسه گروه از یکدیگر جدا می‌شوند. موضوع‌های انجمن `:topic:<threadId>` را اضافه می‌کنند.
- پیام‌های خصوصی می‌توانند `message_thread_id` را حمل کنند؛ OpenClaw آن را برای پاسخ‌ها حفظ می‌کند. نشست‌های موضوع پیام خصوصی فقط زمانی تفکیک می‌شوند که `getMe` در Telegram مقدار `has_topics_enabled: true` را برای ربات گزارش کند؛ در غیر این صورت، پیام‌های خصوصی در نشست تخت باقی می‌مانند.
- نظرسنجی طولانی از اجراکننده grammY با توالی‌بندی به‌ازای هر چت/هر رشته استفاده می‌کند. هم‌زمانی مقصد اجراکننده از `agents.defaults.maxConcurrent` استفاده می‌کند.
- راه‌اندازی چندحسابی، تعداد کاوش‌های هم‌زمان `getMe` را محدود می‌کند تا ناوگان‌های بزرگ ربات، کاوش همه حساب‌ها را یک‌باره پخش نکنند.
- هر فرایند Gateway از نظرسنجی طولانی محافظت می‌کند تا در هر لحظه فقط یک نظرسنج فعال بتواند از توکن ربات استفاده کند. تعارض‌های پایدار 409 در `getUpdates` نشان می‌دهند که Gateway دیگری از OpenClaw، یک اسکریپت یا نظرسنج خارجی دیگری در حال استفاده از همان توکن است.
- نگهبان نظرسنجی پس از 120 ثانیه بدون تکمیل سلامت‌سنجی `getUpdates`، دوباره راه‌اندازی می‌شود.
- Telegram Bot API از رسید خواندن پشتیبانی نمی‌کند (`sendReadReceipts` کاربرد ندارد).

<Note>
  `channels.telegram.dm.threadReplies` و `channels.telegram.direct.<chatId>.threadReplies` حذف شده‌اند. اگر پیکربندی شما هنوز این کلیدها را دارد، پس از ارتقا `openclaw doctor --fix` را اجرا کنید. مسیریابی موضوع پیام خصوصی اکنون از `getMe.has_topics_enabled` در Telegram پیروی می‌کند (که با حالت رشته‌ای BotFather کنترل می‌شود): ربات‌هایی که موضوع‌ها در آن‌ها فعال است، وقتی Telegram مقدار `message_thread_id` را ارسال می‌کند از نشست‌های پیام خصوصی محدود به رشته استفاده می‌کنند؛ دیگر پیام‌های خصوصی در نشست تخت باقی می‌مانند.
</Note>

## مرجع قابلیت‌ها

<AccordionGroup>
  <Accordion title="پیش‌نمایش پخش زنده (ویرایش پیام)">
    OpenClaw پاسخ‌های جزئی را به‌صورت بی‌درنگ در چت‌های مستقیم، گروه‌ها و موضوع‌ها پخش می‌کند: یک پیام پیش‌نمایش می‌فرستد، سپس بارها `editMessageText` را اجرا می‌کند و در همان‌جا آن را نهایی می‌کند.

    - `channels.telegram.streaming` برابر با `off | partial | block | progress` است (پیش‌فرض: `partial`)
    - پیش‌نمایش‌های کوتاه پاسخ اولیه با تأخیر ادغام می‌شوند و اگر اجرا همچنان فعال باشد، پس از یک تأخیر محدود ایجاد می‌شوند
    - `progress` یک پیش‌نویس وضعیت قابل‌ویرایش را برای پیشرفت ابزار حفظ می‌کند، اگر فعالیت پاسخ پیش از پیشرفت ابزار برسد برچسب وضعیت پایدار را نمایش می‌دهد، هنگام تکمیل آن را پاک می‌کند و پاسخ نهایی را به‌صورت یک پیام عادی می‌فرستد
    - `streaming.preview.toolProgress` کنترل می‌کند که آیا به‌روزرسانی‌های ابزار/پیشرفت از همان پیام پیش‌نمایش ویرایش‌شده دوباره استفاده کنند یا نه (پیش‌فرض: وقتی پخش پیش‌نمایش فعال است، `true`)
    - `streaming.preview.commandText` جزئیات فرمان/اجرا را درون آن خط‌ها کنترل می‌کند: `raw` (پیش‌فرض) یا `status` (فقط برچسب ابزار)
    - `streaming.progress.commentary` (پیش‌فرض: `false`) متن توضیح/مقدمه دستیار را در پیش‌نویس موقت پیشرفت فعال می‌کند
    - مقادیر قدیمی `channels.telegram.streamMode`، مقادیر بولی `streaming` و کلیدهای بازنشسته پیش‌نمایش پیش‌نویس بومی شناسایی می‌شوند؛ برای مهاجرت آن‌ها `openclaw doctor --fix` را اجرا کنید

    خط‌های پیشرفت ابزار، به‌روزرسانی‌های وضعیت کوتاهی هستند که هنگام اجرای ابزارها نمایش داده می‌شوند (اجرای فرمان، خواندن فایل‌ها، به‌روزرسانی‌های برنامه‌ریزی، خلاصه وصله‌ها و مقدمه/توضیحات Codex در حالت app-server). Telegram آن‌ها را به‌طور پیش‌فرض فعال نگه می‌دارد (مطابق رفتار منتشرشده از `v2026.4.22`+).

    ویرایش‌های پیش‌نمایش پاسخ را نگه دارید اما خط‌های پیشرفت ابزار را پنهان کنید:

    ```json
    {
      "channels": {
        "telegram": {
          "streaming": {
            "mode": "partial",
            "preview": { "toolProgress": false }
          }
        }
      }
    }
    ```

    پیشرفت ابزار را قابل‌مشاهده نگه دارید اما متن فرمان/اجرا را پنهان کنید:

    ```json
    {
      "channels": {
        "telegram": {
          "streaming": {
            "mode": "partial",
            "preview": { "commandText": "status" }
          }
        }
      }
    }
    ```

    حالت `progress` پیشرفت ابزار را بدون ویرایش پاسخ نهایی درون آن پیام نمایش می‌دهد. سیاست متن فرمان را زیر `streaming.progress` قرار دهید:

    ```json
    {
      "channels": {
        "telegram": {
          "streaming": {
            "mode": "progress",
            "progress": {
              "toolProgress": true,
              "commandText": "status"
            }
          }
        }
      }
    }
    ```

    `streaming.mode: "off"` ویرایش‌های پیش‌نمایش را غیرفعال و گفت‌وگوی عمومی ابزار/پیشرفت را به‌جای ارسال آن به‌صورت پیام‌های وضعیت مستقل سرکوب می‌کند؛ درخواست‌های تأیید، رسانه و خطاها همچنان از مسیر تحویل نهایی عادی ارسال می‌شوند. `streaming.preview.toolProgress: false` فقط ویرایش‌های پیش‌نمایش پاسخ را نگه می‌دارد.

    <Note>
      پاسخ به نقل‌قول‌های انتخاب‌شده استثنا است. وقتی `replyToMode` برابر با `first`، `all` یا `batched` باشد و پیام ورودی متن نقل‌قول انتخاب‌شده داشته باشد، OpenClaw پاسخ نهایی را به‌جای ویرایش پیش‌نمایش پاسخ، از مسیر بومی پاسخ به نقل‌قول Telegram می‌فرستد؛ بنابراین `streaming.preview.toolProgress` نمی‌تواند در آن نوبت خط‌های وضعیت را نمایش دهد. پاسخ به پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان پخش می‌شود. اگر مشاهده‌پذیری پیشرفت ابزار از پاسخ‌های بومی به نقل‌قول مهم‌تر است، `replyToMode: "off"` را تنظیم کنید، یا برای پذیرش این بده‌بستان `streaming.preview.toolProgress: false` را تنظیم کنید.
    </Note>

    برای پاسخ‌های فقط متنی: پیش‌نمایش‌های کوتاه، ویرایش نهایی را در همان‌جا دریافت می‌کنند؛ پاسخ‌های نهایی طولانی که به چند پیام تقسیم می‌شوند، از پیش‌نمایش به‌عنوان بخش اول دوباره استفاده می‌کنند و سپس فقط باقی‌مانده را می‌فرستند؛ پاسخ‌های نهایی حالت پیشرفت، پیش‌نویس وضعیت را پاک می‌کنند و از تحویل نهایی عادی استفاده می‌کنند؛ اگر ویرایش نهایی پیش از تأیید تکمیل ناموفق باشد، OpenClaw به تحویل نهایی عادی بازمی‌گردد و پیش‌نمایش کهنه را پاک می‌کند. برای پاسخ‌های پیچیده (محموله‌های رسانه‌ای)، OpenClaw همیشه به تحویل نهایی عادی بازمی‌گردد و پیش‌نمایش را پاک می‌کند.

    پخش پیش‌نمایش و پخش بلوکی با یکدیگر ناسازگارند — وقتی پخش بلوکی صراحتاً فعال باشد، OpenClaw برای جلوگیری از پخش دوگانه، پخش پیش‌نمایش را رد می‌کند.

    استدلال: `/reasoning stream` هنگام تولید، استدلال را در پیش‌نمایش زنده پخش می‌کند و سپس پس از تحویل نهایی، پیش‌نمایش استدلال را حذف می‌کند (برای قابل‌مشاهده نگه‌داشتن آن از `/reasoning on` استفاده کنید). پاسخ نهایی بدون متن استدلال ارسال می‌شود.

  </Accordion>

  <Accordion title="قالب‌بندی غنی پیام">
    متن خروجی به‌طور پیش‌فرض از پیام‌های استاندارد HTML در Telegram استفاده می‌کند که در کلاینت‌های فعلی خوانا هستند: پررنگ، کج، پیوندها، کد، متن‌های پوشیده و نقل‌قول‌ها — نه بلوک‌های مختص محتوای غنی Bot API 10.2 (جدول‌های بومی، جزئیات، رسانه غنی و فرمول‌ها).

    پیام‌های غنی Bot API 10.2 را فعال کنید:

```json5
{
  channels: {
    telegram: {
      richMessages: true,
    },
  },
}
```

    هنگام فعال‌سازی: به عامل گفته می‌شود که پیام‌های غنی برای این ربات/حساب در دسترس‌اند (همراه با قرارداد پشتیبانی‌شده نگارش Markdown + جزیره HTML)؛ متن Markdown از طریق IR مربوط به Markdown در OpenClaw به‌صورت بلوک‌های غنی نوع‌دار Bot API 10.2 رندر می‌شود (عنوان‌ها، جدول‌ها، جزئیات، فهرست‌های بررسی، رسانه غنی، فرمول‌ها، نقشه‌ها و کلاژها)؛ زیرنویس‌های رسانه همچنان از زیرنویس HTML در Telegram استفاده می‌کنند (پیام‌های غنی جایگزین زیرنویس‌ها نمی‌شوند و زیرنویس‌ها حداکثر 1024 نویسه دارند).

    این کار متن مدل را از نشانه‌های Markdown غنی Telegram دور نگه می‌دارد تا مقادیر پولی مانند `$400-600K` به‌عنوان ریاضی تجزیه نشوند. متن غنی طولانی به‌طور خودکار بر اساس محدودیت‌های Telegram تقسیم می‌شود. جدول‌هایی که از محدودیت 20 ستون عبور کنند به بلوک کد بازمی‌گردند.

    پیش‌فرض: خاموش، برای سازگاری کلاینت — برخی کلاینت‌های فعلی Desktop، Web، Android و شخص ثالث، پیام‌های غنی پذیرفته‌شده را پشتیبانی‌نشده رندر می‌کنند. مگر آن‌که همه کلاینت‌های مورداستفاده با ربات بتوانند آن‌ها را رندر کنند، این گزینه را خاموش نگه دارید. `/status` نشان می‌دهد که پیام‌های غنی در نشست فعلی روشن هستند یا خاموش.

    پیش‌نمایش پیوندها به‌طور پیش‌فرض روشن است. `channels.telegram.linkPreview: false` تشخیص خودکار موجودیت را برای متن غنی غیرفعال می‌کند.

  </Accordion>

  <Accordion title="فرمان‌های بومی و فرمان‌های سفارشی">
    منوی فرمان Telegram هنگام راه‌اندازی با `setMyCommands` ثبت می‌شود. `commands.native: "auto"` فرمان‌های بومی را برای Telegram فعال می‌کند.

    ورودی‌های سفارشی را به منوی فرمان اضافه کنید:

```json5
{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "پشتیبان‌گیری Git" },
        { command: "generate", description: "ایجاد یک تصویر" },
      ],
    },
  },
}
```

    قواعد: نام‌ها نرمال‌سازی می‌شوند (`/` ابتدایی حذف و حروف کوچک می‌شوند)؛ الگوی معتبر `a-z`، `0-9`، `_`، طول 1-32؛ فرمان‌های سفارشی نمی‌توانند فرمان‌های بومی را بازنویسی کنند؛ تعارض‌ها/تکراری‌ها رد و ثبت می‌شوند.

    فرمان‌های سفارشی فقط ورودی‌های منو هستند — رفتار را به‌طور خودکار پیاده‌سازی نمی‌کنند. فرمان‌های Plugin/skill حتی اگر در منوی Telegram نمایش داده نشوند، همچنان می‌توانند هنگام تایپ کار کنند. اگر فرمان‌های بومی غیرفعال باشند، فرمان‌های داخلی حذف می‌شوند؛ فرمان‌های سفارشی/Plugin ممکن است در صورت پیکربندی همچنان ثبت شوند.

    خطاهای رایج راه‌اندازی:

    - `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` پس از تلاش مجدد برای کوتاه‌سازی، به این معناست که منو همچنان سرریز می‌شود؛ تعداد فرمان‌های Plugin/skill/سفارشی را کاهش دهید یا `channels.telegram.commands.native` را غیرفعال کنید.
    - ناموفق‌بودن `deleteWebhook`، `deleteMyCommands` یا `setMyCommands` با `404: Not Found` در حالی که فرمان‌های مستقیم curl برای Bot API کار می‌کنند، معمولاً به این معناست که `channels.telegram.apiRoot` روی نقطه پایانی کامل `/bot<TOKEN>` تنظیم شده است. `apiRoot` باید فقط ریشه Bot API باشد؛ `openclaw doctor --fix` یک `/bot<TOKEN>` انتهایی ناخواسته را حذف می‌کند.
    - `getMe returned 401` به این معناست که Telegram توکن ربات پیکربندی‌شده را رد کرده است. `botToken`، `tokenFile` یا `TELEGRAM_BOT_TOKEN` (حساب پیش‌فرض) را با توکن فعلی BotFather به‌روزرسانی کنید؛ OpenClaw پیش از نظرسنجی متوقف می‌شود تا این مورد به‌عنوان خطای پاک‌سازی Webhook گزارش نشود.
    - `setMyCommands failed` همراه با خطاهای شبکه/واکشی معمولاً به این معناست که DNS/HTTPS خروجی به `api.telegram.org` مسدود است.

    ### فرمان‌های جفت‌سازی دستگاه (Plugin ‏`device-pair`)

    پس از نصب:

    1. `/pair` یک کد راه‌اندازی تولید می‌کند
    2. کد را در برنامه iOS جای‌گذاری کنید
    3. `/pair pending` درخواست‌های در انتظار را فهرست می‌کند (از جمله نقش/دامنه‌ها)
    4. تأیید: `/pair approve <requestId>`، `/pair approve` (فقط درخواست در انتظار) یا `/pair approve latest`

    اگر دستگاهی با جزئیات احراز هویت تغییریافته (نقش، دامنه‌ها، کلید عمومی) دوباره تلاش کند، درخواست در انتظار قبلی با یک `requestId` جدید جایگزین می‌شود؛ پیش از تأیید، `/pair pending` را دوباره اجرا کنید.

    جزئیات بیشتر: [جفت‌سازی](/fa/channels/pairing#pair-via-telegram).

  </Accordion>

  <Accordion title="دکمه‌های درون‌خطی">
    دامنه صفحه‌کلید درون‌خطی را پیکربندی کنید:

```json5
{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}
```

    بازنویسی به‌ازای هر حساب:

```json5
{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}
```

    دامنه‌ها: `off`، `dm`، `group`، `all`، `allowlist` (پیش‌فرض). مقدار قدیمی `capabilities: ["inlineButtons"]` به `"all"` نگاشت می‌شود.

    نمونه کنش پیام:

```json5
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "یک گزینه انتخاب کنید:",
  buttons: [
    [
      { text: "بله", callback_data: "yes" },
      { text: "خیر", callback_data: "no" },
    ],
    [{ text: "لغو", callback_data: "cancel" }],
  ],
}
```

    نمونه دکمه Mini App:

```json5
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "باز کردن برنامه:",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "راه‌اندازی", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}
```

    دکمه‌های `web_app` فقط در چت‌های خصوصی میان کاربر و ربات کار می‌کنند.

    کلیک‌های بازخوانی که هیچ کنترل‌کننده تعاملی ثبت‌شده Plugin آن‌ها را دریافت نکرده باشد، به‌صورت متن به عامل ارسال می‌شوند: `callback_data: <value>`.

  </Accordion>

  <Accordion title="کنش‌های پیام Telegram برای عامل‌ها و خودکارسازی">
    کنش‌ها:

    - `sendMessage` (`to`، `content`، `mediaUrl` اختیاری، `replyToMessageId`، `messageThreadId`)
    - `react` (`chatId`، `messageId`، `emoji`)
    - `deleteMessage` (`chatId`، `messageId`)
    - `editMessage` (`chatId`، `messageId`، `content` یا `caption`، دکمه‌های درون‌خطی اختیاری `presentation`؛ ویرایش‌های صرفاً مربوط به دکمه، نشانه‌گذاری پاسخ را به‌روزرسانی می‌کنند)
    - `createForumTopic` (`chatId`، `name`، `iconColor` اختیاری، `iconCustomEmojiId`)

    نام‌های مستعار کاربردپسند: `send`، `react`، `delete`، `edit`، `sticker`، `sticker-search`، `topic-create`.

    کنترل دسترسی: `channels.telegram.actions.sendMessage`، `deleteMessage`، `reactions`، `sticker` (پیش‌فرض: غیرفعال). `edit`، `createForumTopic` و `editForumTopic` به‌طور پیش‌فرض فعال‌اند و کلید اختصاصی ندارند.
    ارسال‌های زمان اجرا از تصویر لحظه‌ای فعال پیکربندی/اسرار در هنگام راه‌اندازی یا بارگذاری مجدد استفاده می‌کنند؛ بنابراین مسیرهای کنش برای هر ارسال، مقادیر `SecretRef` را دوباره تفکیک نمی‌کنند.

    معنای حذف واکنش: [/tools/reactions](/fa/tools/reactions).

  </Accordion>

  <Accordion title="برچسب‌های رشته‌بندی پاسخ">
    برچسب‌های صریح رشته‌بندی پاسخ در خروجی تولیدشده:

    - `[[reply_to_current]]` — به پیام آغازگر پاسخ می‌دهد
    - `[[reply_to:<id>]]` — به یک شناسه پیام مشخص پاسخ می‌دهد

    `channels.telegram.replyToMode`: `off` (پیش‌فرض)، `first`، `all`.

    وقتی رشته‌بندی پاسخ فعال باشد و متن/شرح اصلی در دسترس باشد، OpenClaw به‌طور خودکار یک گزیده نقل‌قول بومی اضافه می‌کند. Telegram متن نقل‌قول بومی را به 1024 واحد کد UTF-16 محدود می‌کند؛ پیام‌های طولانی‌تر از ابتدا نقل می‌شوند و اگر Telegram نقل‌قول را رد کند، به پاسخ ساده بازمی‌گردند.

    `off` فقط رشته‌بندی ضمنی پاسخ را غیرفعال می‌کند؛ برچسب‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند.

  </Accordion>

  <Accordion title="موضوعات انجمن و رفتار رشته">
    ابرگروه‌های انجمن: کلیدهای نشست موضوع، `:topic:<threadId>` را به انتهای خود می‌افزایند؛ پاسخ‌ها و وضعیت تایپ، رشته موضوع را هدف می‌گیرند؛ مسیر پیکربندی موضوع `channels.telegram.groups.<chatId>.topics.<threadId>` است.

    موضوع عمومی (`threadId=1`) یک حالت ویژه است: ارسال پیام، `message_thread_id` را حذف می‌کند (Telegram مقدار `sendMessage(...thread_id=1)` را با پیام "رشته یافت نشد" رد می‌کند)، اما کنش‌های تایپ همچنان `message_thread_id` را شامل می‌شوند (طبق تجربه برای نمایش نشانگر تایپ ضروری است).

    ورودی‌های موضوع، تنظیمات گروه را به ارث می‌برند مگر اینکه بازنویسی شوند (`requireMention`، `allowFrom`، `skills`، `systemPrompt`، `enabled`، `groupPolicy`). `agentId` فقط مختص موضوع است و از پیش‌فرض‌های گروه ارث‌بری نمی‌کند. `topics."*"` پیش‌فرض‌های همه موضوعات آن گروه را تعیین می‌کند؛ شناسه‌های دقیق موضوع همچنان بر `"*"` اولویت دارند.

    **مسیریابی عامل به‌ازای هر موضوع**: هر موضوع می‌تواند از طریق `agentId` در پیکربندی موضوع به عامل متفاوتی مسیریابی شود و فضای کاری، حافظه و نشست مخصوص خود را داشته باشد:

    ```json5
    {
      channels: {
        telegram: {
          groups: {
            "-1001234567890": {
              topics: {
                "1": { agentId: "main" },      // موضوع عمومی -> عامل اصلی
                "3": { agentId: "zu" },        // موضوع توسعه -> عامل zu
                "5": { agentId: "coder" }      // بازبینی کد -> عامل coder
              }
            }
          }
        }
      }
    }
    ```

    سپس هر موضوع کلید نشست مخصوص خود را دارد؛ برای مثال `agent:zu:telegram:group:-1001234567890:topic:3`.

    **اتصال پایدار موضوع ACP**: موضوعات انجمن می‌توانند نشست‌های مهار ACP را از طریق اتصال‌های نوع‌دار سطح بالا سنجاق کنند (`bindings[]` همراه با `type: "acp"`، `match.channel: "telegram"`، `peer.kind: "group"` و یک شناسه مقید به موضوع مانند `-1001234567890:topic:42`). در حال حاضر دامنه آن به موضوعات انجمن در گروه‌ها/ابرگروه‌ها محدود است. [عامل‌های ACP](/fa/tools/acp-agents) را ببینید.

    **ایجاد ACP متصل به رشته از گفت‌وگو**: `/acp spawn <agent> --thread here|auto` موضوع فعلی را به یک نشست ACP جدید متصل می‌کند؛ پیگیری‌ها مستقیماً به آنجا مسیریابی می‌شوند و OpenClaw تأیید ایجاد را در همان موضوع سنجاق می‌کند. با `session.threadBindings.spawnSessions` کنترل می‌شود (پیش‌فرض: `true`).

    زمینه قالب، `MessageThreadId` و `IsForum` را ارائه می‌کند. گفت‌وگوهای پیام مستقیم با `message_thread_id` فراداده پاسخ را نگه می‌دارند، اما فقط زمانی از کلیدهای نشست آگاه از رشته استفاده می‌کنند که `getMe` در Telegram مقدار `has_topics_enabled: true` را گزارش کند.
    بازنویسی‌های منسوخ `dm.threadReplies` و `direct.*.threadReplies` حذف شده‌اند؛ حالت رشته‌ای BotFather تنها منبع حقیقت است. برای حذف کلیدهای پیکربندی قدیمی، `openclaw doctor --fix` را اجرا کنید.

  </Accordion>

  <Accordion title="صدا، ویدئو و استیکرها">
    ### پیام‌های صوتی

    Telegram یادداشت‌های صوتی را از فایل‌های صوتی متمایز می‌کند. پیش‌فرض: رفتار فایل صوتی؛ برای اجبار ارسال به‌شکل یادداشت صوتی، در پاسخ عامل از برچسب `[[audio_as_voice]]` استفاده کنید. رونوشت یادداشت‌های صوتی ورودی در زمینه عامل به‌عنوان متن تولیدشده توسط ماشین و غیرقابل‌اعتماد قاب‌بندی می‌شوند، اما تشخیص اشاره همچنان از رونوشت خام استفاده می‌کند تا پیام‌های صوتی مشروط به اشاره همچنان کار کنند.

```json5
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}
```

    ### پیام‌های ویدئویی

    Telegram فایل‌های ویدئویی را از یادداشت‌های ویدئویی متمایز می‌کند. یادداشت‌های ویدئویی از شرح پشتیبانی نمی‌کنند؛ متن پیام ارائه‌شده جداگانه ارسال می‌شود.

```json5
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}
```

    ### مکان‌ها و محل‌ها

    از کنش موجود `send` همراه با یک شیء مستقل `location` استفاده کنید. مختصات، یک سنجاق بومی ارسال می‌کنند؛ افزودن هر دو `name` و `address` یک کارت بومی محل ارسال می‌کند. ارسال مکان را نمی‌توان با متن پیام یا رسانه ترکیب کرد.

```json5
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  location: {
    latitude: 48.858844,
    longitude: 2.294351,
    accuracy: 12,
    name: "برج ایفل",
    address: "شان دو مارس، پاریس",
  },
}
```

    ### استیکرها

    ورودی: WEBP ایستا بارگیری و پردازش می‌شود (جای‌نگهدار `<media:sticker>`)؛ TGS متحرک و WEBM ویدئویی نادیده گرفته می‌شوند.

    فیلدهای زمینه استیکر: `Sticker.emoji`، `Sticker.setName`، `Sticker.fileId`، `Sticker.fileUniqueId`، `Sticker.cachedDescription`. توضیحات در وضعیت Plugin مبتنی بر SQLite متعلق به OpenClaw ذخیره موقت می‌شوند تا فراخوانی‌های تکراری بینایی کاهش یابند.

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

```json5
{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}
```

    ارسال:

```json5
{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}
```

    جست‌وجوی استیکرهای ذخیره‌شده در حافظه نهان:

```json5
{
  action: "sticker-search",
  channel: "telegram",
  query: "گربه در حال دست تکان دادن",
  limit: 5,
}
```

  </Accordion>

  <Accordion title="اعلان‌های واکنش">
    واکنش‌های Telegram به‌صورت به‌روزرسانی‌های `message_reaction` و جدا از بار پیام دریافت می‌شوند. وقتی فعال باشد، OpenClaw رویدادهای سیستمی مانند `Telegram reaction added: 👍 by Alice (@alice) on msg 42` را در صف قرار می‌دهد.

    - `channels.telegram.reactionNotifications`: `off | own | all` (پیش‌فرض: `own`)
    - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (پیش‌فرض: `minimal`)

    `own` یعنی فقط واکنش‌های کاربران به پیام‌های ارسال‌شده توسط ربات (به‌صورت بهترین تلاش با استفاده از حافظه نهان پیام‌های ارسالی). رویدادهای واکنش همچنان کنترل‌های دسترسی Telegram را رعایت می‌کنند (`dmPolicy`، `allowFrom`، `groupPolicy`، `groupAllowFrom`)؛ فرستندگان غیرمجاز حذف می‌شوند.

    Telegram شناسه‌های رشته را در به‌روزرسانی‌های واکنش ارائه نمی‌کند: گروه‌های غیرانجمنی به نشست گفت‌وگوی گروه مسیریابی می‌شوند؛ گروه‌های انجمنی به نشست موضوع عمومی (`:topic:1`) مسیریابی می‌شوند، نه موضوع دقیق مبدأ.

    `allowed_updates` برای polling/webhook به‌طور خودکار شامل `message_reaction` می‌شود.

  </Accordion>

  <Accordion title="واکنش‌های تأیید دریافت">
    `ackReaction` هنگامی که OpenClaw یک پیام ورودی را پردازش می‌کند، یک ایموجی تأیید دریافت ارسال می‌کند. `messages.ackReactionScope` تعیین می‌کند که *چه زمانی* ارسال شود.

    **ترتیب تفکیک ایموجی:**

    - `channels.telegram.accounts.<accountId>.ackReaction`
    - `channels.telegram.ackReaction`
    - `messages.ackReaction`
    - ایموجی جایگزین هویت عامل (`agents.entries.*.identity.emoji`، وگرنه "👀")

    Telegram انتظار یک ایموجی یونیکد دارد (برای مثال "👀")؛ برای غیرفعال‌کردن واکنش برای یک کانال یا حساب، از `""` استفاده کنید.

    **دامنه (`messages.ackReactionScope`، پیش‌فرض `"group-mentions"`؛ در حال حاضر بدون بازنویسی مختص حساب Telegram یا کانال Telegram):**

    `all` (پیام‌های مستقیم + گروه‌ها، شامل رویدادهای محیطی اتاق)، `direct` (فقط پیام‌های مستقیم)، `group-all` (همه پیام‌های گروهی به‌جز رویدادهای محیطی اتاق، بدون پیام مستقیم)، `group-mentions` (گروه‌ها زمانی که به ربات اشاره می‌شود؛ **بدون پیام مستقیم** — پیش‌فرض)، `off` / `none` (غیرفعال).

    <Note>
    دامنه پیش‌فرض (`group-mentions`) واکنش تأیید دریافت را در پیام‌های مستقیم یا رویدادهای محیطی اتاق فعال نمی‌کند. برای پیام‌های مستقیم از `direct` یا `all` استفاده کنید؛ فقط `all` رویدادهای محیطی اتاق را تأیید می‌کند. این مقدار هنگام راه‌اندازی ارائه‌دهنده Telegram خوانده می‌شود؛ بنابراین برای اعمال تغییر، راه‌اندازی مجدد Gateway لازم است.
    </Note>

  </Accordion>

  <Accordion title="نوشتن پیکربندی از رویدادها و فرمان‌های Telegram">
    نوشتن پیکربندی کانال به‌طور پیش‌فرض فعال است (`configWrites !== false`). نوشتن‌های آغازشده توسط Telegram شامل رویدادهای مهاجرت گروه (`migrate_to_chat_id`، به‌روزرسانی‌های `channels.telegram.groups`) و `/config set` / `/config unset` است (به فعال‌بودن فرمان نیاز دارد).

    غیرفعال‌سازی:

```json5
{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}
```

  </Accordion>

  <Accordion title="نظرسنجی طولانی در برابر Webhook">
    پیش‌فرض، نظرسنجی طولانی است. برای حالت Webhook، `channels.telegram.webhookUrl` و `channels.telegram.webhookSecret` را تنظیم کنید؛ `webhookPath` اختیاری (پیش‌فرض `/telegram-webhook`)، `webhookHost` (پیش‌فرض `127.0.0.1`)، `webhookPort` (پیش‌فرض `8787`)، `webhookCertPath` (گواهی خودامضاشده PEM برای پیکربندی‌های دارای IP مستقیم یا بدون دامنه).

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

    شنونده محلی به‌طور پیش‌فرض به `127.0.0.1:8787` متصل می‌شود. برای ورودی عمومی، یک پروکسی معکوس جلوی درگاه محلی قرار دهید یا `webhookHost: "0.0.0.0"` را آگاهانه تنظیم کنید.

    حالت Webhook محافظ‌های درخواست، توکن محرمانه Telegram و بدنه JSON را اعتبارسنجی می‌کند، سپس پیش از بازگرداندن یک `200` خالی، به‌روزرسانی را در صف ورودی پایدار خود ثبت می‌کند. پذیرش پایدار موفق شامل `x-openclaw-delivery-accepted: durable` است؛ پاسخ‌های سلامت، مسیریابی، احراز هویت، اعتبارسنجی و خطای ذخیره‌سازی این سرآیند را حذف می‌کنند. پروکسی‌های معکوس و کنترل‌کننده‌های میزبان می‌توانند این سرآیند را الزامی کنند تا پذیرش OpenClaw را از یک `200` خالی عمومی تشخیص دهند، بدون اینکه پذیرش را از زمان‌بندی پاسخ استنباط کنند.

    پس از نوشتن پایدار، OpenClaw به‌روزرسانی‌ها را از طریق تخلیه ورودی کانال هسته مطالبه و پردازش می‌کند (مسیرهای به‌ازای هر گفت‌وگو/هر موضوع، تکمیل در زمان پذیرش نوبت، مهلت توقف پیش از پذیرش). نوبت‌های کند عامل، ACK تحویل Telegram را نگه نمی‌دارند.

  </Accordion>

  <Accordion title="محدودیت‌ها و مقصدهای CLI">
    - `channels.telegram.textChunkLimit` به‌طور پیش‌فرض 4000 است؛ `streaming.chunkMode="newline"` پیش از تقسیم بر اساس طول، مرزهای بندها (خطوط خالی) را ترجیح می‌دهد.
    - `channels.telegram.mediaMaxMb` (پیش‌فرض 100) اندازه رسانه‌های ورودی و خروجی را محدود می‌کند.
    - تاریخچه بافت گروه از `channels.telegram.historyLimit` یا `messages.groupChat.historyLimit` (پیش‌فرض 50) استفاده می‌کند؛ `0` آن را غیرفعال می‌کند.
    - بافت تکمیلی پاسخ/نقل‌قول/بازارسال، هنگامی که Gateway پیام‌های والد را مشاهده کرده باشد، در یک پنجره بافت مکالمه انتخاب‌شده عادی‌سازی می‌شود؛ کش پیام‌های مشاهده‌شده در وضعیت Plugin مبتنی بر SQLite متعلق به OpenClaw نگهداری می‌شود و `openclaw doctor --fix` فایل‌های جانبی قدیمی را وارد می‌کند. Telegram در هر به‌روزرسانی فقط یک `reply_to_message` کم‌عمق را شامل می‌شود، بنابراین زنجیره‌های قدیمی‌تر از کش به همان محموله محدودند.
    - فهرست‌های مجاز Telegram عمدتاً تعیین می‌کنند چه کسی می‌تواند عامل را فعال کند، نه اینکه مرز کاملی برای حذف اطلاعات از بافت تکمیلی باشند.
    - تاریخچه پیام خصوصی: `channels.telegram.dmHistoryLimit`، `channels.telegram.dms["<user_id>"].historyLimit`.

    مقصدهای ارسال در CLI و ابزار پیام، شناسه عددی چت، نام کاربری یا مقصد موضوع انجمن را می‌پذیرند:

```bash
openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"
```

    نظرسنجی‌ها از `openclaw message poll` استفاده می‌کنند و از موضوعات انجمن پشتیبانی می‌کنند:

```bash
openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public
```

    پرچم‌های نظرسنجی مختص Telegram: ‏`--poll-duration-seconds` (5-600)، `--poll-anonymous`، `--poll-public`، `--thread-id` (یا یک مقصد `:topic:`). ‏`--poll-option` بین 2 تا 12 بار تکرار می‌شود (سقف گزینه‌های Telegram).

    ارسال در Telegram همچنین از `--presentation` با بلوک‌های `buttons` برای صفحه‌کلیدهای درون‌خطی (وقتی `channels.telegram.capabilities.inlineButtons` آن را مجاز می‌داند)، `--pin` یا `--delivery '{"pin":true}'` برای درخواست تحویل سنجاق‌شده در صورتی که ربات بتواند در آن چت پیام را سنجاق کند، و `--force-document` برای ارسال تصاویر، GIFها و ویدئوهای خروجی به‌صورت سند به‌جای بارگذاری فشرده/متحرک/ویدئویی پشتیبانی می‌کند.

    محدودسازی کنش‌ها: `channels.telegram.actions.sendMessage=false` همه پیام‌های خروجی، از جمله نظرسنجی‌ها، را غیرفعال می‌کند؛ `channels.telegram.actions.poll=false` ایجاد نظرسنجی را غیرفعال می‌کند، اما ارسال‌های عادی را فعال نگه می‌دارد.

  </Accordion>

  <Accordion title="تأیید اجرای دستور در Telegram">
    Telegram از تأیید اجرای دستور در پیام‌های خصوصی تأییدکنندگان پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری درخواست‌ها را در چت یا موضوع مبدأ ارسال کند. تأییدکنندگان باید شناسه‌های عددی کاربر Telegram باشند.

    - `channels.telegram.execApprovals.enabled` (`"auto"` هنگامی فعال می‌شود که دست‌کم یک تأییدکننده قابل شناسایی باشد)
    - `channels.telegram.execApprovals.approvers` (به شناسه‌های عددی مالکان از `commands.ownerAllowFrom` بازمی‌گردد)
    - `channels.telegram.execApprovals.target`: ‏`dm` (پیش‌فرض) | `channel` | `both`
    - `agentFilter`، `sessionFilter`

    `channels.telegram.allowFrom`، `groupAllowFrom` و `defaultTo` کنترل می‌کنند چه کسی می‌تواند با ربات گفتگو کند و پاسخ‌های عادی را کجا ارسال می‌کند؛ آن‌ها کسی را به تأییدکننده اجرای دستور تبدیل نمی‌کنند. نخستین جفت‌سازی پیام خصوصی تأییدشده، وقتی هنوز هیچ مالک دستوری وجود ندارد، `commands.ownerAllowFrom` را راه‌اندازی اولیه می‌کند؛ بنابراین پیکربندی‌های تک‌مالکی بدون تکرار شناسه‌ها در `execApprovals.approvers` کار می‌کنند.

    تحویل در کانال، متن دستور را در چت نمایش می‌دهد؛ `channel` یا `both` را فقط در گروه‌ها/موضوعات مورداعتماد فعال کنید. وقتی درخواست در یک موضوع انجمن قرار می‌گیرد، OpenClaw موضوع را برای درخواست تأیید و پیگیری حفظ می‌کند. تأییدهای اجرای دستور به‌طور پیش‌فرض پس از 30 دقیقه منقضی می‌شوند.

    دکمه‌های تأیید درون‌خطی همچنین نیازمند آن‌اند که `channels.telegram.capabilities.inlineButtons` سطح مقصد (`dm`، `group` یا `all`) را مجاز کند. شناسه‌های تأییدی که با `plugin:` آغاز می‌شوند از طریق تأییدهای Plugin تفکیک می‌شوند؛ سایر شناسه‌ها ابتدا از طریق تأییدهای اجرای دستور تفکیک می‌شوند.

    [تأییدهای اجرای دستور](/fa/tools/exec-approvals) را ببینید.

  </Accordion>
</AccordionGroup>

## کنترل پاسخ‌های خطا

هنگامی که عامل با خطای تحویل یا ارائه‌دهنده مواجه می‌شود، سیاست خطا تعیین می‌کند آیا پیام‌های خطا به چت Telegram برسند یا خیر:

| کلید                             | مقادیر                     | پیش‌فرض  | توضیحات                                                                                                                                                                |
| ------------------------------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `always`، `once`، `silent` | `always` | `always` همه پیام‌های خطا را به چت می‌فرستد. `once` هر پیام خطای منحصربه‌فرد را در هر بازه انتظار داخلی یک‌بار ارسال می‌کند. `silent` هرگز پیام‌های خطا را به چت نمی‌فرستد. |

بازنویسی تنظیمات به‌ازای هر حساب، هر گروه و هر موضوع پشتیبانی می‌شود (با همان وراثت سایر کلیدهای پیکربندی Telegram).

```json5
{
  channels: {
    telegram: {
      errorPolicy: "always",
      groups: {
        "-1001234567890": {
          errorPolicy: "silent", // خطاها را در این گروه سرکوب کن
        },
      },
    },
  },
}
```

## عیب‌یابی

<AccordionGroup>
  <Accordion title="ربات به پیام‌های گروهی بدون اشاره پاسخ نمی‌دهد">

    - اگر `requireMention=false`، حالت حریم خصوصی Telegram باید دید کامل را مجاز کند: BotFather `/setprivacy` -> Disable، سپس ربات را از گروه حذف و دوباره اضافه کنید.
    - `openclaw channels status` هنگامی هشدار می‌دهد که پیکربندی انتظار پیام‌های گروهی بدون اشاره را دارد.
    - `openclaw channels status --probe` شناسه‌های عددی صریح گروه را بررسی می‌کند؛ عضویت نویسه عام `"*"` قابل بررسی نیست.
    - آزمون سریع نشست: `/activation always`.

  </Accordion>

  <Accordion title="ربات اصلاً پیام‌های گروه را نمی‌بیند">

    - وقتی `channels.telegram.groups` وجود دارد، گروه باید در فهرست باشد (یا `"*"` را شامل شود).
    - عضویت ربات در گروه را بررسی کنید.
    - برای دلایل نادیده‌گرفتن، `openclaw logs --follow` را بررسی کنید.

  </Accordion>

  <Accordion title="دستورها ناقص کار می‌کنند یا اصلاً کار نمی‌کنند">

    - هویت فرستنده خود را مجاز کنید (جفت‌سازی و/یا `allowFrom` عددی)؛ مجوزدهی دستور حتی وقتی سیاست گروه `open` باشد نیز اعمال می‌شود.
    - `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` یعنی منوی بومی ورودی‌های بیش‌ازحدی دارد؛ دستورهای Plugin/Skills/سفارشی را کاهش دهید یا منوهای بومی را غیرفعال کنید.
    - فراخوانی‌های راه‌اندازی `deleteMyCommands` / `setMyCommands` و فراخوانی‌های تایپ `sendChatAction` محدودند و هنگام پایان مهلت درخواست، یک‌بار از طریق انتقال جایگزین Telegram دوباره تلاش می‌شوند. خطاهای مداوم شبکه/واکشی معمولاً به این معناست که دسترسی DNS/HTTPS به `api.telegram.org` ممکن نیست.

  </Accordion>

  <Accordion title="راه‌اندازی توکن غیرمجاز گزارش می‌کند">

    - `getMe returned 401` یک خطای احراز هویت Telegram برای توکن پیکربندی‌شده ربات است. توکن را در BotFather دوباره کپی یا بازتولید کنید، سپس `channels.telegram.botToken`، `tokenFile`، `accounts.<id>.botToken` یا `TELEGRAM_BOT_TOKEN` (حساب پیش‌فرض) را به‌روزرسانی کنید.
    - `deleteWebhook 401 Unauthorized` هنگام راه‌اندازی نیز خطای احراز هویت است؛ تلقی آن به‌عنوان «هیچ Webhookای وجود ندارد» فقط همان خطای توکن نامعتبر را تا فراخوانی بعدی API به تعویق می‌اندازد.

  </Accordion>

  <Accordion title="ناپایداری نظرسنجی یا شبکه">

    - در Node 22+، واکشی/پروکسی سفارشی می‌تواند در صورت ناسازگاری نوع‌های `AbortSignal` رفتار لغو فوری را فعال کند.
    - برخی میزبان‌ها ابتدا `api.telegram.org` را به IPv6 تفکیک می‌کنند؛ خروجی خراب IPv6 باعث خطاهای متناوب API می‌شود.
    - گزارش‌هایی شامل `TypeError: fetch failed` یا `Network request for 'getUpdates' failed!` به‌عنوان خطاهای شبکه قابل‌بازیابی دوباره تلاش می‌شوند.
    - در هنگام راه‌اندازی نظرسنجی، OpenClaw کاوش موفق `getMe` زمان راه‌اندازی را برای grammY دوباره استفاده می‌کند تا اجراکننده پیش از نخستین `getUpdates` به `getMe` دومی نیاز نداشته باشد.
    - اگر `deleteWebhook` هنگام راه‌اندازی نظرسنجی با خطای گذرای شبکه شکست بخورد، OpenClaw به‌جای انجام فراخوانی کنترلی دیگری پیش از نظرسنجی، وارد نظرسنجی طولانی می‌شود. در این صورت Webhook همچنان فعال به‌شکل تداخل `getUpdates` نمایان می‌شود؛ OpenClaw انتقال را بازسازی می‌کند و پاک‌سازی Webhook را دوباره امتحان می‌کند.
    - `Polling stall detected` در گزارش‌ها یعنی OpenClaw به‌طور پیش‌فرض پس از 120 ثانیه بدون تکمیل زنده‌بودن نظرسنجی طولانی، نظرسنجی را از نو آغاز و انتقال را بازسازی می‌کند.
    - `openclaw channels status --probe` و `openclaw doctor` هنگامی هشدار می‌دهند که یک حساب نظرسنجی در حال اجرا پس از مهلت راه‌اندازی `getUpdates` را تکمیل نکرده باشد، یک حساب Webhook در حال اجرا پس از مهلت راه‌اندازی `setWebhook` را تکمیل نکرده باشد، یا آخرین فعالیت موفق انتقال نظرسنجی کهنه شده باشد.
    - Telegram متغیرهای محیطی پروکسی فرایند را برای انتقال Bot API رعایت می‌کند: `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY` و گونه‌های حروف کوچک. `NO_PROXY` / `no_proxy` همچنان می‌توانند `api.telegram.org` را دور بزنند.
    - اگر `OPENCLAW_PROXY_URL` برای محیط سرویس تنظیم شده باشد و هیچ متغیر محیطی استاندارد پروکسی وجود نداشته باشد، Telegram از آن URL برای انتقال Bot API نیز استفاده می‌کند.
    - در میزبان‌های VPS با خروجی مستقیم/TLS ناپایدار، فراخوانی‌های API مربوط به Telegram را از طریق پروکسی هدایت کنید:

```yaml
channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080
```

    - Node 22+ به‌طور پیش‌فرض از `autoSelectFamily=true` استفاده می‌کند (به‌جز WSL2). ترتیب نتیجه DNS در Telegram ابتدا `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`، سپس `channels.telegram.network.dnsResultOrder` و بعد پیش‌فرض فرایند (برای مثال `NODE_OPTIONS=--dns-result-order=ipv4first`) را رعایت می‌کند و اگر هیچ‌کدام اعمال نشوند، در Node 22+ به `ipv4first` بازمی‌گردد.
    - در WSL2، یا هنگامی که رفتار صرفاً IPv4 بهتر کار می‌کند، انتخاب خانواده را اجباری کنید:

```yaml
channels:
  telegram:
    network:
      autoSelectFamily: false
```

    - پاسخ‌های محدوده معیار RFC 2544 ‏(`198.18.0.0/15`) از پیش به‌طور پیش‌فرض برای دانلود رسانه‌های Telegram مجازند. اگر یک پروکسی fake-IP یا شفاف مورداعتماد هنگام دانلود رسانه، `api.telegram.org` را به نشانی خصوصی/داخلی/دارای کاربرد ویژه دیگری بازنویسی می‌کند، عبور مختص Telegram را فعال کنید:

```yaml
channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true
```

    - همین فعال‌سازی به‌ازای هر حساب نیز در `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` در دسترس است.
    - اگر پروکسی شما میزبان‌های رسانه Telegram را به `198.18.x.x` تفکیک می‌کند، ابتدا پرچم خطرناک را خاموش نگه دارید؛ آن محدوده از پیش به‌طور پیش‌فرض مجاز است.

    <Warning>
      `channels.telegram.network.dangerouslyAllowPrivateNetwork` محافظت‌های SSRF رسانه Telegram را تضعیف می‌کند. فقط برای محیط‌های پروکسی مورداعتماد و تحت کنترل اپراتور (مسیریابی fake-IP در Clash، Mihomo و Surge) که پاسخ‌های خصوصی یا دارای کاربرد ویژه خارج از محدوده معیار RFC 2544 تولید می‌کنند، از آن استفاده کنید. برای دسترسی عادی Telegram از اینترنت عمومی، آن را خاموش نگه دارید.
    </Warning>

    - بازنویسی‌های موقت محیط: `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`، `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`، `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`.
    - پاسخ‌های DNS را اعتبارسنجی کنید:

```bash
dig +short api.telegram.org A
dig +short api.telegram.org AAAA
```

  </Accordion>
</AccordionGroup>

راهنمای بیشتر: [عیب‌یابی کانال](/fa/channels/troubleshooting).

## مرجع پیکربندی

مرجع اصلی: [مرجع پیکربندی - Telegram](/fa/gateway/config-channels#telegram).

<Accordion title="فیلدهای مهم Telegram">

- راه‌اندازی/احراز هویت: `enabled`، `botToken`، `tokenFile` (باید یک فایل معمولی باشد؛ پیوندهای نمادین رد می‌شوند)، `accounts.*`
- کنترل دسترسی: `dmPolicy`، `allowFrom`، `groupPolicy`، `groupAllowFrom`، `groups`، `groups.*.topics.*`، `bindings[]` سطح‌بالا (`type: "acp"`)
- پیش‌فرض‌های موضوع: `groups.<chatId>.topics."*"` برای موضوع‌های انجمن بدون تطابق اعمال می‌شود؛ شناسه‌های دقیق موضوع آن را لغو می‌کنند
- تأییدهای اجرا: `execApprovals`، `accounts.*.execApprovals`
- فرمان/منو: `commands.native`، `commands.nativeSkills`، `customCommands`
- رشته‌بندی/پاسخ‌ها: `replyToMode`، `threadBindings`
- استریم: `streaming` (حالت‌های `off | partial | block | progress`)، `streaming.preview.toolProgress`
- قالب‌بندی/تحویل: `textChunkLimit`، `streaming.chunkMode`، `richMessages`، `markdown.tables` (`off | bullets | code | block`)، `linkPreview`، `responsePrefix`
- رسانه/شبکه: `mediaMaxMb`، `network.autoSelectFamily`، `network.dangerouslyAllowPrivateNetwork`، `proxy`
- ریشه API سفارشی: `apiRoot` (فقط ریشه Bot API؛ `/bot<TOKEN>` را شامل نکنید)، `trustedLocalFileRoots` (ریشه‌های مطلق `file_path` برای Bot API خودمیزبان)
- Webhook: `webhookUrl`، `webhookSecret`، `webhookPath`، `webhookHost`، `webhookPort`، `webhookCertPath`
- کنش‌ها/قابلیت‌ها: `capabilities.inlineButtons`، `actions.sendMessage|editMessage|deleteMessage|reactions|sticker|createForumTopic|editForumTopic`
- واکنش‌ها: `reactionNotifications`، `reactionLevel`
- خطاها: `errorPolicy`، `silentErrorReplies`
- نوشتن/تاریخچه: `configWrites`، `historyLimit`، `dmHistoryLimit`، `dms.*.historyLimit`

</Accordion>

<Note>
اولویت چندحسابی: وقتی دو یا چند شناسه حساب پیکربندی شده‌اند، برای صریح‌کردن مسیریابی پیش‌فرض، `channels.telegram.defaultAccount` را تنظیم کنید (یا `channels.telegram.accounts.default` را شامل کنید). در غیر این صورت، OpenClaw به نخستین شناسه حساب نرمال‌شده بازمی‌گردد و `openclaw doctor` هشدار می‌دهد. حساب‌های نام‌گذاری‌شده `channels.telegram.allowFrom` / `groupAllowFrom` را به ارث می‌برند، اما مقادیر `accounts.default.*` را به ارث نمی‌برند.
</Note>

## مرتبط

<CardGroup cols={2}>
  <Card title="جفت‌سازی" icon="link" href="/fa/channels/pairing">
    یک کاربر Telegram را با Gateway جفت کنید.
  </Card>
  <Card title="گروه‌ها" icon="users" href="/fa/channels/groups">
    رفتار فهرست مجاز گروه و موضوع.
  </Card>
  <Card title="مسیریابی کانال" icon="route" href="/fa/channels/channel-routing">
    پیام‌های ورودی را به عامل‌ها مسیریابی کنید.
  </Card>
  <Card title="امنیت" icon="shield" href="/fa/gateway/security">
    مدل تهدید و مقاوم‌سازی.
  </Card>
  <Card title="مسیریابی چندعاملی" icon="sitemap" href="/fa/concepts/multi-agent">
    گروه‌ها و موضوع‌ها را به عامل‌ها نگاشت کنید.
  </Card>
  <Card title="عیب‌یابی" icon="wrench" href="/fa/channels/troubleshooting">
    تشخیص مشکلات میان‌کانالی.
  </Card>
</CardGroup>
