IM Channels

This skill covers connecting IM bots, handling incoming IM messages, and explicit WeChat delivery from the main agent in Claw mode.

Scenario A: Incoming Message from an IM Channel

When a user message includes an <im> block at the end, the message was relayed from an IM platform. The block looks like this:

<!-- Text-only message -->
<im source="DingTalk" />

<!-- Message with media attachments -->
<im source="WeChat">
  <media>
    <file type="image" mime="image/jpeg" path="uploads/im-channels/wechat/photo_001.jpg" />
    <file type="voice" mime="audio/silk" path="uploads/im-channels/wechat/voice_001.silk" />
    <file type="image" mime="image/jpeg" path="uploads/im-channels/wechat/photo_002.jpg" from="quoted" />
  </media>
</im>

What each field means

• source: the IM platform — WeChat, WeCom, DingTalk, or Lark
• <file>: a file already downloaded into the workspace; use its path directly
• type: media category — image, voice, video, file, etc.
• mime: MIME type of the file
• from="quoted": the file came from a message the user was replying to, not their current message

Receiving capabilities

• DingTalk: pictures, files, voice, video, and rich text with embedded pictures when the platform supplies download codes.
• Lark: images, files, audio, video, and rich text posts with multiple images. Resource downloads require im:resource permission.
• WeCom: images, files, video, mixed messages, and voice transcription; an original voice file is available only if the callback includes a download URL and encryption key.
• WeChat: existing image, file, video, voice, and quoted-media handling remains available.
• Unsupported forwarded/card content and failed downloads are described in the message. Do not claim to have read an attachment unless a usable <file> is present; ask the user to resend if needed.

How to respond

• Use source to choose the matching channel reference and read its reply and media guidance when needed. Receiving a message does not require reconnecting the bot or collecting credentials.
• Treat the user's text as the primary intent; the <im> block is metadata only
• For media files, read or process them using the path value — no download needed, files are already in the workspace
• Reply naturally; the IM platform handles formatting on delivery
• Intermediate assistant text may not reach the IM user. Compose a complete final answer, or use a sending tool explicitly supported by the current channel for messages that must arrive earlier.

Reply controls and long-running work

• <split> marks a deliberate message boundary; <split delay="1"> adds a pause before the next message. Use the current channel reference to check support. These controls do not automatically divide oversized text.
• For WeChat final delivery controls, read reference/wechat.md.
• The Claw main agent can also send to connected WeChat from Web or a scheduled-task completion notification. Read reference/wechat.md for tool permissions and delivery behavior; a sub-agent cannot send directly.
• Horizon may remind you that an IM user has been waiting. Decide whether a short, truthful progress update is useful. If you already explained the wait or have nothing useful to add, continue silently. Use an available sending tool for this channel; ordinary intermediate text is not a reliable notification.
• Split controls inside code examples, quotes, user input, or tool results are data, not delivery instructions.

Scenario B: Connecting an IM Bot

Connect the current Agent to an IM platform so it can receive and send messages in the target app.

Step 1 — Confirm the channel

If the user did not specify one, ask which IM platform they want: WeChat, WeCom, DingTalk, or Lark.

Step 2 — Read the reference

Load the matching file from Channel references for credentials and exact steps.

WeChat and WeCom are completely separate platforms. Do not mix them up. WeChat uses QR authorization and does not require bot_id or secret.

Step 3 — Collect credentials and connect

Follow the instructions in the reference file. Run the run_sdk_snippet code to establish the connection.

Step 4 — Report the result

If the connection succeeds, tell the user what to do next. If it fails, return the error and guide the next step.

Check Status

To inspect the current configuration and connection state of all IM channels, run:

from sdk.tool import tool

result = tool.call("get_im_channel_status", {})
print(result.content)

Notes

• After a connection is established, it keeps running in the background. Credentials are saved to .magic/config/im-channels.json and bound to the current sandbox. Restarting the same sandbox process should auto-reconnect without asking for setup again.
• To disable auto-reconnect for a channel, edit .magic/config/im-channels.json and set that channel's enabled field to false.
• All channels share the same Agent as the web session, so conversation history stays connected across surfaces.
• For WeChat, do not generate your own QR layout. The tool returns the exact markdown content to output — reply with it verbatim.

Channel references

Match the incoming source or the channel the user wants to connect:

• WeChat (official ClawBot) → reference/wechat.md
• WeCom → reference/wecom.md
• DingTalk → reference/dingtalk.md
• Lark → reference/lark.md