> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Messaging Channel Integration Guide
> For users who integrate external IM platforms through the Forward Channel API, this guide covers the recommended QR-code binding flow, and how to create the app/bot, configure permissions, and obtain credentials for each channel.
**We currently recommend using QR-code binding to authorize channels — do not configure credentials directly unless necessary.**
DingTalk, Feishu, WeCom, and personal WeChat all support QR-code binding: you can omit `channel_config.credentials` when creating a Channel, then complete the binding by scanning a QR code through a QR Session. This avoids storing sensitive credentials like App Secret on your side, and is both more secure and easier to maintain.
Only consider the "direct credential" flow below for each channel when QR-code binding cannot meet your needs (for example, unattended server-side automation).
## QR-code binding flow (recommended)
QR-code binding works for all channels — `dingtalk`, `feishu`, `wecom`, `wechat`. The steps are:
1. **Create the Channel**: call [Create Channel](/cloud-agents/api/forward/channels/create) with `name`, `channel_type`, `identity_id`, and `template_id`, **omitting `channel_config.credentials`**.
2. **Create a QR Session**: call [Create Channel QR Session](/cloud-agents/api/forward/channels/create-qr-session) to obtain `qr_code_image_base64` (the QR code image) or `qr_code_content` (the authorization URL), along with the suggested polling interval `poll_interval_seconds`.
3. **Show the QR code and authorize**: display the QR code to the user, then use the corresponding channel client to scan and confirm authorization.
4. **Poll the authorization status**: at the `poll_interval_seconds` cadence, call [Get Channel QR Session](/cloud-agents/api/forward/channels/get-qr-session) to poll `status` until it becomes `confirmed` (other states: `waiting`, `scanned`, `expired`, `denied`, `error`).
5. **Complete the binding**: after `status=confirmed`, refresh the Channel detail; `binding_status` will become `bound`, and the channel is ready to receive inbound messages and reply automatically.
QR codes have a short validity. If a session becomes `expired` or `denied`, create a new QR Session and scan again.
## Direct credential integration (as needed)
If you must use direct credentials, create an app/bot on the corresponding open platform, configure the required permissions, obtain the credentials, and then pass them to [Create Channel](/cloud-agents/api/forward/channels/create) through `channel_config.credentials`. Mapping of `channel_type` and credential fields per channel:
| Channel | `channel_type` | `channel_config.credentials` fields | Supports QR binding |
| --------------- | -------------- | ----------------------------------- | ------------------- |
| DingTalk | `dingtalk` | `client_id`, `client_secret` | Yes (recommended) |
| Feishu | `feishu` | `app_id`, `app_secret` | Yes (recommended) |
| WeCom | `wecom` | `bot_id`, `secret` | Yes (recommended) |
| Personal WeChat | `wechat` | No credentials required | QR binding only |
Credentials are only written when creating/updating a Channel; they are never returned in plaintext.
## DingTalk
### Create a DingTalk app
1. Go to the [DingTalk Open Platform](https://open-dev.dingtalk.com/). Choose an organization that has developer permissions, or acquire developer permissions on a given organization. If no suitable organization exists, use the DingTalk mobile app to quickly create one by scanning a QR code.
2. In the top navigation, click **App Development**, then click **Create App** on the DingTalk App page.
### Create a DingTalk bot
1. Once the app is created, select **Add App Capability** in the left navigation, then click **Add** on the bot card.
2. On the bot configuration page, enable bot configuration.
3. For **Message Reception Mode**, choose **Stream mode**, then click **Publish** to finish configuring the bot.
### Configure permissions
In the app's **Permission Management**, enable the following permissions:
| Permission | Description |
| ---------------------- | -------------------------------- |
| `Card.Streaming.Write` | Streaming write to card messages |
| `Card.Instance.Write` | Create / update card instances |
| `qyapi_robot_sendmsg` | Bot sends messages |
### Publish the app
1. Select **Version Management and Release** in the left navigation, then click **Create New Version**.
2. Fill in the app version number and description, choose the app's availability scope based on your business needs, and click **Save** to publish.
If the availability scope is set to all employees, the app will be visible to every employee of the current enterprise after publishing.
### Get the credentials
On the **Credentials & Basic Info** page in the left navigation, record the **Client ID** and **Client Secret** — they correspond to the API's `client_id` and `client_secret`.
## Feishu
### Create a Feishu app
1. Visit the [Feishu Open Platform](https://open.feishu.cn/) and click **Developer Console** in the top-right corner.
2. Click **Create Custom App for Enterprise**, fill in the required info, and click **Create**.
### Add and configure the bot
1. Select **Add App Capability** in the left navigation, and click **Add** on the bot card.
2. Click the edit icon next to "How to get started" on the bot configuration card.
3. Under **Message Card Callback Request Method**, click **Configure**, choose **Receive callbacks via long connection**, and save.
4. Click **Event Configuration**, choose the same **Receive callbacks via long connection** subscription mode, and save.
5. On the Event Configuration page, add the following four events and save:
* Bot joined chat
* Bot removed from chat
* Message read
* Receive message
### Configure permissions
In **Permission Management > Enable Permissions**, click **Batch Import / Export Permissions**, paste the JSON below to import the required permissions in one click, confirm, and click **Apply for Approval**:
```json theme={null}
{
"scopes": {
"tenant": [
"contact:contact.base:readonly",
"docx:document:readonly",
"im:chat:read",
"im:chat:update",
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message.pins:read",
"im:message.pins:write_only",
"im:message.reactions:read",
"im:message.reactions:write_only",
"im:message:readonly",
"im:message:recall",
"im:message:send_as_bot",
"im:message:send_multi_users",
"im:message:send_sys_msg",
"im:message:update",
"im:resource",
"application:application:self_manage",
"cardkit:card:write",
"cardkit:card:read"
],
"user": [
"contact:user.employee_id:readonly",
"offline_access",
"base:app:copy",
"base:field:create",
"base:field:delete",
"base:field:read",
"base:field:update",
"base:record:create",
"base:record:delete",
"base:record:retrieve",
"base:record:update",
"base:table:create",
"base:table:delete",
"base:table:read",
"base:table:update",
"base:view:read",
"base:view:write_only",
"base:app:create",
"base:app:update",
"base:app:read",
"board:whiteboard:node:create",
"board:whiteboard:node:read",
"calendar:calendar:read",
"calendar:calendar.event:create",
"calendar:calendar.event:delete",
"calendar:calendar.event:read",
"calendar:calendar.event:reply",
"calendar:calendar.event:update",
"calendar:calendar.free_busy:read",
"contact:contact.base:readonly",
"contact:user.base:readonly",
"contact:user:search",
"docs:document.comment:create",
"docs:document.comment:read",
"docs:document.comment:update",
"docs:document.media:download",
"docs:document:copy",
"docx:document:create",
"docx:document:readonly",
"docx:document:write_only",
"drive:drive.metadata:readonly",
"drive:file:download",
"drive:file:upload",
"im:chat.members:read",
"im:chat:read",
"im:message",
"im:message.group_msg:get_as_user",
"im:message.p2p_msg:get_as_user",
"im:message:readonly",
"search:docs:read",
"search:message",
"space:document:delete",
"space:document:move",
"space:document:retrieve",
"task:comment:read",
"task:comment:write",
"task:task:read",
"task:task:write",
"task:task:writeonly",
"task:tasklist:read",
"task:tasklist:write",
"wiki:node:copy",
"wiki:node:create",
"wiki:node:move",
"wiki:node:read",
"wiki:node:retrieve",
"wiki:space:read",
"wiki:space:retrieve",
"wiki:space:write_only"
]
}
}
```
### Publish the app
1. Select **Version Management and Release** in the left navigation.
2. Click **Create Version**, fill in the required info, and click **Save**.
### Get the credentials
On the app's **Credentials & Basic Info** page, copy the **App ID** (format like `cli_xxx`) and **App Secret** — they correspond to the API's `app_id` and `app_secret`.
## WeCom
### Create a smart bot
1. Visit the [WeCom Admin Console](https://work.weixin.qq.com/). In the left navigation, click **Security & Management > Management Tools**, click **Create Bot**, and then click **Manually Create**.
2. Configure the bot's visibility scope.
3. Scroll to the bottom and click **API Mode Creation**, and choose **Use long connection** as the connection method.
### Get the credentials
In the **Secret** area of the configuration method, click **Get** and record the **Bot ID** and **Secret** — they correspond to the API's `bot_id` and `secret`.
## Personal WeChat
Personal WeChat only supports **QR-code binding** — no need to create an app on any open platform, and no direct credentials are required. When creating a Channel, pass `wechat` as `channel_type` and complete the authorization following the [QR-code binding flow (recommended)](#qr-code-binding-flow-recommended) above.
## Related