> 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/en/build/choose-channel/line-works.md).

# Connect a Conversation Platform: LINE WORKS

Connect the LINE WORKS messaging platform：create a Client App and Bot in Developer Console, obtain a Service Account and Bot Secret, configure the Callback URL, and activate the Bot.

LINE WORKS is LINE's enterprise communication tool. Once connected, employees can chat with an Agent directly in LINE WORKS without opening another system. Both one-on-one direct messages and group conversations are supported.

{% hint style="info" %}
LINE WORKS and LINE are separate platforms with entirely different credentials and setup procedures. To connect a consumer-facing LINE Official Account, see [Connect a Messaging Platform：LINE](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/line.md).
{% endhint %}

## Before You Connect <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

* You have created an "AI Assistant" on the [MaiAgent platform](https://admin.maiagent.ai/)
* You have LINE WORKS administrator permissions (you can log in to the [Admin console](https://admin.worksmobile.com/))
* You can access the [LINE WORKS Developer Console](https://developers.worksmobile.com/)

{% hint style="warning" %}
This integration requires 6 credentials, and **credentials cannot be changed after the channel is created**. Complete Steps 1 and 2 and prepare all 6 credentials before proceeding to Step 3.
{% endhint %}

***

## Step 1：Create a Client App and Obtain a Service Account <a href="#step-create-client-app" id="step-create-client-app"></a>

### 1. Open the ClientApp Page in Developer Console <a href="#step-go-to-clientapp" id="step-go-to-clientapp"></a>

Log in to the [LINE WORKS Developer Console](https://developers.worksmobile.com/), select <mark style="color:blue;">API</mark> → <mark style="color:blue;">ClientApp</mark> in the left menu, then click <mark style="color:blue;">Add client app</mark> to create an App.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0d792c7b976ddc8399f167d41ee79992a0caa192%2Flineworks-console-clientapp-list.png?alt=media" alt="ClientApp list page in Developer Console"><figcaption><p>Developer Console → API → ClientApp</p></figcaption></figure>

### 2. Obtain the Four Credentials <a href="#step-get-app-credentials" id="step-get-app-credentials"></a>

Open the App's details page and obtain the following four items:

| Credential          | Location in Console                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Client ID**       | <mark style="color:blue;">Client ID</mark> field                                                           |
| **Client Secret**   | <mark style="color:blue;">Client Secret</mark> field                                                       |
| **Service Account** | <mark style="color:blue;">Service Account</mark> field, in the format `xxxxx.serviceaccount@your-domain`   |
| **Private Key**     | <mark style="color:blue;">Private Key</mark> section; a `.key` file is available for download when created |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-22a6737d44f3e40f43a4b72a81fc4568dc81dfc8%2Flineworks-console-clientapp-detail.png?alt=media" alt="Client App details page with Client ID, Client Secret, OAuth Scopes, Service Account, and Private Key"><figcaption><p>Client App details page — all four credentials and OAuth Scopes are on this page</p></figcaption></figure>

### 3. Configure OAuth Scopes <a href="#step-set-oauth-scopes" id="step-set-oauth-scopes"></a>

Grant the following permissions in the <mark style="color:blue;">OAuth Scopes</mark> section on the same page. Without them, the Agent cannot send or receive messages or look up member names:

| Scope         | Description                                                                   |
| ------------- | ----------------------------------------------------------------------------- |
| `bot`         | Manage the Bot                                                                |
| `bot.message` | Send messages                                                                 |
| `bot.read`    | Read Bot settings                                                             |
| `user.read`   | Read member information (used to display the speaker's name in conversations) |

{% hint style="info" %} <mark style="color:blue;">Token Settings</mark> on the same page lets you adjust the Access Token's validity period. MaiAgent automatically manages token issuance and renewal, so you can keep the default value here.
{% endhint %}

{% hint style="danger" %}
**The Private Key can only be downloaded once.** A `.key` file is available for download when you create the Service Account. You cannot retrieve it after leaving the page. Store it securely first. If lost, you must generate a new key, which immediately invalidates the existing integration.
{% endhint %}

The private key must be in **unencrypted** PEM format: the first line contains the `BEGIN PRIVATE KEY` or `BEGIN RSA PRIVATE KEY` marker (with five hyphens on each side), and the last line contains the corresponding `END` marker. MaiAgent cannot use a password-protected private key. Generate an unencrypted one instead.

***

## Step 2：Create a Bot and Obtain the Bot ID and Bot Secret <a href="#step-create-bot" id="step-create-bot"></a>

Select <mark style="color:blue;">Bot</mark> in the left menu of Developer Console, create a Bot, and obtain:

| Credential     | Location in Console                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Bot ID**     | <mark style="color:blue;">Bot ID</mark> field                                                                                  |
| **Bot Secret** | <mark style="color:blue;">Bot Secret</mark> field, used to verify that messages sent by LINE WORKS actually come from your Bot |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-96baaf3f207c58a24ca25d1c10f0a2cdd692913a%2Flineworks-console-bot-detail.png?alt=media" alt="Bot details page with the Bot name, Bot ID, Bot Secret, Callback URL, and Bot Policy"><figcaption><p>Bot details page — find the Bot ID and Bot Secret here</p></figcaption></figure>

### Required Settings for Group Conversations <a href="#step-enable-group-chat" id="step-enable-group-chat"></a>

On the Bot's <mark style="color:blue;">Edit</mark> page, find <mark style="color:blue;">Bot Policy</mark> → <mark style="color:blue;">Join Chat Rooms</mark> and select <mark style="color:blue;">Can be invited to team/group and 1:N chat rooms</mark>.

Without this option, the Bot can only exchange one-on-one direct messages and cannot be invited to a group.

{% hint style="warning" %}
The <mark style="color:blue;">Bot Policy</mark> summary on the Bot details page has been observed to differ from the actual checkbox selection in the edit form. If the two differ, use the selection in the <mark style="color:blue;">Edit</mark> form as the source of truth.
{% endhint %}

The **Bot name** is also configured on this page. Users enter this name when they @ mention the Bot in a group, so choose a name that is easy to type.

{% hint style="info" %}
Skip the Callback URL for now. It requires a Webhook URL generated by MaiAgent. You will return to fill it in during **Step 4**.
{% endhint %}

***

## Step 3：Create a LINE WORKS Messaging Platform in MaiAgent <a href="#step-create-channel-in-maiagent" id="step-create-channel-in-maiagent"></a>

### 1. Open Connect Messaging Platform <a href="#step-go-to-channel-integration" id="step-go-to-channel-integration"></a>

Select <mark style="color:blue;">Messaging Platforms</mark> in MaiAgent's left menu, click <mark style="color:blue;">Connect Messaging Platform</mark> in the upper right, and select <mark style="color:blue;">LINE WORKS</mark>.

### 2. Fill In the Basic Settings <a href="#step-fill-basic-settings" id="step-fill-basic-settings"></a>

| Field               | Description                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Name**            | Name this integration (required). This is only a label in MaiAgent and is unrelated to the Bot name displayed in LINE WORKS. |
| **AI Assistant**    | Select the Agent to link                                                                                                     |
| **Bot ID**          | Obtained in Step 2 (required)                                                                                                |
| **Bot Secret**      | Obtained in Step 2 (required)                                                                                                |
| **Client ID**       | Obtained in Step 1 (required)                                                                                                |
| **Client Secret**   | Obtained in Step 1 (required)                                                                                                |
| **Service Account** | Obtained in Step 1 (required)                                                                                                |
| **Private Key**     | Paste the entire contents of the `.key` file downloaded in Step 1, including the opening and closing marker lines (required) |

The form has an upper and a lower section. The upper section contains the name, Agent, and the Bot ID and Bot Secret obtained in Step 2:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-684d5f59dd73accc1c7177b4c3bc3b02345ab1a3%2Flineworks-create-form.png?alt=media" alt="Upper section of the MaiAgent LINE WORKS creation form with Name, Agent, Bot ID, and Bot Secret"><figcaption><p>Upper section of the creation form — Name, Agent, Bot ID, Bot Secret (example values shown)</p></figcaption></figure>

Scroll down to find the three Client App credentials and private key obtained in Step 1:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-456748551dd15070854358eaf0ceb8785d9f448d%2Flineworks-create-form-credentials.png?alt=media" alt="Lower section of the MaiAgent LINE WORKS creation form with Client ID, Client Secret, Service Account, and Private Key"><figcaption><p>Lower section of the creation form — Client ID, Client Secret, Service Account, Private Key (example values shown)</p></figcaption></figure>

{% hint style="info" %}
Bot Secret and Client Secret are masked with dots after entry. Click the eye icon on the right of a field to check its contents. Paste the entire contents of the `.key` file directly into Private Key; line breaks are preserved.
{% endhint %}

### 3. Chat Room Settings <a href="#step-chat-room-settings" id="step-chat-room-settings"></a>

| Setting                             | Description                                                                                                                                                                                                                                                                                                      |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Require @Bot to Reply in Groups** | When enabled, the Bot only replies in group conversations when @ mentioned. **Recommended for group use**; otherwise, every message in the group triggers an Agent reply.                                                                                                                                        |
| **Enable Reset Command**            | When enabled, you can add one or more command texts (for example, "Start over"). When a user's message in LINE WORKS exactly matches one of them, a new conversation starts for that user. The command itself receives no reply. The AI responds in the new conversation when the user sends their next message. |

{% hint style="info" %}
"Require @Bot to Reply in Groups" matches the **Bot name configured in Developer Console**, rather than the Inbox name entered in the "Name" field above. If you change the Bot name in Developer Console, the name to @ mention in groups changes too.
{% endhint %}

### 4. Test the Integration <a href="#step-validate-credentials" id="step-validate-credentials"></a>

Click <mark style="color:blue;">Test Integration</mark>. MaiAgent requests an access token from LINE WORKS to verify that the credentials work together.

If the test fails, the screen displays the specific reason. Two common errors are:

* <mark style="color:red;">Credential validation failed</mark> — Check, in order, that the entire Private Key was pasted (including the opening and closing marker lines and all line breaks in between), that it is unencrypted, that the Service Account is complete (including the `.serviceaccount@domain` suffix), that Client ID and Client Secret belong to the same App, and that the App has the four Scopes listed in Step 1
* <mark style="color:red;">This Bot ID is already linked to another inbox</mark> — The same Bot cannot be connected to two messaging platforms at once. Use another Bot, or delete the existing messaging platform first

The error message appears to the left of the button:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-2861170cf6776a2e293279d60dc83f913bf8b18d%2Flineworks-validate-error.png?alt=media" alt="When the integration test fails, the error message appears to the left of the Test Integration button"><figcaption><p>Location of the integration test error message (this example shows a Bot ID already linked to another inbox)</p></figcaption></figure>

### 5. Create the Channel and Copy the Webhook URL <a href="#step-save-and-get-webhook-url" id="step-save-and-get-webhook-url"></a>

Click <mark style="color:blue;">Connect Messaging Platform</mark> to finish creating the channel. The system generates a **Webhook URL**. Copy it for the next step, where you will enter it in Developer Console.

You can also return to the channel's settings page at any time and copy this URL from the <mark style="color:blue;">API Integration</mark> field.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a78d5c06347c503ad3522890174f6e39d536e127%2Flineworks-edit-page.png?alt=media" alt="Settings page for the LINE WORKS channel, with read-only Bot ID, Client ID, and Service Account, and a Webhook URL for API Integration"><figcaption><p>Settings page after creation — credentials are no longer displayed, and the Webhook URL can be copied at any time</p></figcaption></figure>

***

## Step 4：Return to Developer Console to Configure the Callback URL <a href="#step-configure-callback-url" id="step-configure-callback-url"></a>

Return to the Bot created in Step 2 and open the <mark style="color:blue;">Edit</mark> page:

1. Set <mark style="color:blue;">Callback URL</mark> to <mark style="color:blue;">On</mark> and enter the **Webhook URL** generated by MaiAgent
2. Under <mark style="color:blue;">Callback Event Settings</mark>, select the events to receive. Select all options under <mark style="color:blue;">Message Event</mark> so the Agent can handle all message types:

| Event                                             | Corresponding User Action |
| ------------------------------------------------- | ------------------------- |
| <mark style="color:blue;">TEXT</mark>             | Send a text message       |
| <mark style="color:blue;">Photo</mark>            | Send an image             |
| <mark style="color:blue;">File</mark>             | Send a file               |
| <mark style="color:blue;">Audio</mark>            | Send a voice message      |
| <mark style="color:blue;">Video</mark>            | Send a video              |
| <mark style="color:blue;">Location Sharing</mark> | Share a location          |
| <mark style="color:blue;">Sticker</mark>          | Send a sticker            |

3. If you plan to use the Bot in groups, also select <mark style="color:blue;">Join Event</mark> and <mark style="color:blue;">Joined Event</mark>
4. Save the settings

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b55d63f49e2c97ae83bd1ea6737402a710e03e06%2Flineworks-console-bot-callback.png?alt=media" alt="Callback URL and Callback Event Settings on the Bot edit page"><figcaption><p>Set Callback URL to On, enter the Webhook URL, and select the event types below</p></figcaption></figure>

{% hint style="warning" %}
LINE WORKS does not send unselected event types to MaiAgent. Those messages are treated as if they never occurred: the Agent does not reply, and no record appears in the conversation.
{% endhint %}

***

## Step 5：Activate the Bot in the Admin Console <a href="#step-activate-bot" id="step-activate-bot"></a>

Log in to the [LINE WORKS Admin console](https://admin.worksmobile.com/), open <mark style="color:blue;">Services</mark> → <mark style="color:blue;">Bot</mark> in the left menu, and click <mark style="color:blue;">Add Bot</mark> in the upper right to add the Bot created in Step 2.

Once added, the Bot appears on this page. Use the <mark style="color:blue;">Access Permissions</mark> field to specify which members can see it (selecting <mark style="color:blue;">All</mark> makes it available to all members).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9bd2b2649536680af45839ab3c239677210c1100%2Flineworks-admin-bot.png?alt=media" alt="Services → Bot page in the LINE WORKS Admin console, listing added Bots and their access permissions"><figcaption><p>Admin console → Services → Bot — add a Bot and configure access permissions</p></figcaption></figure>

{% hint style="warning" %}
This step is easy to miss. After you create a Bot in Developer Console, **it does not yet appear in employees' LINE WORKS**. The tenant administrator must add it in the Admin console before employees can find it in search.
{% endhint %}

***

## Getting Started <a href="#getting-started" id="getting-started"></a>

### One-on-One Direct Messages <a href="#direct-message" id="direct-message"></a>

Search for the Bot's name in LINE WORKS and start a conversation. The Agent replies automatically.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-61671de9af211a3e38edec25ce37d9a382dceea4%2Flineworks-chat-demo.png?alt=media" alt="One-on-one conversation with an Agent in a LINE WORKS chat room"><figcaption><p>Chat directly with an Agent in a LINE WORKS chat room</p></figcaption></figure>

{% hint style="info" %}
LINE WORKS chat rooms display plain text only and **do not render Markdown**. If the Agent outputs a table or syntax such as `**bold**` or `###`, users see the raw symbols. Add formatting rules to the Agent's role instructions asking it to use numbered lists and line breaks instead of Markdown syntax.
{% endhint %}

### Group Conversations <a href="#group-conversation" id="group-conversation"></a>

Invite the Bot to a group. If "Require @Bot to Reply in Groups" is enabled, enter `@BotName your question` to trigger a reply.

In MaiAgent's <mark style="color:blue;">All Conversations</mark>, each group appears as **a single conversation**, with the speaker's name displayed on each message. Messages from multiple group members do not create separate parallel conversations.

### Supported Message Types <a href="#supported-message-types" id="supported-message-types"></a>

| What the User Sends           | How the Agent Handles It                         |
| ----------------------------- | ------------------------------------------------ |
| Text                          | Answers directly                                 |
| Image                         | Can recognize the image's contents               |
| File (PDF, Excel, Word, etc.) | Reads the contents and answers related questions |
| Voice message                 | Converts to text for processing                  |
| Video                         | Saves it as an attachment in the conversation    |
| Location                      | Displays "📍 Location shared"                    |
| Sticker                       | Displays "🏷 Sticker"                            |

The Agent supports text and attachments in replies. If a single text message exceeds LINE WORKS' 1,000-character limit, the system automatically splits it into multiple messages without truncating it.

***

## FAQ <a href="#faq" id="faq"></a>

### The Agent Suddenly Stopped Replying <a href="#troubleshoot-no-reply" id="troubleshoot-no-reply"></a>

First, open the channel's settings page and check for a <mark style="color:red;">Credentials are invalid</mark> warning.

The most common cause of invalid credentials is **regenerating the private key or Service Account in Developer Console**. Once the old credentials are replaced, MaiAgent can no longer obtain an access token.

Because credentials cannot be edited in place, create a new LINE WORKS channel and enter the new credentials.

{% hint style="info" %}
The only visible symptom of invalid credentials is that the Agent goes silent; users receive no error message. If a colleague reports that "the bot isn't responding," this is the first place to check.
{% endhint %}

### Why Can't Credentials Be Changed? <a href="#why-credentials-are-immutable" id="why-credentials-are-immutable"></a>

Credentials are sensitive data. Once stored, MaiAgent does not return them to the frontend or allow changes on the settings page, to avoid repeatedly exposing them during transmission and on screen. Bot ID, Client ID, and Service Account are displayed as read-only values so you can verify which Bot is connected.

To replace any credential, delete this channel and create it again.

### The Bot Does Not Respond to @ Mentions in a Group <a href="#troubleshoot-group-mention" id="troubleshoot-group-mention"></a>

* Check that the @ mention matches the **Bot name in Developer Console**, rather than the Inbox name in MaiAgent
* On the Bot edit page, check that <mark style="color:blue;">Can be invited to team/group and 1:N chat rooms</mark> is selected under <mark style="color:blue;">Bot Policy</mark> → <mark style="color:blue;">Join Chat Rooms</mark>
* Check that <mark style="color:blue;">TEXT</mark> is selected under <mark style="color:blue;">Callback Event Settings</mark>

### Do Tokens Need to Be Renewed Manually on a Regular Basis? <a href="#token-renewal" id="token-renewal"></a>

No. MaiAgent authenticates using a Service Account. The system automatically issues and renews access tokens, so they do not become invalid over time. The integration remains valid as long as the credentials in Developer Console are not regenerated.


---

# 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/en/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.
