> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/ja/build/choose-channel/line-works.md).

# 会話プラットフォーム連携：LINE WORKS

LINE WORKS 対話プラットフォームとの連携：Developer Console で Client App と Bot を作成し、Service Account と Bot Secret を取得、Callback URL を設定して有効化します。

LINE WORKS は LINE の企業向けコミュニケーションツールです。連携すると、従業員は普段使っている LINE WORKS からそのまま Agent と対話でき、別のシステムを開く必要がありません。1 対 1 のダイレクトメッセージとグループ対話の両方に対応しています。

{% hint style="info" %}
LINE WORKS と LINE は別のプラットフォームで、認証情報も設定方法もまったく異なります。一般ユーザー向けの LINE 公式アカウントを連携する場合は、[対話プラットフォーム連携：LINE](/maiagent-user-guide/ja/build/choose-channel/line.md) をご覧ください。
{% endhint %}

## 連携前の確認 <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

* [MaiAgent プラットフォーム](https://admin.maiagent.ai/)上で「AI アシスタント」をすでに作成済みであること
* LINE WORKS の管理者権限を持っていること（[Admin 管理画面](https://admin.worksmobile.com/)にログインできること）
* [LINE WORKS Developer Console](https://developers.worksmobile.com/) にアクセスできること

{% hint style="warning" %}
この連携には 6 つの認証情報が必要で、**チャネル作成後は認証情報を変更できません**。先にステップ 1 とステップ 2 を完了して 6 つの認証情報をすべて揃えてから、ステップ 3 に進んでください。
{% endhint %}

***

## ステップ 1：Client App を作成して Service Account を取得する <a href="#step-create-client-app" id="step-create-client-app"></a>

### 1. Developer Console の ClientApp ページを開く <a href="#step-go-to-clientapp" id="step-go-to-clientapp"></a>

[LINE WORKS Developer Console](https://developers.worksmobile.com/) にログインし、左側メニューで <mark style="color:blue;">API</mark> → <mark style="color:blue;">ClientApp</mark> をクリックして、<mark style="color:blue;">Add client app</mark> をクリックし、App を作成します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-0d792c7b976ddc8399f167d41ee79992a0caa192%2Flineworks-console-clientapp-list.png?alt=media" alt="Developer Console の ClientApp 一覧ページ"><figcaption><p>Developer Console → API → ClientApp</p></figcaption></figure>

### 2. 4 つの認証情報を取得する <a href="#step-get-app-credentials" id="step-get-app-credentials"></a>

該当 App の詳細ページを開き、次の 4 項目を取得します。

| 認証情報                | Console 上の場所                                                                           |
| ------------------- | -------------------------------------------------------------------------------------- |
| **Client ID**       | <mark style="color:blue;">Client ID</mark> 欄                                           |
| **Client Secret**   | <mark style="color:blue;">Client Secret</mark> 欄                                       |
| **Service Account** | <mark style="color:blue;">Service Account</mark> 欄。形式は `xxxxx.serviceaccount@お使いのドメイン` |
| **Private Key**     | <mark style="color:blue;">Private Key</mark> ブロック。作成時に `.key` ファイルをダウンロードできます          |

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-22a6737d44f3e40f43a4b72a81fc4568dc81dfc8%2Flineworks-console-clientapp-detail.png?alt=media" alt="Client ID、Client Secret、OAuth Scopes、Service Account、Private Key を含む Client App の詳細ページ"><figcaption><p>Client App の詳細ページ — 4 つの認証情報と OAuth Scopes がこのページにあります</p></figcaption></figure>

### 3. OAuth Scopes を設定する <a href="#step-set-oauth-scopes" id="step-set-oauth-scopes"></a>

同じページの <mark style="color:blue;">OAuth Scopes</mark> ブロックで、次の権限を付与する必要があります。付与しないと、Agent がメッセージを送受信したり、メンバー名を取得したりできません。

| Scope         | 説明                              |
| ------------- | ------------------------------- |
| `bot`         | Bot の管理                         |
| `bot.message` | メッセージの送信                        |
| `bot.read`    | Bot 設定の読み取り                     |
| `user.read`   | メンバー情報の読み取り（対話内に発言者名を表示するために使用） |

{% hint style="info" %}
同じページの <mark style="color:blue;">Token設定</mark> では、Access Token の有効期限を調整できます。MaiAgent がトークンの発行と更新を自動で管理するため、ここは既定値のままで問題ありません。
{% endhint %}

{% hint style="danger" %}
**Private Key はダウンロードできるのが 1 回だけです。** Service Account の作成時に `.key` ファイルのダウンロードが提供され、ページを離れると二度と取得できません。必ず安全な場所に保管してください。紛失した場合は新しく再生成するしかなく、再生成すると既存の連携が直ちに無効になります。
{% endhint %}

秘密鍵は**暗号化されていない** PEM 形式である必要があります。1 行目は `BEGIN PRIVATE KEY` または `BEGIN RSA PRIVATE KEY` のマーカー（その前後に各 5 つのハイフン）で、最終行は対応する `END` マーカーです。秘密鍵がパスワードで保護されている場合、MaiAgent では使用できないため、暗号化されていないものを再生成してください。

***

## ステップ 2：Bot を作成して Bot ID と Bot Secret を取得する <a href="#step-create-bot" id="step-create-bot"></a>

Developer Console の左側メニューで <mark style="color:blue;">Bot</mark> をクリックして Bot を作成し、次を取得します。

| 認証情報           | Console 上の場所                                                                                               |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| **Bot ID**     | <mark style="color:blue;">Bot ID</mark> 欄                                                                  |
| **Bot Secret** | <mark style="color:blue;">Bot Secret</mark> 欄。LINE WORKS から送られてくるメッセージが確かにお客様の Bot からのものであることを検証するために使用します |

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-96baaf3f207c58a24ca25d1c10f0a2cdd692913a%2Flineworks-console-bot-detail.png?alt=media" alt="Bot 名、Bot ID、Bot Secret、Callback URL、Bot ポリシーを含む Bot の詳細ページ"><figcaption><p>Bot の詳細ページ — Bot ID と Bot Secret はここにあります</p></figcaption></figure>

### グループ対話が必要な場合の必須設定 <a href="#step-enable-group-chat" id="step-enable-group-chat"></a>

Bot の <mark style="color:blue;">修改</mark>（編集）ページで <mark style="color:blue;">Bot政策</mark>（Bot ポリシー）→ <mark style="color:blue;">加入聊天室</mark>（トークルームへの参加）を開き、<mark style="color:blue;">可邀請加入團隊/群組、1:N聊天室</mark>（チーム／グループ、1:N トークルームへの招待を許可）にチェックを入れます。

チェックを入れていない場合、Bot は 1 対 1 のダイレクトメッセージしかできず、グループに招待されることはできません。

{% hint style="warning" %}
Bot の詳細ページにある <mark style="color:blue;">Bot政策</mark>（Bot ポリシー）の概要テキストが、編集フォームの実際のチェック状態と一致しないケースが確認されています。両者の表示が異なる場合は、<mark style="color:blue;">修改</mark>（編集）フォームのチェック状態を基準にしてください。
{% endhint %}

**Bot 名**もこのページで設定します。この名前は、ユーザーがグループで Bot に @ メンションするときに入力する名前になるため、入力しやすい名前を付けてください。

{% hint style="info" %}
Callback URL はこの段階では設定せず、スキップしてください。MaiAgent が生成する Webhook URL が必要なため、**ステップ 4** に戻ってから入力します。
{% endhint %}

***

## ステップ 3：MaiAgent で LINE WORKS 対話プラットフォームを作成する <a href="#step-create-channel-in-maiagent" id="step-create-channel-in-maiagent"></a>

### 1. 対話プラットフォーム連携を開く <a href="#step-go-to-channel-integration" id="step-go-to-channel-integration"></a>

MaiAgent の左側メニューで <mark style="color:blue;">対話プラットフォーム</mark>をクリックし、右上の<mark style="color:blue;">対話プラットフォームを連携</mark>をクリックして、<mark style="color:blue;">LINE WORKS</mark> を選択します。

### 2. 基本設定を入力する <a href="#step-fill-basic-settings" id="step-fill-basic-settings"></a>

| 項目                  | 説明                                                                  |
| ------------------- | ------------------------------------------------------------------- |
| **名前**              | この連携の名前を付けます（必須）。MaiAgent 側のラベルにすぎず、LINE WORKS に表示される Bot 名とは無関係です。 |
| **AI アシスタント**       | 紐付ける Agent を選択します                                                   |
| **Bot ID**          | ステップ 2 で取得したもの（必須）                                                  |
| **Bot Secret**      | ステップ 2 で取得したもの（必須）                                                  |
| **Client ID**       | ステップ 1 で取得したもの（必須）                                                  |
| **Client Secret**   | ステップ 1 で取得したもの（必須）                                                  |
| **Service Account** | ステップ 1 で取得したもの（必須）                                                  |
| **Private Key**     | ステップ 1 でダウンロードした `.key` ファイルの内容全体を、先頭と末尾のマーカー行も含めて貼り付けます（必須）        |

フォームは上下 2 つのブロックに分かれています。上半分は名前、Agent、およびステップ 2 で取得した Bot ID と Bot Secret です。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-684d5f59dd73accc1c7177b4c3bc3b02345ab1a3%2Flineworks-create-form.png?alt=media" alt="名前、Agent、Bot ID、Bot Secret を含む MaiAgent の LINE WORKS 作成フォーム上半分"><figcaption><p>作成フォーム上半分 — 名前、Agent、Bot ID、Bot Secret（図は例の値です）</p></figcaption></figure>

下にスクロールすると、ステップ 1 で取得した Client App の 3 つの認証情報と秘密鍵があります。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-456748551dd15070854358eaf0ceb8785d9f448d%2Flineworks-create-form-credentials.png?alt=media" alt="Client ID、Client Secret、Service Account、Private Key を含む MaiAgent の LINE WORKS 作成フォーム下半分"><figcaption><p>作成フォーム下半分 — Client ID、Client Secret、Service Account、Private Key（図は例の値です）</p></figcaption></figure>

{% hint style="info" %}
Bot Secret と Client Secret は入力後に丸い点でマスクされます。欄の右側にある目のアイコンをクリックすると内容を確認できます。Private Key は `.key` ファイルの内容全体をそのまま貼り付けてください。改行はそのまま保持されます。
{% endhint %}

### 3. トークルーム設定 <a href="#step-chat-room-settings" id="step-chat-room-settings"></a>

| 設定                  | 説明                                                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| **グループでは @Bot が必要** | 有効にすると、Bot はグループ対話で @ メンションされたときだけ返信します。**グループで使う場合は有効にすることをおすすめします**。無効だと、グループ内のすべてのメッセージが Agent の返信を引き起こします。 |
| **リセットコマンドを有効にする**  | 有効にするとキーワードを自由に設定でき、ユーザーがそのキーワードを入力すると対話の記憶を消去して最初からやり直せます。                                                    |

{% hint style="info" %}
「グループでは @Bot が必要」が照合するのは **Developer Console で設定した Bot 名**であり、上の「名前」欄に入力した Inbox 名ではありません。Developer Console で Bot 名を変更すると、グループで @ メンションする名前も変わります。
{% endhint %}

### 4. 連携テスト <a href="#step-validate-credentials" id="step-validate-credentials"></a>

<mark style="color:blue;">連携テスト</mark>をクリックすると、MaiAgent が実際に LINE WORKS へアクセストークンを 1 回取得しに行き、認証情報の組み合わせが正しいことを確認します。

失敗した場合は、画面に具体的な原因が表示されます。よくあるものは次の 2 つです。

* <mark style="color:red;">認証情報の検証に失敗しました</mark> — 次の順に確認してください：Private Key が完全に貼り付けられているか（先頭と末尾のマーカー行を含み、途中の改行が欠けていないこと）、暗号化されていない形式か、Service Account が完全か（`.serviceaccount@ドメイン` の後半部分を含む）、Client ID と Client Secret が同じ App のものか、App にステップ 1 に挙げた 4 つの Scope が付与されているか
* <mark style="color:red;">この Bot ID はすでに別の受信トレイに紐付けられています</mark> — 同じ Bot を 2 つの対話プラットフォームに同時に接続することはできません。別の Bot を使うか、先に既存の対話プラットフォームを削除してください

失敗メッセージはボタンの左側に表示されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-2861170cf6776a2e293279d60dc83f913bf8b18d%2Flineworks-validate-error.png?alt=media" alt="連携テスト失敗時、エラーメッセージが連携テストボタンの左側に表示される"><figcaption><p>連携テスト失敗メッセージの表示位置（この例では Bot ID の重複紐付け）</p></figcaption></figure>

### 5. Webhook URL を作成してコピーする <a href="#step-save-and-get-webhook-url" id="step-save-and-get-webhook-url"></a>

<mark style="color:blue;">対話プラットフォームを連携</mark>をクリックして作成を完了します。システムが **Webhook URL** を生成しますので、コピーして控えておいてください。次のステップで Developer Console に入力します。

該当チャネルの設定ページに戻れば、<mark style="color:blue;">API 連携</mark>欄からいつでもこの URL をコピーできます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-a78d5c06347c503ad3522890174f6e39d536e127%2Flineworks-edit-page.png?alt=media" alt="Bot ID、Client ID、Service Account が読み取り専用で表示され、API 連携の Webhook URL が提供される LINE WORKS チャネルの設定ページ"><figcaption><p>作成後の設定ページ — 認証情報は表示されなくなり、Webhook URL はいつでもコピーできます</p></figcaption></figure>

***

## ステップ 4：Developer Console に戻って Callback URL を設定する <a href="#step-configure-callback-url" id="step-configure-callback-url"></a>

ステップ 2 で作成した Bot に戻り、<mark style="color:blue;">修改</mark>（編集）ページを開きます。

1. <mark style="color:blue;">Callback URL</mark> を <mark style="color:blue;">On</mark> に設定し、MaiAgent が生成した **Webhook URL** を入力します
2. <mark style="color:blue;">Callback Event Settings</mark> で受信するイベントにチェックを入れます。Agent があらゆる種類のメッセージを処理できるよう、<mark style="color:blue;">Message Event</mark> の下をすべてチェックすることをおすすめします。

| イベント                                           | 対応するユーザーの操作  |
| ---------------------------------------------- | ------------ |
| <mark style="color:blue;">TEXT</mark>          | テキストメッセージの送信 |
| <mark style="color:blue;">照片</mark>（写真）        | 画像の送信        |
| <mark style="color:blue;">檔案</mark>（ファイル）      | ファイルの送信      |
| <mark style="color:blue;">音訊</mark>（音声）        | 音声メッセージの送信   |
| <mark style="color:blue;">視訊</mark>（動画）        | 動画の送信        |
| <mark style="color:blue;">位置分享</mark>（位置情報の共有） | 位置情報の共有      |
| <mark style="color:blue;">貼圖</mark>（スタンプ）      | スタンプの送信      |

3. グループで使う場合は、<mark style="color:blue;">Join Event</mark> と <mark style="color:blue;">Joined Event</mark> もチェックすることをおすすめします
4. 設定を保存します

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-b55d63f49e2c97ae83bd1ea6737402a710e03e06%2Flineworks-console-bot-callback.png?alt=media" alt="Bot 編集ページの Callback URL と Callback Event Settings"><figcaption><p>Callback URL を On にして Webhook URL を入力し、下でイベントタイプにチェックを入れます</p></figcaption></figure>

{% hint style="warning" %}
チェックを入れていないイベントタイプは、LINE WORKS から MaiAgent に送信されません。その種類のメッセージは最初から無かったことになり、Agent は返信せず、対話にも記録が残りません。
{% endhint %}

***

## ステップ 5：Admin 管理画面で Bot を有効にする <a href="#step-activate-bot" id="step-activate-bot"></a>

[LINE WORKS Admin 管理画面](https://admin.worksmobile.com/)にログインし、左側の<mark style="color:blue;">服務</mark>（サービス）→ <mark style="color:blue;">Bot</mark> で右上の<mark style="color:blue;">新增Bot</mark>（Bot の追加）をクリックして、ステップ 2 で作成した Bot を追加します。

追加すると、このページに該当 Bot が一覧表示され、<mark style="color:blue;">使用權限</mark>（利用権限）欄でどのメンバーに表示するかを設定できます（<mark style="color:blue;">全部</mark>（すべて）に設定すると、全メンバーが利用できます）。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-9bd2b2649536680af45839ab3c239677210c1100%2Flineworks-admin-bot.png?alt=media" alt="追加済みの Bot とその利用権限が一覧表示される LINE WORKS Admin 管理画面の サービス → Bot ページ"><figcaption><p>Admin 管理画面 → サービス → Bot — Bot を追加して利用権限を設定します</p></figcaption></figure>

{% hint style="warning" %}
このステップは見落としやすいので注意してください。Developer Console で Bot を作成しただけでは、**従業員の LINE WORKS にはまだ表示されません**。テナント管理者が Admin 管理画面で追加して初めて、従業員が検索で見つけられるようになります。
{% endhint %}

***

## 使い始める <a href="#getting-started" id="getting-started"></a>

### 1 対 1 のダイレクトメッセージ <a href="#direct-message" id="direct-message"></a>

LINE WORKS で Bot 名を検索して対話を始めると、Agent が自動的に返信します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-61671de9af211a3e38edec25ce37d9a382dceea4%2Flineworks-chat-demo.png?alt=media" alt="LINE WORKS のトークルームでの Agent との 1 対 1 の対話"><figcaption><p>LINE WORKS のトークルームで Agent と直接対話します</p></figcaption></figure>

{% hint style="info" %}
LINE WORKS のトークルームはプレーンテキストのみを表示し、**Markdown をレンダリングしません**。Agent が表や `**太字**`、`###` などの記法を出力すると、ユーザーには元の記号がそのまま見えてしまいます。Agent のロール指示に書式ルールを追加し、リストは番号と改行で表現して Markdown 記法を使わないよう指示することをおすすめします。
{% endhint %}

### グループ対話 <a href="#group-conversation" id="group-conversation"></a>

Bot をグループに招待します。「グループでは @Bot が必要」を有効にしている場合は、`@Bot名 質問内容` と入力したときだけ返信が行われます。

MaiAgent の<mark style="color:blue;">すべての対話</mark>では、同じグループは**ひとつの対話**として表示され、発言者名がメッセージ上に表示されます。グループ内で複数の人が発言しても、並行する複数の対話に分割されることはありません。

### 対応するメッセージタイプ <a href="#supported-message-types" id="supported-message-types"></a>

| ユーザーが送信するもの             | Agent の処理方法             |
| ----------------------- | ----------------------- |
| テキスト                    | そのまま回答します               |
| 画像                      | 画像の内容を認識できます            |
| ファイル（PDF、Excel、Word など） | 内容を読み取って関連する質問に回答します    |
| 音声メッセージ                 | テキストに変換してから処理します        |
| 動画                      | 添付ファイルとして保存され、対話に記録されます |
| 位置情報                    | 「📍 位置情報を共有しました」と表示されます |
| スタンプ                    | 「🏷 スタンプ」と表示されます        |

Agent の返信ではテキストと添付ファイルに対応しています。1 通のテキストメッセージが LINE WORKS の上限である 1,000 文字を超える場合は、システムが自動的に分割して送信するため、途中で切り捨てられることはありません。

***

## よくある質問 <a href="#faq" id="faq"></a>

### Agent が突然返信しなくなった <a href="#troubleshoot-no-reply" id="troubleshoot-no-reply"></a>

まず、該当チャネルの設定ページで<mark style="color:red;">認証情報が無効です</mark>という警告が表示されていないか確認してください。

認証情報が無効になる最も一般的な原因は、**Developer Console で秘密鍵または Service Account を再生成したこと**です。古い認証情報が置き換えられると、MaiAgent はアクセストークンを取得できなくなります。

認証情報はその場で変更できないため、LINE WORKS チャネルを新しく作成し直し、新しい認証情報を入力してください。

{% hint style="info" %}
認証情報が無効になったときの外部から見える症状は、Agent が静かになることだけです。ユーザーにはエラーメッセージが一切表示されません。同僚から「ボットが反応しない」と報告があった場合は、まずここを確認してください。
{% endhint %}

### なぜ認証情報は変更できないのですか？ <a href="#why-credentials-are-immutable" id="why-credentials-are-immutable"></a>

認証情報は機密データのため、MaiAgent は保存後にフロントエンドへ返さず、設定ページでも変更を受け付けません。これは、認証情報が通信経路や画面上で繰り返し露出するのを避けるためです。Bot ID、Client ID、Service Account は読み取り専用で表示されるので、現在どの Bot に接続しているかを確認できます。

いずれかの認証情報を変更する必要がある場合は、このチャネルを削除してから作成し直してください。

### グループで Bot に @ メンションしたのに反応がない <a href="#troubleshoot-group-mention" id="troubleshoot-group-mention"></a>

* @ メンションした名前が、MaiAgent の Inbox 名ではなく **Developer Console の Bot 名**と一致しているか確認してください
* Bot の編集ページで <mark style="color:blue;">Bot政策</mark>（Bot ポリシー）→ <mark style="color:blue;">加入聊天室</mark>（トークルームへの参加）の <mark style="color:blue;">可邀請加入團隊/群組、1:N聊天室</mark>（チーム／グループ、1:N トークルームへの招待を許可）にチェックが入っているか確認してください
* <mark style="color:blue;">Callback Event Settings</mark> で <mark style="color:blue;">TEXT</mark> にチェックが入っているか確認してください

### トークンを定期的に更新する必要がありますか？ <a href="#token-renewal" id="token-renewal"></a>

必要ありません。MaiAgent は Service Account 方式で認証しており、アクセストークンはシステムが自動的に発行・更新するため、時間の経過で失効することはありません。Developer Console の認証情報が再生成されていない限り、連携は有効なまま続きます。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/build/choose-channel/line-works.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.