Messaging Channel Integration Guide

For users who integrate external IM platforms through the Forward Channel API, this guide covers channel authorization, fixed/pairing execution context modes, 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).

Distinguish channel authorization from Channel Pairing

Forward Channel has two independent configuration dimensions:

Dimension	Problem it solves	Options
Channel authorization	How Forward obtains IM bot connection and send/receive permissions	QR Session scan (recommended) or direct credentials
Identity resolution	Which Identity and Template should be used for a given inbound message	fixed or pairing

The “QR-code binding” in a QR Session is channel credential authorization — it is not the same as Channel Pairing. A pairing Channel still needs to complete channel authorization first so binding_status=bound; afterwards, when a real IM conversation is triggered for the first time, Forward generates a Pairing Code to bind the execution context for that message scope.

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 with name, channel_type, and the desired identity resolution mode, omitting channel_config.credentials. For fixed mode, also pass identity_id and template_id; for pairing mode, pass identity_resolution.mode=pairing without identity_id or template_id.
2. 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). poll_interval_seconds is an optional compatibility field and should not be relied upon as a stable return value.
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: call Get Channel QR Session to poll status. Use poll_interval_seconds if present; otherwise default to a 3-second interval. Poll until confirmed (other states: waiting, scanned, expired, denied, error).
5. Complete channel authorization: after status=confirmed, refresh the Channel detail; binding_status will become bound. A fixed Channel can now process inbound messages with its fixed execution context; a pairing Channel will return a Pairing Code for unpaired messages — complete Channel Pairing (below) before messages enter the Agent.

QR codes have a short validity. If a session becomes expired or denied, create a new QR Session and scan again.

Identity resolution modes

fixed mode

fixed is the default. You must specify identity_id and template_id when creating the Channel; all inbound messages use this fixed execution context:

{
  "identity_id": "idn_019eabc123",
  "identity_resolution": {
    "mode": "fixed"
  },
  "template_id": "tmpl_support",
  "channel_type": "feishu",
  "name": "Support Feishu channel"
}

pairing mode

In pairing mode, the Channel only represents an IM transport connection — no Identity or Template is specified at creation:

{
  "identity_resolution": {
    "mode": "pairing"
  },
  "channel_type": "feishu",
  "name": "Support Feishu channel"
}

After channel authorization is complete, the pairing flow is:

1. A user sends a message from a real IM private chat or group chat to the bot.
2. Forward creates or reuses a 6-digit Pairing Code for the unpaired direct/room scope, replies only with a pairing prompt, and does not create a Session.
3. The admin calls Pair a channel with code + identity_id + template_id.
4. Subsequent messages resolve Identity and Template via the Pairing, then create or reuse a Session.
5. To revoke the binding, use the pairing_id from the Pair response to call Unpair a channel.

Direct scope uses the remote user as the pairing boundary; room scope uses the stable group/channel ID as the pairing boundary. Different members and threads within the same room share a Pairing, but Sessions and replies are still isolated per conversation/thread. Original messages that triggered pairing are not replayed after pairing succeeds — users need to send their request again.

identity_resolution.mode cannot be changed after creation. To switch between fixed and pairing, you must delete and recreate the Channel.

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

1. 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.
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 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:

{
  "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. 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) above.

Related

Create Channel

Create Channel QR Session

Pair a channel

Unpair a channel

List Channels