From 223d22a7a4eebfaaad65a6bda6128339254304a8 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 11 Apr 2026 18:33:04 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/msteams.md | 577 +++++++++++++++++++++++------------- 1 file changed, 366 insertions(+), 211 deletions(-) diff --git a/docs/uk/channels/msteams.md b/docs/uk/channels/msteams.md index 5010f9e45..a8e73c2f3 100644 --- a/docs/uk/channels/msteams.md +++ b/docs/uk/channels/msteams.md @@ -1,30 +1,31 @@ --- read_when: - - Робота над можливостями каналу Microsoft Teams -summary: Статус підтримки бота Microsoft Teams, можливості та конфігурація + - Робота над функціями каналу Microsoft Teams +summary: Статус підтримки бота Microsoft Teams, можливості та налаштування title: Microsoft Teams x-i18n: - generated_at: "2026-04-05T18:00:02Z" + generated_at: "2026-04-11T18:30:42Z" model: gpt-5.4 provider: openai - source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf + source_hash: 3e6841a618fb030e4c2029b3652d45dedd516392e2ae17309ff46b93648ffb79 source_path: channels/msteams.md workflow: 15 --- # Microsoft Teams -> "Полиште всі надії, ті, хто входить сюди." +> «Залиште надію всі, хто сюди входить». -Оновлено: 2026-01-21 +Оновлено: 2026-03-25 -Статус: підтримуються текст і вкладення в DM; надсилання файлів у каналах/групах потребує `sharePointSiteId` + дозволів Graph (див. [Надсилання файлів у групових чатах](#sending-files-in-group-chats)). Polls надсилаються через Adaptive Cards. Дії з повідомленнями надають явний `upload-file` для надсилань, де файл є основним. +Статус: підтримуються текстові повідомлення + вкладення в DM; надсилання файлів у каналах/групах потребує `sharePointSiteId` + дозволів Graph (див. [Надсилання файлів у групових чатах](#sending-files-in-group-chats)). Опитування надсилаються через Adaptive Cards. Дії з повідомленнями надають явний `upload-file` для надсилань, що починаються з файлу. ## Вбудований плагін -Microsoft Teams постачається як вбудований плагін у поточних випусках OpenClaw, тому в типовій пакетній збірці окреме встановлення не потрібне. +Microsoft Teams постачається як вбудований плагін у поточних релізах OpenClaw, тож у звичайній пакетованій збірці окреме встановлення не потрібне. -Якщо ви використовуєте старішу збірку або власне встановлення без вбудованого Teams, установіть його вручну: +Якщо ви використовуєте старішу збірку або власне встановлення без вбудованого Teams, +встановіть його вручну: ```bash openclaw plugins install @openclaw/msteams @@ -36,19 +37,19 @@ openclaw plugins install @openclaw/msteams openclaw plugins install ./path/to/local/msteams-plugin ``` -Докладніше: [Plugins](/tools/plugin) +Докладніше: [Плагіни](/uk/tools/plugin) ## Швидке налаштування (для початківців) 1. Переконайтеся, що плагін Microsoft Teams доступний. - - У поточних пакетних випусках OpenClaw він уже вбудований. - - У старіших/власних установленнях його можна додати вручну за допомогою команд вище. + - У поточних пакетованих релізах OpenClaw він уже вбудований. + - У старіших/власних встановленнях його можна додати вручну командами вище. 2. Створіть **Azure Bot** (App ID + client secret + tenant ID). 3. Налаштуйте OpenClaw із цими обліковими даними. -4. Відкрийте `/api/messages` (порт 3978 типово) через публічний URL або тунель. +4. Відкрийте `/api/messages` (типово порт 3978) через публічну URL-адресу або тунель. 5. Установіть пакет застосунку Teams і запустіть gateway. -Мінімальна конфігурація: +Мінімальна конфігурація (client secret): ```json5 { @@ -64,19 +65,21 @@ openclaw plugins install ./path/to/local/msteams-plugin } ``` -Примітка: групові чати типово заблоковані (`channels.msteams.groupPolicy: "allowlist"`). Щоб дозволити відповіді в групах, задайте `channels.msteams.groupAllowFrom` (або використайте `groupPolicy: "open"`, щоб дозволити будь-якому учаснику, із перевіркою згадки). +Для production-розгортань розгляньте використання [federated authentication](#federated-authentication-certificate--managed-identity) (сертифікат або managed identity) замість client secret. + +Примітка: групові чати типово заблоковані (`channels.msteams.groupPolicy: "allowlist"`). Щоб дозволити відповіді в групах, задайте `channels.msteams.groupAllowFrom` (або використайте `groupPolicy: "open"`, щоб дозволити будь-якого учасника, із вимогою згадки). ## Цілі -- Спілкуватися з OpenClaw через DM, групові чати або канали Teams. -- Зберігати детерміновану маршрутизацію: відповіді завжди повертаються в той канал, з якого вони надійшли. +- Спілкуватися з OpenClaw через Teams DM, групові чати або канали. +- Зберігати детерміновану маршрутизацію: відповіді завжди повертаються в канал, з якого вони надійшли. - Типово використовувати безпечну поведінку каналів (потрібні згадки, якщо не налаштовано інакше). -## Записи конфігурації +## Запис у конфігурацію -Типово Microsoft Teams має дозвіл на запис оновлень конфігурації, ініційованих через `/config set|unset` (потрібно `commands.config: true`). +Типово Microsoft Teams має право записувати оновлення конфігурації, ініційовані через `/config set|unset` (потрібно `commands.config: true`). -Щоб вимкнути: +Вимкнути можна так: ```json5 { @@ -86,19 +89,19 @@ openclaw plugins install ./path/to/local/msteams-plugin ## Керування доступом (DM + групи) -**Доступ DM** +**Доступ у DM** - Типово: `channels.msteams.dmPolicy = "pairing"`. Невідомі відправники ігноруються до схвалення. -- У `channels.msteams.allowFrom` слід використовувати стабільні AAD object ID. -- UPN/відображувані імена можуть змінюватися; пряме зіставлення типово вимкнене й вмикається лише через `channels.msteams.dangerouslyAllowNameMatching: true`. -- Майстер може розв’язувати імена в ID через Microsoft Graph, якщо облікові дані це дозволяють. +- `channels.msteams.allowFrom` має використовувати стабільні AAD object ID. +- UPN/display name можуть змінюватися; пряме зіставлення типово вимкнене й вмикається лише через `channels.msteams.dangerouslyAllowNameMatching: true`. +- Майстер налаштування може зіставляти імена з ID через Microsoft Graph, якщо облікові дані це дозволяють. -**Доступ груп** +**Груповий доступ** - Типово: `channels.msteams.groupPolicy = "allowlist"` (заблоковано, доки ви не додасте `groupAllowFrom`). Використовуйте `channels.defaults.groupPolicy`, щоб перевизначити типове значення, якщо його не задано. -- `channels.msteams.groupAllowFrom` визначає, які відправники можуть активувати в групових чатах/каналах (з резервним переходом до `channels.msteams.allowFrom`). -- Установіть `groupPolicy: "open"`, щоб дозволити будь-якого учасника (згадка все одно типово обов’язкова). -- Щоб заборонити **всі канали**, установіть `channels.msteams.groupPolicy: "disabled"`. +- `channels.msteams.groupAllowFrom` визначає, які відправники можуть ініціювати дії в групових чатах/каналах (із fallback на `channels.msteams.allowFrom`). +- Встановіть `groupPolicy: "open"`, щоб дозволити будь-якого учасника (типово все одно потрібна згадка). +- Щоб дозволити **жодних каналів**, задайте `channels.msteams.groupPolicy: "disabled"`. Приклад: @@ -113,14 +116,14 @@ openclaw plugins install ./path/to/local/msteams-plugin } ``` -**Teams + список дозволених каналів** +**Teams + allowlist каналів** -- Обмежуйте відповіді в групах/каналах, перелічуючи команди й канали в `channels.msteams.teams`. -- Ключі мають використовувати стабільні team ID і conversation ID каналу. -- Коли `groupPolicy="allowlist"` і задано список дозволених teams, приймаються лише перелічені команди/канали (із перевіркою згадки). -- Майстер конфігурації приймає записи `Team/Channel` і зберігає їх для вас. -- Під час запуску OpenClaw розв’язує назви team/channel і списку дозволених користувачів в ID (коли це дозволяють права Graph) - і записує відповідність у журнали; нерозв’язані назви team/channel зберігаються як введені, але типово ігноруються для маршрутизації, якщо не ввімкнено `channels.msteams.dangerouslyAllowNameMatching: true`. +- Обмежуйте відповіді в групах/каналах, перелічивши teams і channels у `channels.msteams.teams`. +- Як ключі слід використовувати стабільні team ID і channel conversation ID. +- Коли `groupPolicy="allowlist"` і присутній teams allowlist, приймаються лише перелічені teams/channels (із вимогою згадки). +- Майстер налаштування приймає записи `Team/Channel` і зберігає їх за вас. +- Під час запуску OpenClaw зіставляє імена team/channel і user в allowlist з ID (коли це дозволяють дозволи Graph) + і записує це зіставлення в лог; невизначені імена team/channel зберігаються як введені, але типово ігноруються для маршрутизації, якщо не ввімкнено `channels.msteams.dangerouslyAllowNameMatching: true`. Приклад: @@ -144,49 +147,49 @@ openclaw plugins install ./path/to/local/msteams-plugin ## Як це працює 1. Переконайтеся, що плагін Microsoft Teams доступний. - - У поточних пакетних випусках OpenClaw він уже вбудований. - - У старіших/власних установленнях його можна додати вручну за допомогою команд вище. + - У поточних пакетованих релізах OpenClaw він уже вбудований. + - У старіших/власних встановленнях його можна додати вручну командами вище. 2. Створіть **Azure Bot** (App ID + secret + tenant ID). -3. Створіть **пакет застосунку Teams**, який посилається на бота та містить наведені нижче дозволи RSC. -4. Завантажте/установіть застосунок Teams у команду (або в особисту область для DM). -5. Налаштуйте `msteams` у `~/.openclaw/openclaw.json` (або через змінні середовища) і запустіть gateway. -6. Gateway типово слухає трафік вебхуків Bot Framework на `/api/messages`. +3. Зберіть **пакет застосунку Teams**, який посилається на бота та включає наведені нижче дозволи RSC. +4. Завантажте/встановіть застосунок Teams у команду (або в особисту область для DM). +5. Налаштуйте `msteams` у `~/.openclaw/openclaw.json` (або змінні середовища) і запустіть gateway. +6. Gateway типово слухає webhook-трафік Bot Framework на `/api/messages`. ## Налаштування Azure Bot (передумови) -Перш ніж налаштовувати OpenClaw, вам потрібно створити ресурс Azure Bot. +Перш ніж налаштовувати OpenClaw, потрібно створити ресурс Azure Bot. ### Крок 1: Створіть Azure Bot -1. Перейдіть на [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) +1. Перейдіть до [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) 2. Заповніть вкладку **Basics**: | Поле | Значення | | ------------------ | -------------------------------------------------------- | | **Bot handle** | Назва вашого бота, наприклад `openclaw-msteams` (має бути унікальною) | - | **Subscription** | Виберіть свою підписку Azure | + | **Subscription** | Виберіть вашу Azure subscription | | **Resource group** | Створіть нову або використайте наявну | | **Pricing tier** | **Free** для розробки/тестування | | **Type of App** | **Single Tenant** (рекомендовано — див. примітку нижче) | | **Creation type** | **Create new Microsoft App ID** | -> **Повідомлення про застарівання:** створення нових multi-tenant bot було застаріло після 2025-07-31. Для нових ботів використовуйте **Single Tenant**. +> **Повідомлення про припинення підтримки:** створення нових multi-tenant ботів було припинено після 2025-07-31. Для нових ботів використовуйте **Single Tenant**. -3. Натисніть **Review + create** → **Create** (зачекайте ~1-2 хвилини) +3. Натисніть **Review + create** → **Create** (зачекайте ~1–2 хвилини) ### Крок 2: Отримайте облікові дані -1. Перейдіть до свого ресурсу Azure Bot → **Configuration** +1. Перейдіть до ресурсу Azure Bot → **Configuration** 2. Скопіюйте **Microsoft App ID** → це ваш `appId` 3. Натисніть **Manage Password** → перейдіть до App Registration -4. У розділі **Certificates & secrets** → **New client secret** → скопіюйте **Value** → це ваш `appPassword` +4. У **Certificates & secrets** → **New client secret** → скопіюйте **Value** → це ваш `appPassword` 5. Перейдіть до **Overview** → скопіюйте **Directory (tenant) ID** → це ваш `tenantId` -### Крок 3: Налаштуйте кінцеву точку обміну повідомленнями +### Крок 3: Налаштуйте endpoint повідомлень 1. У Azure Bot → **Configuration** -2. Установіть **Messaging endpoint** на URL свого вебхука: - - Продуктивне середовище: `https://your-domain.com/api/messages` +2. Установіть **Messaging endpoint** на вашу webhook URL-адресу: + - Production: `https://your-domain.com/api/messages` - Локальна розробка: використовуйте тунель (див. [Локальна розробка](#local-development-tunneling) нижче) ### Крок 4: Увімкніть канал Teams @@ -195,6 +198,148 @@ openclaw plugins install ./path/to/local/msteams-plugin 2. Натисніть **Microsoft Teams** → Configure → Save 3. Прийміть Terms of Service +## Federated Authentication (сертифікат + Managed Identity) + +> Додано в 2026.3.24 + +Для production-розгортань OpenClaw підтримує **federated authentication** як безпечнішу альтернативу client secret. Доступні два методи: + +### Варіант A: автентифікація на основі сертифіката + +Використовуйте PEM-сертифікат, зареєстрований у реєстрації застосунку Entra ID. + +**Налаштування:** + +1. Згенеруйте або отримайте сертифікат (формат PEM із приватним ключем). +2. У Entra ID → App Registration → **Certificates & secrets** → **Certificates** → завантажте публічний сертифікат. + +**Конфігурація:** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + certificatePath: "/path/to/cert.pem", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Змінні середовища:** + +- `MSTEAMS_AUTH_TYPE=federated` +- `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem` + +### Варіант B: Azure Managed Identity + +Використовуйте Azure Managed Identity для автентифікації без пароля. Це ідеально підходить для розгортань в інфраструктурі Azure (AKS, App Service, Azure VM), де доступна managed identity. + +**Як це працює:** + +1. Bot pod/VM має managed identity (system-assigned або user-assigned). +2. **Federated identity credential** пов’язує managed identity з реєстрацією застосунку Entra ID. +3. Під час виконання OpenClaw використовує `@azure/identity`, щоб отримати токени з endpoint Azure IMDS (`169.254.169.254`). +4. Токен передається в Teams SDK для автентифікації бота. + +**Передумови:** + +- Інфраструктура Azure з увімкненою managed identity (AKS workload identity, App Service, VM) +- Створений federated identity credential у реєстрації застосунку Entra ID +- Мережевий доступ до IMDS (`169.254.169.254:80`) з pod/VM + +**Конфігурація (system-assigned managed identity):** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Конфігурація (user-assigned managed identity):** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + managedIdentityClientId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Змінні середовища:** + +- `MSTEAMS_AUTH_TYPE=federated` +- `MSTEAMS_USE_MANAGED_IDENTITY=true` +- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=` (лише для user-assigned) + +### Налаштування AKS Workload Identity + +Для розгортань AKS із використанням workload identity: + +1. **Увімкніть workload identity** у вашому кластері AKS. +2. **Створіть federated identity credential** у реєстрації застосунку Entra ID: + + ```bash + az ad app federated-credential create --id --parameters '{ + "name": "my-bot-workload-identity", + "issuer": "", + "subject": "system:serviceaccount::", + "audiences": ["api://AzureADTokenExchange"] + }' + ``` + +3. **Додайте анотацію до Kubernetes service account** з app client ID: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: my-bot-sa + annotations: + azure.workload.identity/client-id: "" + ``` + +4. **Додайте мітку pod** для ін’єкції workload identity: + + ```yaml + metadata: + labels: + azure.workload.identity/use: "true" + ``` + +5. **Переконайтеся в наявності мережевого доступу** до IMDS (`169.254.169.254`) — якщо ви використовуєте NetworkPolicy, додайте правило egress, яке дозволяє трафік до `169.254.169.254/32` на порт 80. + +### Порівняння типів автентифікації + +| Метод | Конфігурація | Переваги | Недоліки | +| -------------------- | ---------------------------------------------- | ----------------------------------- | -------------------------------------- | +| **Client secret** | `appPassword` | Просте налаштування | Потрібна ротація секретів, менш безпечно | +| **Certificate** | `authType: "federated"` + `certificatePath` | Немає спільного секрету в мережі | Додаткові витрати на керування сертифікатами | +| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | Без пароля, не потрібно керувати секретами | Потрібна інфраструктура Azure | + +**Типова поведінка:** якщо `authType` не задано, OpenClaw типово використовує автентифікацію через client secret. Наявні конфігурації продовжують працювати без змін. + ## Локальна розробка (тунелювання) Teams не може звертатися до `localhost`. Для локальної розробки використовуйте тунель: @@ -211,44 +356,44 @@ ngrok http 3978 ```bash tailscale funnel 3978 -# Використайте свій URL Tailscale funnel як messaging endpoint +# Використайте вашу URL-адресу Tailscale funnel як messaging endpoint ``` ## Teams Developer Portal (альтернатива) -Замість ручного створення ZIP із маніфестом ви можете використати [Teams Developer Portal](https://dev.teams.microsoft.com/apps): +Замість ручного створення manifest ZIP ви можете скористатися [Teams Developer Portal](https://dev.teams.microsoft.com/apps): 1. Натисніть **+ New app** -2. Заповніть основну інформацію (назва, опис, інформація про розробника) +2. Заповніть базову інформацію (назва, опис, інформація про розробника) 3. Перейдіть до **App features** → **Bot** -4. Виберіть **Enter a bot ID manually** і вставте App ID свого Azure Bot +4. Виберіть **Enter a bot ID manually** і вставте App ID вашого Azure Bot 5. Позначте області: **Personal**, **Team**, **Group Chat** 6. Натисніть **Distribute** → **Download app package** 7. У Teams: **Apps** → **Manage your apps** → **Upload a custom app** → виберіть ZIP -Часто це простіше, ніж редагувати JSON-маніфести вручну. +Часто це простіше, ніж вручну редагувати JSON-маніфести. ## Тестування бота -**Варіант A: Azure Web Chat (спочатку перевірте вебхук)** +**Варіант A: Azure Web Chat (спочатку перевірте webhook)** 1. У Azure Portal → ваш ресурс Azure Bot → **Test in Web Chat** 2. Надішліть повідомлення — ви маєте побачити відповідь -3. Це підтверджує, що ваша кінцева точка вебхука працює до налаштування Teams +3. Це підтверджує, що ваш endpoint webhook працює до налаштування Teams **Варіант B: Teams (після встановлення застосунку)** -1. Установіть застосунок Teams (sideload або каталог організації) +1. Установіть застосунок Teams (sideload або org catalog) 2. Знайдіть бота в Teams і надішліть DM -3. Перевірте журнали gateway на вхідну активність +3. Перевірте логи gateway на наявність вхідної activity ## Налаштування (мінімальне, лише текст) 1. **Переконайтеся, що плагін Microsoft Teams доступний** - - У поточних пакетних випусках OpenClaw він уже вбудований. - - У старіших/власних установленнях його можна додати вручну: + - У поточних пакетованих релізах OpenClaw він уже вбудований. + - У старіших/власних встановленнях його можна додати вручну: - З npm: `openclaw plugins install @openclaw/msteams` - - З локального checkout: `openclaw plugins install ./path/to/local/msteams-plugin` + - Із локального checkout: `openclaw plugins install ./path/to/local/msteams-plugin` 2. **Реєстрація бота** - Створіть Azure Bot (див. вище) і занотуйте: @@ -257,11 +402,11 @@ tailscale funnel 3978 - Tenant ID (single-tenant) 3. **Маніфест застосунку Teams** - - Додайте запис `bot` з `botId = `. + - Додайте запис `bot` із `botId = `. - Області: `personal`, `team`, `groupChat`. - - `supportsFiles: true` (потрібно для обробки файлів в особистій області). + - `supportsFiles: true` (обов’язково для обробки файлів в особистій області). - Додайте дозволи RSC (нижче). - - Створіть значки: `outline.png` (32x32) і `color.png` (192x192). + - Створіть іконки: `outline.png` (32x32) і `color.png` (192x192). - Заархівуйте всі три файли разом: `manifest.json`, `outline.png`, `color.png`. 4. **Налаштуйте OpenClaw** @@ -284,41 +429,46 @@ tailscale funnel 3978 - `MSTEAMS_APP_ID` - `MSTEAMS_APP_PASSWORD` - `MSTEAMS_TENANT_ID` + - `MSTEAMS_AUTH_TYPE` (необов’язково: `"secret"` або `"federated"`) + - `MSTEAMS_CERTIFICATE_PATH` (federated + certificate) + - `MSTEAMS_CERTIFICATE_THUMBPRINT` (необов’язково, не потрібен для автентифікації) + - `MSTEAMS_USE_MANAGED_IDENTITY` (federated + managed identity) + - `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` (лише для user-assigned MI) -5. **Кінцева точка бота** +5. **Endpoint бота** - Установіть Azure Bot Messaging Endpoint на: - - `https://:3978/api/messages` (або вибраний вами шлях/порт). + - `https://:3978/api/messages` (або ваш вибраний path/port). 6. **Запустіть gateway** - - Канал Teams запускається автоматично, коли доступний вбудований або встановлений вручну плагін і конфігурація `msteams` існує разом з обліковими даними. + - Канал Teams запускається автоматично, коли доступний вбудований або вручну встановлений плагін і існує конфігурація `msteams` з обліковими даними. -## Дія інформації про учасника +## Дія member info -OpenClaw надає для Microsoft Teams дію `member-info`, що працює через Graph, щоб агенти та автоматизації могли безпосередньо розв’язувати дані про учасників каналу (відображуване ім’я, email, роль) через Microsoft Graph. +OpenClaw надає для Microsoft Teams дію `member-info`, що працює через Graph, щоб агенти й автоматизації могли напряму отримувати дані про учасників каналу (display name, email, role) з Microsoft Graph. Вимоги: - Дозвіл RSC `Member.Read.Group` (уже є в рекомендованому маніфесті) -- Для міжкомандних пошуків: дозвіл Graph Application `User.Read.All` з admin consent +- Для lookups між командами: дозвіл Application `User.Read.All` у Graph з admin consent -Дія керується `channels.msteams.actions.memberInfo` (типово: увімкнено, коли доступні облікові дані Graph). +Дія керується через `channels.msteams.actions.memberInfo` (типово: увімкнена, коли доступні облікові дані Graph). ## Контекст історії - `channels.msteams.historyLimit` визначає, скільки останніх повідомлень каналу/групи загортається в prompt. -- Має резервний перехід до `messages.groupChat.historyLimit`. Установіть `0`, щоб вимкнути (типово 50). -- Отримана історія ланцюжка фільтрується списками дозволених відправників (`allowFrom` / `groupAllowFrom`), тому початкове наповнення контексту ланцюжка містить лише повідомлення від дозволених відправників. -- Контекст цитованих вкладень (`ReplyTo*`, похідний від HTML-відповідей Teams) наразі передається як отримано. -- Іншими словами, списки дозволених визначають, хто може активувати агента; сьогодні фільтруються лише окремі додаткові шляхи контексту. +- Використовується fallback до `messages.groupChat.historyLimit`. Установіть `0`, щоб вимкнути (типово 50). +- Отримана історія thread фільтрується за allowlist відправників (`allowFrom` / `groupAllowFrom`), тож заповнення контексту thread включає лише повідомлення від дозволених відправників. +- Цитований контекст вкладень (`ReplyTo*`, похідний від Teams reply HTML) зараз передається як отримано. +- Іншими словами, allowlist визначають, хто може активувати агента; сьогодні фільтруються лише окремі шляхи додаткового контексту. - Історію DM можна обмежити через `channels.msteams.dmHistoryLimit` (ходи користувача). Перевизначення для окремих користувачів: `channels.msteams.dms[""].historyLimit`. ## Поточні дозволи Teams RSC (маніфест) -Це **чинні resourceSpecific permissions** у нашому маніфесті застосунку Teams. Вони діють лише в межах команди/чату, де встановлено застосунок. +Це **наявні resourceSpecific permissions** у нашому маніфесті застосунку Teams. Вони застосовуються лише в тій команді/чаті, де встановлено застосунок. **Для каналів (область команди):** -- `ChannelMessage.Read.Group` (Application) - отримання всіх повідомлень каналу без @mention +- `ChannelMessage.Read.Group` (Application) - отримання тексту всіх повідомлень каналу без @mention - `ChannelMessage.Send.Group` (Application) - `Member.Read.Group` (Application) - `Owner.Read.Group` (Application) @@ -330,9 +480,9 @@ OpenClaw надає для Microsoft Teams дію `member-info`, що працю - `ChatMessage.Read.Chat` (Application) - отримання всіх повідомлень групового чату без @mention -## Приклад маніфесту Teams (з редагуванням) +## Приклад маніфесту Teams (із прихованими даними) -Мінімальний коректний приклад з обов’язковими полями. Замініть ID та URL. +Мінімальний, коректний приклад з обов’язковими полями. Замініть ID та URL. ```json5 { @@ -382,146 +532,151 @@ OpenClaw надає для Microsoft Teams дію `member-info`, що працю ### Застереження щодо маніфесту (обов’язкові поля) -- `bots[].botId` **має** точно збігатися з App ID Azure Bot. -- `webApplicationInfo.id` **має** точно збігатися з App ID Azure Bot. -- `bots[].scopes` мають включати поверхні, які ви плануєте використовувати (`personal`, `team`, `groupChat`). -- `bots[].supportsFiles: true` потрібне для обробки файлів в особистій області. -- `authorization.permissions.resourceSpecific` має включати читання/надсилання каналів, якщо ви хочете трафік каналу. +- `bots[].botId` **має** збігатися з Azure Bot App ID. +- `webApplicationInfo.id` **має** збігатися з Azure Bot App ID. +- `bots[].scopes` мають включати області, які ви плануєте використовувати (`personal`, `team`, `groupChat`). +- `bots[].supportsFiles: true` є обов’язковим для обробки файлів в особистій області. +- `authorization.permissions.resourceSpecific` має включати channel read/send, якщо ви хочете трафік каналів. ### Оновлення наявного застосунку Щоб оновити вже встановлений застосунок Teams (наприклад, щоб додати дозволи RSC): -1. Оновіть свій `manifest.json` новими налаштуваннями -2. **Збільште поле `version`** (наприклад, `1.0.0` → `1.1.0`) -3. **Повторно заархівуйте** маніфест зі значками (`manifest.json`, `outline.png`, `color.png`) +1. Оновіть ваш `manifest.json` новими налаштуваннями +2. **Збільшіть поле `version`** (наприклад, `1.0.0` → `1.1.0`) +3. **Повторно заархівуйте** маніфест з іконками (`manifest.json`, `outline.png`, `color.png`) 4. Завантажте новий zip: - - **Варіант A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → знайдіть свій застосунок → Upload new version + - **Варіант A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → знайдіть ваш застосунок → Upload new version - **Варіант B (Sideload):** У Teams → Apps → Manage your apps → Upload a custom app -5. **Для командних каналів:** перевстановіть застосунок у кожній команді, щоб нові дозволи набули чинності -6. **Повністю вийдіть і знову запустіть Teams** (а не просто закрийте вікно), щоб очистити кешовані метадані застосунку +5. **Для каналів команд:** повторно встановіть застосунок у кожній команді, щоб нові дозволи набули чинності +6. **Повністю закрийте й знову запустіть Teams** (а не просто закрийте вікно), щоб очистити кешовані метадані застосунку -## Можливості: лише RSC проти Graph +## Можливості: лише RSC чи Graph -### З **лише Teams RSC** (застосунок установлено, без дозволів Graph API) +### З **лише Teams RSC** (застосунок встановлено, без дозволів Graph API) Працює: - Читання **текстового** вмісту повідомлень каналу. - Надсилання **текстового** вмісту повідомлень каналу. -- Отримання **особистих (DM)** файлових вкладень. +- Отримання вкладень файлів у **особистих повідомленнях (DM)**. НЕ працює: -- **Зображення чи вміст файлів** у каналах/групах (payload містить лише HTML-заглушку). +- **Вміст зображень або файлів** у каналах/групах (payload містить лише HTML-заглушку). - Завантаження вкладень, що зберігаються в SharePoint/OneDrive. -- Читання історії повідомлень (поза поточною подією вебхука). +- Читання історії повідомлень (поза межами live webhook event). ### З **Teams RSC + дозволами Microsoft Graph Application** Додається: -- Завантаження розміщеного вмісту (зображення, вставлені в повідомлення). -- Завантаження файлових вкладень, що зберігаються в SharePoint/OneDrive. +- Завантаження hosted content (зображень, вставлених у повідомлення). +- Завантаження вкладень файлів, що зберігаються в SharePoint/OneDrive. - Читання історії повідомлень каналів/чатів через Graph. -### RSC проти Graph API +### RSC і Graph API -| Можливість | Дозволи RSC | Graph API | -| ----------------------- | -------------------- | ------------------------------------ | -| **Повідомлення в реальному часі** | Так (через вебхук) | Ні (лише опитування) | -| **Історичні повідомлення** | Ні | Так (можна запитувати історію) | -| **Складність налаштування** | Лише маніфест застосунку | Потрібні admin consent + потік токенів | -| **Працює офлайн** | Ні (має бути запущено) | Так (можна запитувати будь-коли) | +| Можливість | Дозволи RSC | Graph API | +| ----------------------- | -------------------- | ----------------------------------- | +| **Повідомлення в реальному часі** | Так (через webhook) | Ні (лише polling) | +| **Історичні повідомлення** | Ні | Так (можна отримувати історію) | +| **Складність налаштування** | Лише маніфест застосунку | Потрібні admin consent + token flow | +| **Працює офлайн** | Ні (має бути запущено) | Так (можна запитувати будь-коли) | -**Підсумок:** RSC призначений для прослуховування в реальному часі; Graph API — для історичного доступу. Щоб надолужувати пропущені повідомлення під час офлайну, вам потрібен Graph API з `ChannelMessage.Read.All` (потрібен admin consent). +**Підсумок:** RSC потрібен для прослуховування в реальному часі; Graph API — для історичного доступу. Щоб надолужувати пропущені повідомлення під час офлайн-режиму, потрібен Graph API з `ChannelMessage.Read.All` (потрібен admin consent). -## Медіа + історія з Graph (потрібно для каналів) +## Медіа й історія з Graph (обов’язково для каналів) Якщо вам потрібні зображення/файли в **каналах** або ви хочете отримувати **історію повідомлень**, потрібно ввімкнути дозволи Microsoft Graph і надати admin consent. -1. У Entra ID (Azure AD) **App Registration** додайте дозволи Microsoft Graph **Application permissions**: +1. У **App Registration** Entra ID (Azure AD) додайте **Application permissions** Microsoft Graph: - `ChannelMessage.Read.All` (вкладення каналів + історія) - `Chat.Read.All` або `ChatMessage.Read.All` (групові чати) 2. **Надайте admin consent** для tenant. -3. Збільште **версію маніфесту** застосунку Teams, повторно завантажте його та **перевстановіть застосунок у Teams**. -4. **Повністю вийдіть і знову запустіть Teams**, щоб очистити кешовані метадані застосунку. +3. Збільшіть **версію маніфесту** застосунку Teams, повторно завантажте його й **повторно встановіть застосунок у Teams**. +4. **Повністю закрийте й знову запустіть Teams**, щоб очистити кешовані метадані застосунку. -**Додатковий дозвіл для згадок користувачів:** @mentions користувачів працюють одразу для користувачів у розмові. Однак якщо ви хочете динамічно шукати й згадувати користувачів, які **не перебувають у поточній розмові**, додайте дозвіл `User.Read.All` (Application) і надайте admin consent. +**Додатковий дозвіл для згадок користувачів:** @mentions користувачів працюють одразу для користувачів у поточній розмові. Однак якщо ви хочете динамічно шукати й згадувати користувачів, які **не перебувають у поточній розмові**, додайте дозвіл `User.Read.All` (Application) і надайте admin consent. ## Відомі обмеження -### Тайм-аути вебхуків +### Тайм-аути webhook -Teams доставляє повідомлення через HTTP-вебхук. Якщо обробка займає надто багато часу (наприклад, повільні відповіді LLM), ви можете побачити: +Teams доставляє повідомлення через HTTP webhook. Якщо обробка триває надто довго (наприклад, через повільні відповіді LLM), ви можете побачити: - тайм-аути gateway -- повторну спробу надсилання повідомлення з боку Teams (що спричиняє дублікати) +- повторні спроби доставки повідомлення з боку Teams (що спричиняє дублікати) - втрачені відповіді -OpenClaw вирішує це, швидко повертаючи відповідь і надсилаючи повідомлення проактивно, але дуже повільні відповіді все одно можуть спричиняти проблеми. +OpenClaw обробляє це, швидко повертаючи відповідь і надсилаючи відповіді проактивно, але дуже повільні відповіді все одно можуть спричиняти проблеми. ### Форматування -Markdown у Teams обмеженіший, ніж у Slack або Discord: +Markdown у Teams більш обмежений, ніж у Slack чи Discord: - Базове форматування працює: **жирний**, _курсив_, `code`, посилання -- Складний Markdown (таблиці, вкладені списки) може відображатися некоректно -- Adaptive Cards підтримуються для Polls і довільного надсилання карток (див. нижче) +- Складний markdown (таблиці, вкладені списки) може відображатися некоректно +- Adaptive Cards підтримуються для опитувань і довільного надсилання карток (див. нижче) ## Конфігурація -Основні параметри (спільні шаблони каналів див. у `/gateway/configuration`): +Ключові параметри (спільні шаблони каналів див. у `/gateway/configuration`): - `channels.msteams.enabled`: увімкнути/вимкнути канал. - `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: облікові дані бота. - `channels.msteams.webhook.port` (типово `3978`) - `channels.msteams.webhook.path` (типово `/api/messages`) - `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (типово: pairing) -- `channels.msteams.allowFrom`: список дозволених для DM (рекомендовано AAD object ID). Майстер під час налаштування розв’язує імена в ID, коли доступний Graph. -- `channels.msteams.dangerouslyAllowNameMatching`: аварійний перемикач, який знову вмикає зіставлення за змінними UPN/відображуваними іменами та пряму маршрутизацію за назвами team/channel. -- `channels.msteams.textChunkLimit`: розмір вихідного текстового блока. -- `channels.msteams.chunkMode`: `length` (типово) або `newline` для розбиття за порожніми рядками (межі абзаців) перед розбиттям за довжиною. -- `channels.msteams.mediaAllowHosts`: список дозволених хостів для вхідних вкладень (типово домени Microsoft/Teams). -- `channels.msteams.mediaAuthAllowHosts`: список дозволених хостів для додавання заголовків Authorization під час повторних спроб медіа (типово хости Graph + Bot Framework). +- `channels.msteams.allowFrom`: allowlist для DM (рекомендовано AAD object ID). Майстер під час налаштування зіставляє імена з ID, коли доступний доступ до Graph. +- `channels.msteams.dangerouslyAllowNameMatching`: аварійний перемикач для повторного ввімкнення зіставлення за змінними UPN/display name і прямої маршрутизації за назвами team/channel. +- `channels.msteams.textChunkLimit`: розмір фрагмента вихідного тексту. +- `channels.msteams.chunkMode`: `length` (типово) або `newline`, щоб розбивати за порожніми рядками (межами абзаців) перед розбиттям за довжиною. +- `channels.msteams.mediaAllowHosts`: allowlist хостів для вхідних вкладень (типово домени Microsoft/Teams). +- `channels.msteams.mediaAuthAllowHosts`: allowlist для додавання заголовків Authorization під час повторних спроб завантаження медіа (типово хости Graph + Bot Framework). - `channels.msteams.requireMention`: вимагати @mention у каналах/групах (типово true). - `channels.msteams.replyStyle`: `thread | top-level` (див. [Стиль відповіді](#reply-style-threads-vs-posts)). - `channels.msteams.teams..replyStyle`: перевизначення для окремої команди. - `channels.msteams.teams..requireMention`: перевизначення для окремої команди. -- `channels.msteams.teams..tools`: типові перевизначення політики інструментів для окремої команди (`allow`/`deny`/`alsoAllow`), що використовуються, коли перевизначення каналу відсутнє. -- `channels.msteams.teams..toolsBySender`: типові перевизначення політики інструментів для окремої команди й окремого відправника (підтримується шаблон `"*"`). +- `channels.msteams.teams..tools`: типові перевизначення політики інструментів для окремої команди (`allow`/`deny`/`alsoAllow`), які використовуються, якщо для каналу немає перевизначення. +- `channels.msteams.teams..toolsBySender`: типові перевизначення політики інструментів для окремої команди й відправника (`"*"` wildcard підтримується). - `channels.msteams.teams..channels..replyStyle`: перевизначення для окремого каналу. - `channels.msteams.teams..channels..requireMention`: перевизначення для окремого каналу. - `channels.msteams.teams..channels..tools`: перевизначення політики інструментів для окремого каналу (`allow`/`deny`/`alsoAllow`). -- `channels.msteams.teams..channels..toolsBySender`: перевизначення політики інструментів для окремого каналу й окремого відправника (підтримується шаблон `"*"`). +- `channels.msteams.teams..channels..toolsBySender`: перевизначення політики інструментів для окремого каналу й відправника (`"*"` wildcard підтримується). - Ключі `toolsBySender` мають використовувати явні префікси: `id:`, `e164:`, `username:`, `name:` (застарілі ключі без префікса все ще зіставляються лише з `id:`). - `channels.msteams.actions.memberInfo`: увімкнути або вимкнути дію member info через Graph (типово: увімкнено, коли доступні облікові дані Graph). -- `channels.msteams.sharePointSiteId`: ID сайту SharePoint для вивантаження файлів у групових чатах/каналах (див. [Надсилання файлів у групових чатах](#sending-files-in-group-chats)). +- `channels.msteams.authType`: тип автентифікації — `"secret"` (типово) або `"federated"`. +- `channels.msteams.certificatePath`: шлях до файлу PEM-сертифіката (federated + certificate auth). +- `channels.msteams.certificateThumbprint`: відбиток сертифіката (необов’язково, не потрібен для автентифікації). +- `channels.msteams.useManagedIdentity`: увімкнути автентифікацію через managed identity (режим federated). +- `channels.msteams.managedIdentityClientId`: client ID для user-assigned managed identity. +- `channels.msteams.sharePointSiteId`: SharePoint site ID для надсилання файлів у групових чатах/каналах (див. [Надсилання файлів у групових чатах](#sending-files-in-group-chats)). ## Маршрутизація та сесії -- Ключі сесій дотримуються стандартного формату агента (див. [/concepts/session](/concepts/session)): +- Ключі сесій відповідають стандартному формату агента (див. [/concepts/session](/uk/concepts/session)): - Прямі повідомлення використовують основну сесію (`agent::`). - - Повідомлення каналів/груп використовують ID розмови: + - Повідомлення каналу/групи використовують conversation id: - `agent::msteams:channel:` - `agent::msteams:group:` -## Стиль відповіді: ланцюжки проти дописів +## Стиль відповіді: threads чи posts -Нещодавно Teams запровадив два стилі інтерфейсу каналів поверх однієї базової моделі даних: +Teams нещодавно запровадив два стилі UI каналів поверх тієї самої базової моделі даних: | Стиль | Опис | Рекомендований `replyStyle` | | ----------------------- | --------------------------------------------------------- | --------------------------- | -| **Posts** (класичний) | Повідомлення відображаються як картки, а відповіді йдуть ланцюжком під ними | `thread` (типово) | -| **Threads** (як у Slack) | Повідомлення йдуть лінійно, більше схоже на Slack | `top-level` | +| **Posts** (класичний) | Повідомлення відображаються як картки з thread-відповідями під ними | `thread` (типово) | +| **Threads** (як у Slack) | Повідомлення йдуть лінійно, більше схоже на Slack | `top-level` | -**Проблема:** API Teams не повідомляє, який стиль UI використовує канал. Якщо використати неправильний `replyStyle`: +**Проблема:** API Teams не показує, який стиль UI використовує канал. Якщо використати неправильний `replyStyle`: -- `thread` у каналі стилю Threads → відповіді виглядають незграбно вкладеними -- `top-level` у каналі стилю Posts → відповіді відображаються як окремі дописи верхнього рівня, а не в ланцюжку +- `thread` у каналі зі стилем Threads → відповіді виглядатимуть незграбно вкладеними +- `top-level` у каналі зі стилем Posts → відповіді відображатимуться як окремі повідомлення верхнього рівня, а не в thread -**Рішення:** налаштуйте `replyStyle` для кожного каналу залежно від того, як налаштований канал: +**Рішення:** налаштуйте `replyStyle` для кожного каналу залежно від того, як налаштовано канал: ```json5 { @@ -546,37 +701,37 @@ Markdown у Teams обмеженіший, ніж у Slack або Discord: **Поточні обмеження:** -- **DM:** зображення та файлові вкладення працюють через файлові API ботів Teams. -- **Канали/групи:** вкладення живуть у сховищі M365 (SharePoint/OneDrive). Payload вебхука містить лише HTML-заглушку, а не реальні байти файлу. **Для завантаження вкладень каналів потрібні дозволи Graph API**. -- Для явних надсилань, де файл є основним, використовуйте `action=upload-file` з `media` / `filePath` / `path`; необов’язкове `message` стає супровідним текстом/коментарем, а `filename` перевизначає назву вивантаженого файлу. +- **DM:** зображення та вкладення файлів працюють через Teams bot file API. +- **Канали/групи:** вкладення зберігаються в сховищі M365 (SharePoint/OneDrive). Payload webhook містить лише HTML-заглушку, а не фактичні байти файлу. **Для завантаження вкладень каналів потрібні дозволи Graph API**. +- Для явних надсилань, що починаються з файлу, використовуйте `action=upload-file` з `media` / `filePath` / `path`; необов’язковий `message` стає супровідним текстом/коментарем, а `filename` перевизначає ім’я завантаженого файлу. -Без дозволів Graph повідомлення каналу із зображеннями отримуватимуться лише як текст (вміст зображення боту недоступний). +Без дозволів Graph повідомлення каналів із зображеннями отримуватимуться лише як текст (вміст зображення недоступний боту). Типово OpenClaw завантажує медіа лише з хостів Microsoft/Teams. Перевизначте це через `channels.msteams.mediaAllowHosts` (використайте `["*"]`, щоб дозволити будь-який хост). -Заголовки Authorization додаються лише для хостів у `channels.msteams.mediaAuthAllowHosts` (типово хости Graph + Bot Framework). Тримайте цей список суворим (уникайте багатокористувацьких суфіксів). +Заголовки Authorization додаються лише для хостів у `channels.msteams.mediaAuthAllowHosts` (типово хости Graph + Bot Framework). Тримайте цей список суворим (уникайте multi-tenant суфіксів). ## Надсилання файлів у групових чатах -Боти можуть надсилати файли в DM через потік FileConsentCard (вбудовано). Однак **надсилання файлів у групових чатах/каналах** потребує додаткового налаштування: +Боти можуть надсилати файли в DM за допомогою потоку FileConsentCard (вбудовано). Однак **надсилання файлів у групових чатах/каналах** потребує додаткового налаштування: -| Контекст | Як надсилаються файли | Потрібне налаштування | -| ------------------------ | ----------------------------------------- | ----------------------------------------------- | -| **DM** | FileConsentCard → користувач підтверджує → бот вивантажує | Працює одразу | -| **Групові чати/канали** | Вивантаження в SharePoint → посилання для доступу | Потрібні `sharePointSiteId` + дозволи Graph | -| **Зображення (будь-який контекст)** | Вбудоване кодування Base64 | Працює одразу | +| Контекст | Як надсилаються файли | Потрібне налаштування | +| ------------------------ | ------------------------------------------ | -------------------------------------------------- | +| **DM** | FileConsentCard → користувач підтверджує → бот завантажує | Працює одразу | +| **Групові чати/канали** | Завантаження до SharePoint → посилання для спільного доступу | Потрібні `sharePointSiteId` + дозволи Graph | +| **Зображення (будь-який контекст)** | Вбудовано як Base64 | Працює одразу | -### Чому для групових чатів потрібен SharePoint +### Чому груповим чатам потрібен SharePoint -Боти не мають особистого диска OneDrive (кінцева точка Graph API `/me/drive` не працює для application identities). Щоб надсилати файли в групових чатах/каналах, бот вивантажує їх на **сайт SharePoint** і створює посилання для доступу. +Боти не мають особистого диска OneDrive (endpoint Graph API `/me/drive` не працює для application identities). Щоб надсилати файли в групових чатах/каналах, бот завантажує їх на **сайт SharePoint** і створює посилання для спільного доступу. ### Налаштування -1. **Додайте дозволи Graph API** у Entra ID (Azure AD) → App Registration: - - `Sites.ReadWrite.All` (Application) - вивантаження файлів у SharePoint - - `Chat.Read.All` (Application) - необов’язково, вмикає посилання для доступу на рівні користувача +1. **Додайте дозволи Graph API** в Entra ID (Azure AD) → App Registration: + - `Sites.ReadWrite.All` (Application) - завантаження файлів у SharePoint + - `Chat.Read.All` (Application) - необов’язково, вмикає посилання спільного доступу для окремих користувачів 2. **Надайте admin consent** для tenant. -3. **Отримайте ID свого сайту SharePoint:** +3. **Отримайте SharePoint site ID:** ```bash # Через Graph Explorer або curl із дійсним токеном: @@ -605,40 +760,40 @@ Markdown у Teams обмеженіший, ніж у Slack або Discord: ### Поведінка спільного доступу -| Дозвіл | Поведінка спільного доступу | -| --------------------------------------- | -------------------------------------------------------- | -| `Sites.ReadWrite.All` лише | Посилання спільного доступу на всю організацію (доступне будь-кому в org) | -| `Sites.ReadWrite.All` + `Chat.Read.All` | Посилання спільного доступу на рівні користувача (доступне лише учасникам чату) | +| Дозвіл | Поведінка спільного доступу | +| ----------------------------------------- | -------------------------------------------------------- | +| `Sites.ReadWrite.All` лише | Посилання спільного доступу для всієї організації (доступ має будь-хто в організації) | +| `Sites.ReadWrite.All` + `Chat.Read.All` | Посилання спільного доступу для окремих користувачів (доступ мають лише учасники чату) | -Спільний доступ на рівні користувача безпечніший, оскільки файл доступний лише учасникам чату. Якщо дозвіл `Chat.Read.All` відсутній, бот повертається до спільного доступу на всю організацію. +Спільний доступ для окремих користувачів безпечніший, оскільки лише учасники чату можуть отримати доступ до файлу. Якщо дозволу `Chat.Read.All` немає, бот повертається до спільного доступу для всієї організації. -### Поведінка резервного переходу +### Поведінка fallback | Сценарій | Результат | | ------------------------------------------------- | --------------------------------------------------- | -| Груповий чат + файл + налаштовано `sharePointSiteId` | Вивантаження в SharePoint, надсилання посилання для доступу | -| Груповий чат + файл + без `sharePointSiteId` | Спроба вивантаження в OneDrive (може не вдатися), надсилається лише текст | +| Груповий чат + файл + налаштовано `sharePointSiteId` | Завантаження у SharePoint, надсилання посилання спільного доступу | +| Груповий чат + файл + без `sharePointSiteId` | Спроба завантаження в OneDrive (може не вдатися), надсилається лише текст | | Особистий чат + файл | Потік FileConsentCard (працює без SharePoint) | -| Будь-який контекст + зображення | Вбудоване кодування Base64 (працює без SharePoint) | +| Будь-який контекст + зображення | Вбудовано як Base64 (працює без SharePoint) | -### Де зберігаються файли +### Місце зберігання файлів -Вивантажені файли зберігаються в папці `/OpenClawShared/` у типовій бібліотеці документів налаштованого сайту SharePoint. +Завантажені файли зберігаються в папці `/OpenClawShared/` у стандартній бібліотеці документів налаштованого сайту SharePoint. -## Polls (Adaptive Cards) +## Опитування (Adaptive Cards) -OpenClaw надсилає Polls у Teams як Adaptive Cards (власного API для опитувань у Teams немає). +OpenClaw надсилає опитування Teams як Adaptive Cards (вбудованого Teams poll API немає). - CLI: `openclaw message poll --channel msteams --target conversation: ...` - Голоси записуються gateway у `~/.openclaw/msteams-polls.json`. - Щоб записувати голоси, gateway має залишатися онлайн. -- Polls поки що не публікують підсумки результатів автоматично (за потреби переглядайте файл сховища). +- Опитування поки що не публікують підсумки результатів автоматично (за потреби перевіряйте файл сховища). ## Adaptive Cards (довільні) Надсилайте будь-який JSON Adaptive Card користувачам або розмовам Teams за допомогою інструмента `message` або CLI. -Параметр `card` приймає JSON-об’єкт Adaptive Card. Коли задано `card`, текст повідомлення є необов’язковим. +Параметр `card` приймає JSON-об’єкт Adaptive Card. Коли передано `card`, текст повідомлення необов’язковий. **Інструмент агента:** @@ -663,7 +818,7 @@ openclaw message send --channel msteams \ --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}' ``` -Приклади й схему карток див. у [документації Adaptive Cards](https://adaptivecards.io/). Докладніше про формати цілей див. у [Формати цілей](#target-formats) нижче. +Див. [документацію Adaptive Cards](https://adaptivecards.io/) щодо схеми карток і прикладів. Докладніше про формати цілей див. у [Формати цілей](#target-formats) нижче. ## Формати цілей @@ -674,7 +829,7 @@ openclaw message send --channel msteams \ | Користувач (за ID) | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | | Користувач (за ім’ям) | `user:` | `user:John Smith` (потрібен Graph API) | | Група/канал | `conversation:` | `conversation:19:abc123...@thread.tacv2` | -| Група/канал (сирий) | `` | `19:abc123...@thread.tacv2` (якщо містить `@thread`) | +| Група/канал (raw) | `` | `19:abc123...@thread.tacv2` (якщо містить `@thread`) | **Приклади CLI:** @@ -682,7 +837,7 @@ openclaw message send --channel msteams \ # Надіслати користувачу за ID openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello" -# Надіслати користувачу за відображуваним ім’ям (запускає пошук через Graph API) +# Надіслати користувачу за display name (викликає lookup через Graph API) openclaw message send --channel msteams --target "user:John Smith" --message "Hello" # Надіслати в груповий чат або канал @@ -717,23 +872,23 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread. } ``` -Примітка: без префікса `user:` імена типово трактуються як розв’язання групи/команди. Завжди використовуйте `user:`, коли націлюєтеся на людей за відображуваним ім’ям. +Примітка: без префікса `user:` імена типово трактуються як цілі групи/команди. Завжди використовуйте `user:`, коли адресуєте людей за display name. ## Проактивні повідомлення -- Проактивні повідомлення можливі лише **після** того, як користувач уже взаємодіяв, оскільки саме тоді ми зберігаємо посилання на розмову. -- Параметри `dmPolicy` і перевірку списку дозволених див. у `/gateway/configuration`. +- Проактивні повідомлення можливі лише **після** взаємодії користувача, оскільки саме тоді ми зберігаємо посилання на розмову. +- Див. `/gateway/configuration` щодо `dmPolicy` і обмеження через allowlist. -## ID команд і каналів (типова пастка) +## ID команди та каналу (поширена пастка) -Параметр запиту `groupId` в URL Teams **НЕ** є team ID, який використовується для конфігурації. Витягуйте ID зі шляху URL: +Параметр запиту `groupId` в URL Teams — це **НЕ** team ID, який використовується для конфігурації. Натомість витягайте ID зі шляху URL: **URL команди:** ``` https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=... └────────────────────────────┘ - Team ID (URL-декодуйте це) + Team ID (виконайте URL-декодування) ``` **URL каналу:** @@ -741,7 +896,7 @@ https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?gro ``` https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=... └─────────────────────────┘ - Channel ID (URL-декодуйте це) + Channel ID (виконайте URL-декодування) ``` **Для конфігурації:** @@ -754,57 +909,57 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr Боти мають обмежену підтримку в приватних каналах: -| Можливість | Стандартні канали | Приватні канали | -| --------------------------- | ----------------- | --------------------- | -| Установлення бота | Так | Обмежено | -| Повідомлення в реальному часі (вебхук) | Так | Може не працювати | -| Дозволи RSC | Так | Можуть поводитися інакше | -| @mentions | Так | Якщо бот доступний | -| Історія через Graph API | Так | Так (із дозволами) | +| Функція | Стандартні канали | Приватні канали | +| ---------------------------- | ----------------- | -------------------- | +| Встановлення бота | Так | Обмежено | +| Повідомлення в реальному часі (webhook) | Так | Може не працювати | +| Дозволи RSC | Так | Можуть поводитися інакше | +| @mentions | Так | Якщо бот доступний | +| Історія через Graph API | Так | Так (із дозволами) | -**Обхідні шляхи, якщо приватні канали не працюють:** +**Обхідні варіанти, якщо приватні канали не працюють:** 1. Використовуйте стандартні канали для взаємодії з ботом 2. Використовуйте DM — користувачі завжди можуть писати боту напряму 3. Використовуйте Graph API для історичного доступу (потрібен `ChannelMessage.Read.All`) -## Усунення проблем +## Усунення несправностей -### Типові проблеми +### Поширені проблеми -- **Зображення не показуються в каналах:** бракує дозволів Graph або admin consent. Перевстановіть застосунок Teams і повністю закрийте/відкрийте Teams. -- **Немає відповідей у каналі:** типово потрібні згадки; установіть `channels.msteams.requireMention=false` або налаштуйте для окремої команди/каналу. -- **Невідповідність версій (Teams усе ще показує старий маніфест):** видаліть і знову додайте застосунок та повністю перезапустіть Teams для оновлення. -- **401 Unauthorized від вебхука:** це очікувано під час ручного тестування без Azure JWT — означає, що кінцева точка доступна, але автентифікація не пройшла. Для коректного тестування використовуйте Azure Web Chat. +- **У каналах не відображаються зображення:** бракує дозволів Graph або admin consent. Повторно встановіть застосунок Teams і повністю закрийте/знову відкрийте Teams. +- **Немає відповідей у каналі:** типово потрібні згадки; установіть `channels.msteams.requireMention=false` або налаштуйте це для конкретної команди/каналу. +- **Невідповідність версій (Teams все ще показує старий маніфест):** видаліть і знову додайте застосунок та повністю перезапустіть Teams для оновлення. +- **401 Unauthorized від webhook:** очікувано під час ручного тестування без Azure JWT — це означає, що endpoint доступний, але автентифікація не пройдена. Для коректної перевірки використовуйте Azure Web Chat. ### Помилки завантаження маніфесту -- **"Icon file cannot be empty":** маніфест посилається на файли значків розміром 0 байт. Створіть коректні значки PNG (`outline.png` 32x32, `color.png` 192x192). -- **"webApplicationInfo.Id already in use":** застосунок усе ще встановлений в іншій команді/чаті. Спочатку знайдіть і видаліть його або зачекайте 5-10 хвилин на поширення змін. -- **"Something went wrong" під час завантаження:** натомість завантажуйте через [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), відкрийте DevTools браузера (F12) → вкладка Network і перевірте тіло відповіді, щоб побачити фактичну помилку. +- **"Icon file cannot be empty":** маніфест посилається на файли іконок розміром 0 байт. Створіть коректні PNG-іконки (`outline.png` 32x32, `color.png` 192x192). +- **"webApplicationInfo.Id already in use":** застосунок усе ще встановлений в іншій команді/чаті. Спочатку знайдіть і видаліть його або зачекайте 5–10 хвилин на поширення змін. +- **"Something went wrong" під час завантаження:** натомість виконайте завантаження через [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), відкрийте DevTools браузера (F12) → вкладка Network і перевірте тіло відповіді, щоб побачити фактичну помилку. - **Не вдається sideload:** спробуйте "Upload an app to your org's app catalog" замість "Upload a custom app" — це часто обходить обмеження sideload. ### Дозволи RSC не працюють 1. Переконайтеся, що `webApplicationInfo.id` точно збігається з App ID вашого бота 2. Повторно завантажте застосунок і перевстановіть його в команді/чаті -3. Перевірте, чи адміністратор вашої org не заблокував дозволи RSC +3. Перевірте, чи адміністратор вашої організації не заблокував дозволи RSC 4. Підтвердьте, що ви використовуєте правильну область: `ChannelMessage.Read.Group` для команд, `ChatMessage.Read.Chat` для групових чатів ## Посилання - [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - посібник із налаштування Azure Bot -- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - створення/керування застосунками Teams -- [Схема маніфесту застосунку Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) -- [Отримання повідомлень каналу через RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) -- [Довідник дозволів RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) -- [Обробка файлів ботом Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (для каналу/групи потрібен Graph) -- [Проактивні повідомлення](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) +- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - створення й керування застосунками Teams +- [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) +- [Receive channel messages with RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) +- [RSC permissions reference](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) +- [Teams bot file handling](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (для каналу/групи потрібен Graph) +- [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) ## Пов’язане -- [Огляд каналів](/channels) — усі підтримувані канали -- [Парування](/channels/pairing) — автентифікація DM і потік парування -- [Групи](/channels/groups) — поведінка групового чату й перевірка згадки -- [Маршрутизація каналів](/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Безпека](/gateway/security) — модель доступу та зміцнення безпеки +- [Огляд каналів](/uk/channels) — усі підтримувані канали +- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing +- [Групи](/uk/channels/groups) — поведінка групового чату та обмеження за згадками +- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень +- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту