Channel Deployment Guide

Detailed guide for connecting your AI employee to Telegram or Lark.

Supported Channels

Channel	Status	Best For
Telegram	Available	International users, personal use
Lark (Feishu)	Available	Domestic teams, enterprise use
WeCom (企业微信)	Available	Domestic enterprise users
DingTalk (钉钉)	Available	Domestic teams, no public callback needed
WhatsApp	Available	International business users
Discord	Coming Soon	Developer/community scenarios
Slack	Available	European/US enterprise users
Microsoft Teams	Available	Enterprise teams, Microsoft 365 organizations
Zalo (Official)	Available	Vietnam users, personal & business use
Zalo Personal (Unofficial)	Available	Vietnam users, personal Zalo account (unofficial)

Tip: You can connect multiple channels simultaneously. Your AI employee responds across all connected channels. Pro plan supports Telegram + Lark dual-channel access.

Prerequisites

Item	Description
COCO Account	Registered and paid/trial active
Channel Account	Your Telegram or Lark platform account
~10 minutes	Time to complete deployment

You do NOT need:

• Any servers or technical infrastructure
• Any coding skills
• API keys or developer accounts
• Any technical knowledge

---

Option A: Telegram Deployment (Recommended for international users)

Estimated time: 5-8 minutes

Step 1: Create a Telegram Bot

1. Open Telegram, search for @BotFather (official bot manager)
2. Send /newbot command
3. Enter your Bot display name (e.g., My COCO AI)
4. Enter your Bot username (must end with bot, e.g., my_coco_ai_bot)
5. BotFather returns a Bot Token (format: 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw)
6. Copy and save this Token — you'll need it next

Important: The Bot Token is your bot's unique credential. Do not share it with others.

Step 2: Connect in COCO Dashboard

1. Log into COCO Dashboard
2. Open the Channels page and find the Telegram card
3. Paste the Bot Token from Step 1
4. Click Connect
5. System automatically validates the Token and completes connection

Step 3: Start Using

1. In Telegram, search for your Bot username (e.g., @my_coco_ai_bot)
2. Click Start or send /start
3. Send any message — AI employee responds immediately
4. Deployment complete!

Tip: Telegram is the simplest deployment. No admin permissions needed, no extra configuration. Recommended for first-time users.

Telegram FAQ

Issue	Solution
Bot not responding	Check if Token is correct, verify connection status in Dashboard
Slow responses	Check network connection. Telegram requires stable internet
Want multi-user access	Add Bot to a Telegram group. All group members can interact with AI
Want to switch Bot	Disconnect old one in Dashboard, create new Bot and reconnect

---

Option B: Lark / Feishu Deployment

Estimated time: 8-15 minutes

Note: Adding a self-built app (Bot) in Lark/Feishu requires enterprise admin approval. If you don't want to set up an enterprise Bot right away, you can first create a Lark personal account (international) or Feishu personal account (domestic). You can create and use Bots in your personal workspace without admin approval.

Lark (international) and Feishu (domestic China) have slightly different interfaces. Choose the guide that matches your platform:

Lark Deployment (Recommended for international teams)

WebSocket long connection: Only App ID and App Secret required — no Webhook URL, Verification Token, or public domain needed.

Step 1: Access Lark Open Platform

1. Visit Lark Open Platform
2. Log in with your Lark account
3. Click Developer Backend in the top-right corner

Step 2: Create a Custom App

1. In the Developer Backend, click Create Custom App
2. Enter app name (e.g., COCO AI Employee) and description
3. Click Create to finish

Tip: Enterprise admin permissions are required. If you're not an admin, contact your IT department or use a Lark personal account first.

Step 3: Add Bot Capability

In the app management page, go to Add Capabilities in the left sidebar, find the Bot card, and click "Configure" or "+ Add". After adding, a Bot menu item will appear in the left sidebar.

Important: You must add the Bot capability first before configuring messaging-related permissions (e.g., im:message.group_at_msg:readonly). Otherwise the permission checkbox will be disabled.

After adding, go to Credentials & Basic Info in the left sidebar and note down:

• App ID
• App Secret

Step 4: Configure Permissions

In the app management page, go to Permissions & Scopes. Click Batch Import/Export Permissions, paste the following JSON, and import all permissions at once:

{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "im:app_feed_card:write",
      "im:chat",
      "im:chat.announcement:read",
      "im:chat.announcement:write_only",
      "im:chat.chat_pins:read",
      "im:chat.chat_pins:write_only",
      "im:chat.collab_plugins:read",
      "im:chat.collab_plugins:write_only",
      "im:chat.labels",
      "im:chat.managers:write_only",
      "im:chat.members:bot_access",
      "im:chat.members:read",
      "im:chat.members:write_only",
      "im:chat.menu_tree:read",
      "im:chat.menu_tree:write_only",
      "im:chat.moderation:read",
      "im:chat.tabs:read",
      "im:chat.tabs:write_only",
      "im:chat.top_notice:write_only",
      "im:chat.widgets:read",
      "im:chat.widgets:write_only",
      "im:chat:create",
      "im:chat:delete",
      "im:chat:moderation:write_only",
      "im:chat:operate_as_owner",
      "im:chat:read",
      "im:chat:readonly",
      "im:chat:update",
      "im:datasync.feed_card.time_sensitive:write",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.group_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.urgent",
      "im:message.urgent:phone",
      "im:message.urgent:sms",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_depts",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "im:url_preview.update",
      "im:user_agent:read"
    ],
    "user": []
  }
}

