Messaging Channel Integration Guide

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:

Create the Channel: call Create Channel with name, channel_type, identity_id, and template_id, omitting channel_config.credentials.
Create a QR Session: call Create Channel 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.
Show the QR code and authorize: display the QR code to the user, then use the corresponding channel client to scan and confirm authorization.
Poll the authorization status: at the poll_interval_seconds cadence, call Get Channel QR Session to poll status until it becomes confirmed (other states: waiting, scanned, expired, denied, error).
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 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

Go to the DingTalk Open Platform. 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.
In the top navigation, click App Development, then click Create App on the DingTalk App page.

Create a DingTalk bot

Once the app is created, select Add App Capability in the left navigation, then click Add on the bot card.
On the bot configuration page, enable bot configuration.
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

Select Version Management and Release in the left navigation, then click Create New Version.
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

Visit the Feishu Open Platform and click Developer Console in the top-right corner.
Click Create Custom App for Enterprise, fill in the required info, and click Create.

Add and configure the bot

Select Add App Capability in the left navigation, and click Add on the bot card.
Click the edit icon next to “How to get started” on the bot configuration card.
Under Message Card Callback Request Method, click Configure, choose Receive callbacks via long connection, and save.
Click Event Configuration, choose the same Receive callbacks via long connection subscription mode, and save.
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:

{
  "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

Select Version Management and Release in the left navigation.
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

Visit the WeCom Admin Console. In the left navigation, click Security & Management > Management Tools, click Create Bot, and then click Manually Create.
Configure the bot’s visibility scope.
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) above.

​QR-code binding flow (recommended)

​Direct credential integration (as needed)

​DingTalk

​Create a DingTalk app

​Create a DingTalk bot

​Configure permissions

​Publish the app

​Get the credentials

​Feishu

​Create a Feishu app

​Add and configure the bot

​Configure permissions

​Publish the app

​Get the credentials

​WeCom

​Create a smart bot

​Get the credentials

​Personal WeChat

​Related

Create Channel

Create Channel QR Session

List Channels

QR-code binding flow (recommended)

Direct credential integration (as needed)

DingTalk

Create a DingTalk app

Create a DingTalk bot

Configure permissions

Publish the app

Get the credentials

Feishu

Create a Feishu app

Add and configure the bot

Configure permissions

Publish the app

Get the credentials

WeCom

Create a smart bot

Get the credentials

Personal WeChat

Related