AgentKit Studio
Guides

Channels

Configure a channel connection, attach local or cloud agents, finish pairing and session binding, and verify message traffic in one place.

A channel answers two questions: where messages come from, and where replies go. It routes a WPS Collaboration, Feishu, or WeCom conversation to the agent you bound, then sends the answer back to the original conversation. The session itself still belongs to DSH; a channel is only an entry point.

Prerequisites

  • A reachable Channel service server URL and account id.
  • Local agent attachment additionally needs a workspace id and the connector credential (short-lived Connector JWT) issued to that agent.
  • An application registered for Studio on the channel platform, with an App ID and App secret.

What the channel connector does

ComponentResponsibility
Connection configurationRecords the server URL, account, workspace, and credentials; decides which tenant messages route into
ChannelOne IM application plus one account plus one conversation policy, bound to one agent
Pairing requestsThe admission queue when a newcomer first talks to the bot
Session bindingWhich DSH session one IM conversation maps to
Message recordsThe send/receive ledger used to confirm whether a reply left

Studio only manages and displays: data comes from the Channel API, and the plugin keeps no second copy. What you see here is the channel service's real state.

Steps

Open Channels

Go to Operations → Channels. The top-right badge reads Connection configured or Not configured — configure it first when it says the latter.

The connection URL must be HTTPS/WSS

A remote channel service accepts only https:// or wss://. Plain http:// or ws:// is allowed only for localhost, 127.0.0.1, and [::1]. The URL must not carry a user name, password, query string, or fragment, or saving fails with CHANNEL_URL_INVALID.

Fill in the connection configuration

Expand Connection configuration, fill four fields, then choose Save connection:

FieldRequiredNotes
Channel service URLYesFor example https://channel.example.com
Account idYesDecides which account the channel data belongs to
Workspace idOptionalUsed only for channel routing; it does not bind a local directory
Service credentialOptionalShows "Saved; leave blank to keep" once one exists

Credentials are never echoed back after saving, so leaving the field blank keeps the stored value.

Attach a local agent

Under Local agent attachment, pick an agent, paste the connector credential issued to it, and choose Enable connection.

The connection moves through connecting → registering → connected and normally completes within 10 seconds. Badge text per state:

StateLabel
connectedConnected
connectingConnecting
registeringRegistering
reconnectingReconnecting
stoppedDisabled
unavailableUnavailable
errorConnection failed

The failure reason appears inline:

ReasonMeaning
authentication_failedCredential invalid or expired
connection_failedCannot reach the channel service
protocol_errorChannel protocol or identity mismatch
configuration_invalidThe connection configuration is invalid
connection_replacedAnother device replaced this connection

Messages cannot be delivered while the device is offline

A local agent runs on your device. With the app closed or the machine asleep, messages cannot reach it — for 24×7 operation, deploy the agent to the cloud and bind the target under Cloud deployment in the channel.

Add a channel

Choose Add channel in the top-right and fill the dialog:

FieldConstraint
Bound agentTwo groups: Local · keep the app running and Cloud deployment · runs continuously in the cloud
Channel typeWPS Collaboration / Feishu / WeCom; immutable after creation
Channel account idThe account identifier on the channel platform; immutable after creation
Application App IDIssued by the channel platform for your Studio application
Application App secretIts key; never echoed after saving, and blank means keep the stored value while editing
Direct message policyPairing required (pairing, newcomers go through pairing) or Open (open)
Group policyAllowlist (allowlist) or Open (open)
Session scopePer user (per-peer) or Per group (per-group)
EnabledA new channel is enabled right after creation

Session scope decides how context splits

per-peer gives every direct-message user their own session; per-group gives one shared session per group. Changing this affects which history a session owns — confirm how the group is used before switching.

Scan to connect (Feishu / WeCom)

Scan to connect appears on a row only for feishu and wecom. Opening it fetches a connection URL; open that URL in a browser to finish authorization.

The URL comes from the Connector; Studio neither generates nor stores QR content. When the Host returns none, the dialog reports "The Host returned no connection URL".

Handle pairing requests

Switch to the Pairing requests tab. Columns are requester, channel, conversation type, and state.

  • Rows in state pending offer Approve and Reject.
  • After approval the conversation appears under Session bindings and the bot starts answering normally.

With nothing pending the table reads "No pending pairing requests".

Manage session bindings

Switch to Session bindings; each row is one IM conversation:

ActionEffect
Edit sessionSet the associated Session ID by hand; blank clears the association
Take overA human takes over; supply a reason (default "Handled manually"). The row then shows Taken over
Release takeoverHand the conversation back to the bot
UnbindDetach this IM conversation from the DSH session; irreversible

The bot stays silent while a takeover is active

Takeover signals "a human is handling this". Release it as soon as you are done, or the user will think the bot is broken.

Verify message records

Switch to Message records. The left side lists conversations (channel · count) and the right side shows bubbles:

  • Right-aligned bubbles are outbound, left-aligned are inbound; the time sits in the bottom-right corner.
  • A failed send carries an error line inside the bubble.

Before any conversation exists the pane reads "Messages appear here after a channel is connected and a conversation happens". This view is read-only; you cannot send from here.

Reconnection rules

ScenarioBehavior
Registration timeoutDisconnects and reconnects when no register_ok arrives within 10 seconds
DisconnectExponential backoff starting at 1 second, capped at 60 seconds
401 / 403Enters error without retrying, reason authentication_failed
Close code 4002Enters error, reason connection_replaced (the same agent connected from another device)
Close code 1008Enters error, reason authentication_failed
In-flight tasks at disconnectAborted; never replayed after reconnecting
Per-task timeout300 seconds by default; a task's deadline can cut it earlier

What success looks like

  • The top badge reads Connection configured and the local agent row reads Connected.
  • The "Total channels" metric is greater than 0 and "Enabled" matches it.
  • Session bindings shows the conversation you just paired, with a real Session value rather than "Unassociated".
  • Message records shows one complete round trip with no error line on the outbound bubble.

Common errors

CodeCauseFix
CHANNEL_URL_INVALIDThe server URL is not http(s), or a remote URL is plaintext or carries credentials/queryUse https:// remotely; http:// only for loopback
CHANNEL_CONFIG_INVALIDThe channel configuration file cannot be readCheck that the Host-side channels.json is readable
CHANNEL_NOT_CONFIGUREDNo server URL or account id yetSave the connection configuration first
CHANNEL_AGENT_UNAVAILABLEThe selected agent does not exist or is not locally createdPick again from the dropdown
CHANNEL_CONNECTOR_CONFIG_REQUIREDLocal attachment is missing the account, workspace id, or credentialAll three are required
CHANNEL_ACCOUNT_MISMATCHThe channel account does not match the cloud account of the current subaccountVerify the account id in the connection configuration
CHANNEL_ACTOR_REQUIREDA cloud channel operation lacks a verified subaccount identityRe-verify cloud identity
CHANNEL_PAIRING_UNAVAILABLEThe pairing request does not exist or is not accessibleRefresh and retry
CHANNEL_LOCAL_OFFLINEThe target local agent's channel connection is not enabledEnable that agent's connection first
CHANNEL_PROXY_FAILEDThe channel service request did not complete (network or timeout)Check the network and retry
CHANNEL_PROXY_ERRORThe channel service returned a business errorRead serviceCode in the error
CHANNEL_RESPONSE_INVALIDThe channel service returned a response that violates the contractVerify the server URL and version
CHANNEL_CATALOG_TOO_LARGEThis agent has too many channel conversationsClean up session bindings first

On this page