Scope overview: The scopes above cover contacts (read), chat management (full), messaging (send/receive/recall/pin/react), group @mention listening, urgent messages, file resources, and feed cards. The im:message:send_multi_depts scope replaces the older im:message:send_multi_users name used in previous versions of the platform. The Feishu (domestic China) version uses a slightly smaller scope set — see the Feishu section for details.

Step 5: Connect in COCO Dashboard and Deploy

1. Log into COCO Dashboard
2. Go to the channel configuration page, select Lark
3. Enter the following credentials:

Field	Source
App ID	Lark Open Platform → Credentials & Basic Info
App Secret	Lark Open Platform → Credentials & Basic Info

4. Click Connect — the system will automatically deploy your AI employee (typically takes 2-3 minutes)

Tip: With WebSocket long connection, only App ID and App Secret are needed — no Verification Token, Encrypt Key, or Webhook URL required.

Step 6: Configure Event Subscription

1. Return to the Lark Developer Backend, go to Events & Callbacks

2. Under subscription mode, select Receive events through persistent connection

3. Click Add Events and subscribe to:

   • im.message.receive_v1 — Receive messages (required)
   • im.chat.member.bot.added_v1 — Bot added to group (optional)

4. Click Save

Tip: With persistent connection mode, no Request URL is needed — events are received automatically via WebSocket.

Step 7: Create Version and Publish

1. In the Lark Developer Backend, go to Version Management & Publishing
2. Click Create Version
3. Enter version number (e.g., 1.0.0) and update description
4. Confirm app capabilities and permissions, click Save
5. In the confirmation dialog, click Confirm Publish

Admin Approval: After publishing a Lark custom app, the enterprise admin must approve it in the Lark Admin Console before the app becomes active. If you're using a personal account, this step is not needed.

Step 8: Enable Bot and Add to Groups

1. In Lark Open Platform, go to Bot menu, confirm bot functionality is enabled
2. Open Lark client
3. Create or enter a group
4. Group Settings → Bots → Add Bot → Search for your app name
5. Confirm addition
6. @mention your bot in the group and send a message
7. AI employee responds → Deployment complete!

Also works in private chat: Search for your app name in Lark and start a direct conversation.

---

Feishu Deployment (Recommended for domestic China teams)

WebSocket (Recommended): Simplest setup — only needs App ID and App Secret, no Webhook URL or verification required.

Webhook (Traditional): Feishu pushes events to a Webhook URL — requires Verification Token configuration.

Step 1: Access Feishu Open Platform

1. Visit Feishu Open Platform
2. Log in with your Feishu account
3. Click Developer Backend in the top-right corner

Step 2: Create an Enterprise App

1. In the Developer Backend, click Create Custom App
2. Enter app name (e.g., COCO AI Employee) and description, select an app icon
3. Click Create to finish
4. After creation, go to Credentials & Basic Info in the left sidebar and note down:
   • App ID
   • App Secret

Tip: Enterprise admin permissions are required. If you're not an admin, contact your IT department or use a Feishu personal account first.

Step 3: Add Bot Capability and Configure Permissions

In the app management page, first add the Bot capability by clicking + Add, then go to Permission Management in the left sidebar.

In the Permission Management page, copy the following JSON and import all permissions at once:

{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "im:app_feed_card:write",
      "im:chat",
      "im:chat.announcement:read",
      "im:chat.announcement:write_only",
      "im:chat.chat_pins:read",
      "im:chat.chat_pins:write_only",
      "im:chat.collab_plugins:read",
      "im:chat.collab_plugins:write_only",
      "im:chat.managers:write_only",
      "im:chat.members:bot_access",
      "im:chat.members:read",
      "im:chat.members:write_only",
      "im:chat.menu_tree:read",
      "im:chat.menu_tree:write_only",
      "im:chat.moderation:read",
      "im:chat.tabs:read",
      "im:chat.tabs:write_only",
      "im:chat.top_notice:write_only",
      "im:chat.widgets:read",
      "im:chat.widgets:write_only",
      "im:chat:create",
      "im:chat:delete",
      "im:chat:moderation:write_only",
      "im:chat:operate_as_owner",
      "im:chat:read",
      "im:chat:readonly",
      "im:chat:update",
      "im:datasync.feed_card.time_sensitive:write",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "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.urgent",
      "im:message.urgent:phone",
      "im:message.urgent:sms",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_depts",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "im:url_preview.update",
      "im:user_agent:read"
    ],
    "user": []
  }
}

Feishu vs Lark scopes: The Feishu (domestic China) scope set above differs slightly from the Lark (international) version. Two scopes — im:chat.labels and im:message.group_msg:readonly — are not supported on the Feishu China platform and have been removed. All other scopes are identical.

Step 4: Get Verification Token

1. In app management, go to Events & Callbacks
2. Click the Encryption Strategy tab
3. Find the Verification Token at the bottom of the page, click the eye icon to view and copy it

Tip: On the same page you'll also find the Encrypt Key (optional). If you need encrypted communication, record this as well.

Step 5: Connect in COCO Dashboard and Deploy

1. Log into COCO Dashboard
2. Go to the channel configuration page, select Feishu
3. Enter the following credentials:

Field	Source
App ID	Feishu Open Platform → Credentials & Basic Info
App Secret	Feishu Open Platform → Credentials & Basic Info
Verification Token	Feishu Open Platform → Events & Callbacks → Encryption Strategy
Encrypt Key (optional)	Feishu Open Platform → Events & Callbacks → Encryption Strategy

4. Click Connect — the system will automatically deploy your AI employee (typically takes 2-3 minutes)
5. After deployment, the page will display your dedicated Webhook URL — copy this URL (needed in the next step)

Step 6: Configure Event Subscription

1. Return to the Feishu Developer Backend, go to Events & Callbacks
2. Under "Event Configuration", select Send events to developer server
3. Paste the Webhook URL from the previous step into the Request URL field
4. Subscribe to events:
   • im.message.receive_v1 — Receive messages (required)
   • im.chat.member.bot.added_v1 — Bot added to group (optional)
5. Click Save

Step 7: Create Version and Publish

1. In the Feishu Developer Backend, go to Version Management & Publishing
2. Click Create Version
3. Enter version number (e.g., 1.0.0) and update description
4. Confirm app capabilities and permissions, click Save
5. In the confirmation dialog, click Confirm Publish

Admin Approval: After publishing a Feishu custom app, the enterprise admin must approve it in the Feishu Admin Console before the app becomes active. If you're using a personal account, this step is not needed.

Step 8: Enable Bot and Add to Groups

1. In Feishu Open Platform, go to Bot menu, confirm bot functionality is enabled
2. Open Feishu client
3. Create or enter a group
4. Group Settings → Bots → Add Bot → Search for your app name
5. Confirm addition
6. @mention your bot in the group and send a message
7. AI employee responds → Deployment complete!

Also works in private chat: Search for your app name in Feishu and start a direct conversation.

---

Option C: WeCom (企业微信) Deployment

Estimated time: ~5 minutes

Version Note: This guide applies to WeCom component v0.1.1 and above (WebSocket long connection mode — no public IP or SSL required). If you are on the older v0.1.0 webhook mode, upgrade by sending 帮我升级 wecom 组件 via the Dashboard Web Console.

Only 2 credentials are required:

Credential	Description
Bot ID	Unique identifier for the intelligent robot
Secret	Robot authentication key

Step 1: Create an Intelligent Robot

In the WeCom Admin Console, go to Workbench (工作台) → Intelligent Robots (智能机器人) → click Create Robot (创建机器人).

Step 2: Select Creation Method

In the dialog, click 手动创建 > (Manual Creation), or use AI auto-generation.

Step 3: Switch to API Mode

At the bottom of the page, click 切换至 API 模式创建 (Switch to API Mode Creation).

Step 4: Enable Long Connection and Copy Credentials

1. Select 使用长连接 (Use Long Connection)
2. Copy the Bot ID and Secret displayed on the page
3. Set the Visibility Scope (可见范围) to determine who can use the bot
4. Click Save

Important: The Secret is only shown once at creation. Save it immediately.

Step 5: Connect in Dashboard

In the COCO Dashboard, go to the employee instance detail page → Conversation Entrance (会话入口) → click the WeCom Connection button → enter the Bot ID and Secret from Step 4. Click Connect.

WeCom FAQ

Issue	Solution
Bot not responding	Verify that Long Connection mode is enabled and the Bot ID / Secret are entered correctly
Secret lost	Delete the robot and create a new one — Secrets cannot be retrieved after creation

---

Option D: DingTalk (钉钉) Deployment

Estimated time: 8-12 minutes

Note: DingTalk (钉钉) is Alibaba's enterprise collaboration platform, widely used by Chinese companies. DingTalk uses Stream mode (WebSocket long connection), so no public callback URL is needed — deployment is simpler.

Three credentials are required:

Credential	Description
AppKey	Application unique identifier
AppSecret	Application credential key
RobotCode	Robot identifier (usually same as AppKey)

Step 1: Access DingTalk Open Platform and Create an Application

Visit the DingTalk Open Platform App Management page and click Create Application.

Step 2: Enter Application Name and Description

Enter the Application Name (e.g., COCO AI Employee) and Description, then click Save.

Step 3: Add Robot Capability

After saving, you'll be redirected to the "Add Capabilities" page. Click Add Robot capability.

Step 4: Configure Robot and Select Stream Mode

Open the robot configuration page, fill in the required information, select Stream Mode for message reception, then publish.

Note: Stream mode uses WebSocket long connections to receive messages — no public callback URL configuration needed, making deployment simpler.

Step 5: Version Management and Publishing

In the left sidebar, select Version Management & Publishing and click Create New Version.

Step 6: Set Application Visible Scope

Enter the version information, select the appropriate Visible Scope (which team members can see and use the Bot), then save and publish.

Step 7: Get AppKey, AppSecret, and RobotCode

In the application detail page under "Credentials & Basic Info":

• AppKey — application unique identifier
• AppSecret — click "Show" to view

On the robot configuration page, find the RobotCode (usually the same as AppKey).

Step 8: Enter Credentials in Dashboard

Enter the AppKey, AppSecret, and RobotCode into the COCO Dashboard's DingTalk channel configuration page and click Connect.

Step 9: Start Chatting

Search for the Bot name in DingTalk and start chatting with your AI employee.

Group usage: In a DingTalk group chat, @mention your Bot to interact with the AI employee.

DingTalk FAQ

Issue	Solution
Application not visible to team members	Check the Visible Scope in version publishing — ensure all intended users are included
Bot not responding in group	Confirm the robot has been added to the group and use @mention to trigger
AppSecret forgotten	View or reset in the application credentials page

---

Option E: Slack Deployment

Estimated time: 8-12 minutes

Note: Slack is widely used by European and US enterprises for team collaboration. Slack uses Socket Mode (WebSocket connection), so no public callback URL is needed — deployment is straightforward.

Two credentials are required:

Credential	Format	Description
Bot Token	xoxb-...	Bot User OAuth Token, used to call the Slack API
App Token	xapp-...	App-Level Token, used for Socket Mode connection

Step 1: Create a Slack App

1. Visit Slack App Management and log in
2. Click Create New App in the top-right corner
3. Select From scratch in the popup
4. Enter your App name (e.g., COCO AI Employee) and select the Workspace to install to
5. Click Create App to finish

Step 2: Enable Socket Mode and Generate App Token

1. In the App settings left sidebar, find Socket Mode
2. Toggle Enable Socket Mode on
3. When prompted to generate an App-Level Token:
   • Name the Token (e.g., zylos-socket)
   • Add Scope: search and select connections:write
   • Click Generate
4. Copy and save the generated Token (format: xapp-...)

Important: The App Token is displayed only once after generation. Save it immediately. If lost, you'll need to regenerate it.

Step 3: Configure Bot Token Scopes

1. In the left sidebar, go to OAuth & Permissions
2. Scroll down to the Scopes section
3. Under Bot Token Scopes, click Add an OAuth Scope and add the following permissions:

Scope	Purpose
app_mentions:read	Read @mentions of the bot
channels:history	Read messages in public channels
channels:read	View basic channel info
chat:write	Send messages as the bot
files:read	Read files shared with the bot
files:write	Upload files
groups:history	Read messages in private channels
groups:read	View basic private channel info
im:history	Read direct message history
im:read	View basic DM info
im:write	Start direct messages
reactions:read	Read emoji reactions
reactions:write	Add emoji reactions
users:read	View user info

Step 4: Install App to Workspace

1. Go back to the top of the OAuth & Permissions page
2. Click Install to Workspace (or Reinstall to Workspace)
3. Confirm the permissions in the authorization popup, click Allow
4. After installation, copy and save the Bot User OAuth Token (format: xoxb-...)

Important: Each time you modify Scopes, you must reinstall the App to Workspace. The Token will be regenerated — update your configuration accordingly.

Step 5: Enable Event Subscriptions

1. In the left sidebar, go to Event Subscriptions
2. Toggle Enable Events on
3. Expand Subscribe to bot events, click Add Bot User Event, and add:

Event	Purpose
message.im	Receive direct messages
message.channels	Receive messages in public channels
message.groups	Receive messages in private channels
app_mention	Receive @mentions

4. Click Save Changes at the bottom

Step 6: Configure App Home

1. In the left sidebar, go to App Home
2. Under Show Tabs:
   • Check Messages Tab
   • Check Allow users to send Slash commands and messages from the messages tab

This enables users to send direct messages to your bot in Slack.

Step 7: Send Tokens to Your AI Employee

Once the Slack App setup is complete, simply send both tokens to your AI employee in chat to finish the connection. For example:

Bot Token: xoxb-xxxxxxxx App Token: xapp-xxxxxxxx

Your AI employee will automatically configure the Slack channel connection.

Step 8: Start Chatting

1. In Slack, search for your Bot name or find it in the Apps list
2. Click to start a DM conversation — AI employee responds immediately
3. To use in a channel, invite the Bot by typing /invite @BotName in the channel
4. @mention your Bot to trigger responses in the channel
5. Deployment complete!

Tip: Slack Bot supports both DMs and channel @mentions. You can use it across multiple channels simultaneously.

Slack FAQ

Issue	Solution
Bot not responding	Re-send both Bot Token and App Token to your AI employee in chat
Bot not visible in Slack	Ensure the App is installed to Workspace (Step 4) and App Home is configured (Step 6)
Bot not responding in channels	The Bot must be invited to the channel first using /invite @BotName
Token regenerated after scope change	Reinstall the App to Workspace after any scope modification, then update tokens in Dashboard
Cannot send DMs to Bot	Confirm Messages Tab is enabled in App Home settings

---

Option F: WhatsApp Deployment

Estimated time: ~5 minutes

Note: WhatsApp connects via QR code scanning (linked device), similar to using WhatsApp Web. No API keys, developer accounts, or app configuration are needed — just a phone with WhatsApp installed.

Use a Dedicated WhatsApp Account

Please use a newly registered, dedicated WhatsApp account for the bot — do not use your personal WhatsApp account. The connected account will serve exclusively as the bot's number.

No credentials are required. You only need:

Item	Description
COCO AI Employee	An existing instance in COCO Dashboard
WhatsApp Account	A phone with WhatsApp installed and logged in
~5 minutes	Time to complete deployment

Step 1: Create an AI Employee and Enter Configuration Page

1. Log into COCO Dashboard
2. Create a new AI employee or select an existing instance
3. Click Configure → on the employee card to enter the instance detail page

Step 2: Click WhatsApp "Connect" and Wait for QR Code

1. In the channel list on the instance detail page, find the WhatsApp card
2. Click the Connect button
3. The system will prepare a WhatsApp session in the background — the QR code takes ~30 seconds to generate, please be patient
4. Once generated, the QR code refreshes automatically every 15 seconds

Important: Do not close the page or click repeatedly while waiting — this may trigger duplicate requests.

Step 3: Open WhatsApp on Your Phone → Linked Devices

1. Open WhatsApp on your phone
2. Tap Me (profile icon) in the bottom-right corner
3. In the settings list, tap Linked Devices

Step 4: Tap "Link a Device" and Scan the QR Code

1. On the "Linked Devices" page, tap the Link a Device button at the bottom
2. Your phone's camera opens — point it at the QR code displayed on the Dashboard in Step 2
3. Wait a few seconds for the connection to complete

Tip: If the QR code has expired, the Dashboard will automatically refresh it. Scan the latest QR code displayed.

Step 5: Verify Connection and Manage Chat Permissions

1. After successful scanning, the Dashboard automatically detects the connection — the WhatsApp card shows Connected
2. Deployment complete! You are now the Owner (administrator) of this WhatsApp bot

Verify the Bot Is Working

Search for your own WhatsApp account and send yourself a message — the AI employee will reply automatically. This confirms the connection is live.

Managing Who Can Chat with the Bot

By default, only the Owner can chat with the bot. To allow others to interact, configure access via two modes — just send a natural language instruction to the bot:

Allowlist Mode — Only specified phone numbers can chat:

Send to bot: Enable allowlist mode, add +1 555xxxx888 to the list

The bot will update its configuration automatically. Only users on the allowlist can initiate conversations.

Open Mode — Anyone can chat:

Send to bot: Enable open mode, anyone can DM you

The bot will open chat access to all users.

Note: WhatsApp linked devices may disconnect automatically if the phone is offline for an extended period. If disconnected, return to the Dashboard and scan the QR code again to reconnect.

WhatsApp FAQ

Issue	Solution
QR code takes a long time to appear	The first generation may take 30-60 seconds — this is normal. Do not close the page
QR code expired before scanning	The QR code auto-refreshes every 15 seconds. Use the latest one displayed
"Already in progress" error	A previous QR request is still running. Wait a moment and it will resolve automatically
Others can't message the bot	By default only the Owner can chat. Enable Allowlist or Open mode to grant access
WhatsApp disconnected after some time	Phone was offline too long. Reconnect by scanning QR code again from the Dashboard
Want to disconnect WhatsApp	Click the Disconnect button on the WhatsApp card in the instance detail page

---

Option G: Microsoft Teams Deployment

Estimated time: 15-20 minutes

Note: Microsoft Teams is widely used by enterprises on Microsoft 365. Deployment requires creating an Azure Bot resource, configuring permissions, and publishing the app via the Teams Developer Portal. No servers or coding skills needed — a free Azure tier is sufficient.

Four credentials are required:

Credential	Where to Find	Description
App ID	Azure Bot → Configuration → Microsoft App ID	Identifies your bot application
App Password	App Registration → Certificates & secrets → Secret Value	Authenticates your bot
Tenant ID	Azure Bot → Configuration → Directory (tenant) ID	Your organization's tenant identifier
App Catalog ID	Teams Developer Portal → Basic information → App ID	Identifies the app in the Teams catalog

Step 1: Create an Azure Bot

1. Go to Azure Portal, click Create a resource, and search for Azure Bot
2. Click Create and fill in:
   • Bot handle: a unique name (e.g., coco-ai-employee)
   • Resource group: select an existing one or create new
   • Pricing tier: F0 (Free)
   • Type of App: Single Tenant
   • Creation type: Create new Microsoft App ID
3. Click Review + create, then Create
4. When deployment completes, click Go to resource

Note: Creating an Azure Bot automatically creates an App Registration for you — no separate step needed.

Step 2: Configure the Bot and Note Credentials

1. In the Azure Bot resource, go to Configuration
2. Set the Messaging endpoint to your agent's MS Teams webhook URL:

   https://<your-agent-domain>/ms-teams/api/messages

   You can find this on the Microsoft Teams card in your employee's channel grid on the COCO Dashboard. Copy it and paste it here.
3. Note down the Microsoft App ID (this is your App ID) and App Tenant ID (this is your Tenant ID)
4. Click Apply
5. Go to Channels in the left sidebar, click Microsoft Teams, accept the terms, and click Apply to enable the Teams channel

Important: The Teams channel must be enabled on the Azure Bot resource. Without it, Teams will show an "Invalid Bot" error when users try to chat with the bot.

Step 3: Create a Client Secret

1. On the Configuration page, click Manage Password — this takes you to the App Registration page
2. Go to Certificates & secrets
3. Click New client secret
4. Enter a description (e.g., COCO Bot Secret) and choose an expiration period
5. Click Add
6. Copy the secret Value immediately — it is only shown once

Important: The client secret cannot be viewed again after you leave this page. Save it securely. This is your App Password.

Step 4: Configure Graph API Permissions

Instead of adding permissions one by one through the UI, you can paste them all at once via the manifest editor.

1. In the App Registration page (you should already be here from Step 3), go to the Manifest tab
2. Select the Microsoft Graph App Manifest (New) tab at the top
3. Find "requiredResourceAccess": [] and replace only the [] with the following array:

[
  {
    "resourceAppId": "00000003-0000-0000-c000-000000000000",
    "resourceAccess": [
      { "id": "01d4889c-1287-42c6-ac1f-5d1e02578ef6", "type": "Role" },
      { "id": "6b7d71aa-70aa-4810-a8d9-5d9fb2830017", "type": "Role" },
      { "id": "7b2449af-6ccd-4f4d-9f78-e550c193f0d1", "type": "Role" },
      { "id": "df021288-bdef-4463-88db-98f22de89214", "type": "Role" },
      { "id": "9ff7295e-131b-4d94-90e1-69fde507ac11", "type": "Scope" },
      { "id": "ebf0f66e-9fb1-49e4-a278-222f76911cf4", "type": "Scope" },
      { "id": "767156cb-16ae-4d10-8f8b-41b657c8c8c8", "type": "Scope" },
      { "id": "df85f4d6-205c-4ac5-a5ea-6bf408dba283", "type": "Scope" },
      { "id": "7427e0e9-2fba-42fe-b0c0-848c9e6a8182", "type": "Scope" }
    ]
  }
]

4. Click Save at the top of the Manifest page

Important: Replace only the empty [] after "requiredResourceAccess": — do not replace the entire line including the key name.

This adds all 9 permissions at once:

Permission	Type	What It Does
Files.Read.All	Application	Download files from OneDrive/SharePoint
Chat.Read.All	Application	Read DM and group chat history
ChannelMessage.Read.All	Application	Read team channel message history
User.Read.All	Application	Resolve user mentions and search users
Chat.ReadWrite	Delegated	Read and send chat messages on behalf of the user
ChannelMessage.Send	Delegated	Send channel messages on behalf of the user
ChannelMessage.Read.All	Delegated	Read channel messages on behalf of the user
Files.Read.All	Delegated	Access files the user can access
offline_access	Delegated	Maintain access when the user is not actively signed in

Grant Admin Consent

After saving the manifest, go to API permissions and click Grant admin consent for [your organization]. Confirm, and all 9 permissions should show a green checkmark.

Important: Admin consent is required. Without it, file downloads, chat history, emoji reactions, and smart mode features will not work.

Step 5: Create App in Teams Developer Portal

1. Go to Teams Developer Portal and sign in
2. Click Apps in the left sidebar, then + New app
3. Enter an app name (e.g., COCO AI Employee)
4. In Basic information, note the App ID shown at the top — this is your App Catalog ID (you'll need it when connecting in the COCO Dashboard)
5. Fill in the required fields:
   • Short description: e.g., AI-powered digital employee
   • Long description: e.g., COCO AI employee that helps your team with writing, research, translation, data analysis, and daily tasks — right inside Microsoft Teams.
   • Developer name: e.g., COCO
   • Website: https://coco.xyz
   • Privacy policy: https://docs.coco.xyz/privacy-policy
   • Terms of use: https://docs.coco.xyz/user-agreement
6. Click Save

Step 6: Configure the App Manifest

1. In the Teams Developer Portal, go to your app's App package → App package editor
2. Paste the following manifest JSON, replacing the two placeholders with your actual values:
   • Replace <TEAMS_APP_ID> (1 place) with the App ID from Step 5 (the App Catalog ID)
   • Replace <AZURE_APP_ID> (2 places) with the App ID from Step 2 (the Azure App Registration ID)

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
  "version": "1.0.0",
  "manifestVersion": "1.19",
  "id": "<TEAMS_APP_ID>",
  "name": { "short": "COCO AI Employee" },
  "developer": {
    "name": "COCO",
    "websiteUrl": "https://coco.xyz",
    "privacyUrl": "https://docs.coco.xyz/privacy-policy",
    "termsOfUseUrl": "https://docs.coco.xyz/user-agreement"
  },
  "description": {
    "short": "AI-powered digital employee",
    "full": "COCO AI employee that helps your team with writing, research, translation, data analysis, and daily tasks — right inside Microsoft Teams."
  },
  "icons": { "outline": "outline.png", "color": "color.png" },
  "accentColor": "#FFD646",
  "bots": [{
    "botId": "<AZURE_APP_ID>",
    "scopes": ["personal", "team", "groupChat"],
    "isNotificationOnly": false,
    "supportsCalling": false,
    "supportsVideo": false,
    "supportsFiles": true
  }],
  "permissions": ["messageTeamMembers"],
  "validDomains": [],
  "webApplicationInfo": {
    "id": "<AZURE_APP_ID>",
    "resource": "https://graph.microsoft.com"
  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        { "name": "ChatMessage.Read.Chat", "type": "Application" },
        { "name": "ChannelMessage.Read.Group", "type": "Application" }
      ]
    }
  }
}

3. Click Save at the top of the editor
4. Return to the App package editor page and click the Update button to apply your changes

Note on placeholders: The manifest has two different IDs. <TEAMS_APP_ID> is the App ID from the Teams Developer Portal (Step 5) — it appears once in the id field. <AZURE_APP_ID> is the App ID from Azure (Step 2) — it appears in botId and webApplicationInfo.id.

Step 7: Upload App Icons (Optional)

1. In the Teams Developer Portal, go to your app's Branding section
2. Upload the app icons:
   • Color icon: 192x192 PNG
   • Outline icon: 32x32 PNG with transparent background
3. Click Save

Tip: If you skip this step, Teams will use default placeholder icons.

Step 8: Publish the App

You have two options to distribute the app:

Option A — Publish to your organization:

1. In the Teams Developer Portal, go to Distribute → Publish to org
2. Submit the app for admin approval
3. An admin must approve the app in the Teams Admin Center → Manage apps
4. After approval, users should restart Microsoft Teams to see the new app

Option B — Sideload via app package (for admins):

1. In the Teams Developer Portal, click Download app package to get the .zip file
2. In Microsoft Teams, go to Apps → Manage your apps → Upload a custom app
3. Select the downloaded .zip file

Step 9: Connect in COCO Dashboard

Important: This step must be done last — all 4 credentials are required.

1. Log into COCO Dashboard
2. Go to the employee instance detail page
3. Find the Microsoft Teams card and click Connect
4. Enter the credentials:

Field	Source
App ID	Azure Bot → Configuration → Microsoft App ID (Step 2)
App Password	App Registration → Client Secret Value (Step 3)
App Catalog ID	Teams Developer Portal → Basic information → App ID (Step 5)
Tenant ID	Azure Bot → Configuration → App Tenant ID (Step 2)

5. Click Connect — the system will validate your credentials and deploy the channel

Step 10: Start Chatting

1. In Teams, search for your app name (e.g., COCO AI Employee)
2. Click to start a DM conversation
3. Send any message — AI employee responds immediately
4. Deployment complete!

Tip: To use in group chats or team channels, add the bot to a team or group chat, then @mention it to trigger a response.

Microsoft Teams FAQ

Issue	Solution
Bot not responding	Verify the Messaging endpoint is set correctly in Azure Bot Configuration. Check that credentials (App ID, App Password) match
Credential validation failed	Ensure App Password is the Value (not the Secret ID). Confirm the Tenant ID is correct
Bot not appearing in Teams	The app must be published and approved (or sideloaded). Check that the Azure App ID in the manifest matches your App Registration
App not visible after admin approval	Restart the Microsoft Teams client to pick up newly approved apps
Messages not reaching the bot	Confirm the Messaging endpoint URL is HTTPS and publicly reachable. Check that the Azure Bot resource is active
File downloads failing	Verify Files.Read.All has admin consent in Azure Portal → App Registration → API permissions
Smart mode not working	Verify ChannelMessage.Read.All has admin consent, and ensure the channel is set to smart mode
Client secret expired	Azure client secrets expire on the schedule you set. Create a new secret and update the App Password in COCO Dashboard
Want to disconnect	Click the Disconnect button on the Microsoft Teams card in the employee detail page

---

Option H: Zalo (Official) Deployment

Estimated time: ~5 minutes

Note: Zalo (Official) connects via the official Zalo Bot Platform API. Only a personal Zalo account is required — no Official Account (OA) registration, no servers, and no coding skills needed.

One credential is required:

Credential	Where to Find	Description
Bot Token	Zalo Bot Platform → Bot details page	Unique token identifying your bot (format: numeric_id:secret)

Step 1: Create a Bot on the Zalo Bot Platform

1. Visit the Zalo Bot Platform and log in with your Zalo account
2. Click Create Bot
3. Enter a bot name (e.g., COCO AI) and description
4. After creation, you will see your Bot Token (format: numeric_id:secret)
5. Copy and save this Token — you'll need it in the next step

Important: The Bot Token is your bot's unique credential. Do not share it with others.

Step 2: Connect in COCO Dashboard

1. Log into COCO Dashboard
2. Go to the employee instance detail page
3. Find the Zalo (Official) card and click Connect
4. Paste the Bot Token from Step 1
5. Click Connect — the system will validate the token and complete the connection

Step 3: Start Chatting

1. Open Zalo on your phone or desktop
2. Search for your bot name
3. Send any message — AI employee responds immediately
4. Deployment complete!

First message: The first user to send a DM to the bot becomes the Owner. The owner always has full access regardless of policy settings.

Zalo (Official) FAQ

Issue	Solution
Bot not responding	Verify the Bot Token is correct. Check the connection status in COCO Dashboard
Cannot send images to bot	Ensure the image is under 10 MB. Supported formats: JPG, PNG
Bot image not displaying	Outbound images must be hosted on a publicly accessible HTTPS URL
Others can't message the bot	By default only the Owner can chat. Enable Allowlist or Open mode to grant access
Want to disconnect	Click the Disconnect button on the Zalo (Official) card in the employee detail page

---

Option I: Zalo Personal (Unofficial) Deployment

Estimated time: ~2 minutes

Note: Zalo Personal (Unofficial) uses a real Zalo account via QR code scanning — no bot registration, API keys, or developer accounts needed. It connects through zca-js, a reverse-engineered protocol library.

Unofficial Protocol

Zalo Personal (Unofficial) uses an unofficial, reverse-engineered protocol (zca-js) that is not endorsed by Zalo/VNG. Your account could potentially be restricted or banned by Zalo. Use at your own risk. For an official integration, consider Zalo Bot Platform instead.

Use a Dedicated Zalo Account

Please use a separate, dedicated Zalo account for the bot — do not use the same Zalo account that users will use to talk to your COCO agent. The connected account becomes the bot's identity, so it must be a different account from any user who will interact with it.

No credentials are required. Authentication is done entirely via QR code:

Item	Description
COCO AI Employee	An existing AI employee with at least one channel already connected (e.g., Telegram, Lark, WhatsApp)
Dedicated Zalo Account	A phone with Zalo installed and logged in to a separate account — not the same account users will use to message your COCO agent
~2 minutes	Time to complete deployment

Step 1: Ask Your AI Employee to Install Zalo Personal (Unofficial)

Message your AI employee in any connected channel (Telegram, Lark, WhatsApp, etc.):

"Install the Zalo Personal (Unofficial) channel"

Your AI employee will install the Zalo Personal (Unofficial) component and generate a QR code, which it sends back to you in the chat.

Step 2: Scan the QR Code with Your Dedicated Zalo Account

1. Open Zalo on the phone logged in to your dedicated bot account (not your personal account)
2. Tap the QR code scanner (usually in the top-right corner of the home screen or in the search bar)
3. Point your camera at the QR code your AI employee sent you
4. Confirm the login on your phone when prompted

Step 3: Connection Confirmed

Your AI employee will confirm the connection is established. Your dedicated Zalo account is now the bot's identity on Zalo.

Step 4: Start Chatting

1. Anyone who sends a message to your dedicated bot Zalo account will receive AI-powered responses
2. Deployment complete!

First message: The first user to send a DM becomes the Owner (administrator). The owner always has full access regardless of policy settings.

Zalo Personal (Unofficial) FAQ

Issue	Solution
QR code expired before scanning	Ask your AI employee to generate a new QR code (e.g., "Reconnect Zalo Personal (Unofficial)")
Connection lost after some time	Zalo may disconnect long-running sessions. Ask your AI employee to reconnect (e.g., "Reconnect Zalo Personal (Unofficial)")
Account warning or restriction	This uses an unofficial protocol. If you receive a warning from Zalo, stop using the integration and consider switching to the official Zalo Bot Platform
Others can't message the bot	By default only the Owner can chat. Ask your AI employee to enable Allowlist or Open mode to grant access
Want to disconnect	Ask your AI employee to disconnect the Zalo Personal (Unofficial) channel (e.g., "Disconnect Zalo Personal (Unofficial)")