Introduction

YuChat provides a REST API for integrating with external systems and building chatbots.

📄 Download OpenAPI Specification

---

Creating a Bot

1. Add the Bot Assistant (aibot@yuchat.ai) to your workspace. This assistant is required for creating and managing bots.

   • Go to Workspace Settings → Invite to Team → Invite by Email → enter aibot@yuchat.ai

   • Once added, the assistant will appear in the AI Agents and Bots section below your channels list

     
     
     note

     You can interact with the Bot Assistant via direct messages. Send /help to see all available commands.

2. Send a direct message to the Bot Assistant with /botcreate <bot_name>

3. You'll receive a token to use for API authentication

   Example:

   Command:

   /botcreate TestBot

   Response:

   Bot TestBot created
Token: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJDbzVsR3ItZU51WnU0TjdUSEd2TGVHRGNWVk1oR1JXWlVLTmc0cFBxa2hBIn0.eyJleHAicJ1In0.Cncyq8zILO81Bv_wbNk5b5OuHLP76Vf94TRs2gUAq-Mvq3Qc4ZFNE_eMcpsvYr0q4DOAffpQ

4. Save your token securely

---

info

Bots can only send messages and perform actions in channels where they are members.

Adding a Bot to a Channel

1. Open the target channel
2. Open the Members list
3. Click Add People
4. Select the bot from the list
5. Click Invite

---

💡 Use the sidebar to browse available API methods, request/response schemas, and examples.

info

Base URL

• Cloud: https://yuchat.ai/

• On-Premises: Use your corporate API endpoint, e.g., https://api.company.com

  Note: Use the API domain, not the web client URL, or requests will fail.

Authentication

Include this header in every request:

Authorization: Bearer <your_token>

🔑 Some endpoints (e.g., sending messages or files) require workspaceId and chatId in the request body.

Finding Your workspaceId

1. Open YuChat in your browser and navigate to the target workspace

2. Open Developer Tools (F12)

3. Go to the Elements tab

4. Look for an element with the data-workspace-id attribute

   Example: <div data-workspace-id="RRvYqDwAvk">

   info

   If you have multiple workspaces, ensure you're inspecting the correct one.

5. Alternatively, open the Console tab and switch workspaces—you'll see: go to workspaceId: <ID>

Finding Your chatId

Check the browser URL when viewing a channel:

Example: https://web.yuchat.ai/testws/channels/w:eXtXOs0sT2

The chatId is w:eXtXOs0sT2.

Key Concepts

Identifier	Description
workspaceId	Unique identifier for a workspace
chatId	Identifier for channels, direct messages, threads, or meeting discussions
membershipId	User identifier within a specific workspace
accountId	Global user identifier
messageId	Unique identifier for a message

Tip: The chatId prefix indicates the chat type: w: = channel, p: = direct message, t: = thread

Bot Management

Bots aren't tied to their creator—any workspace administrator can manage them. If a token is compromised, regenerate it with /botnewtoken; the old token is immediately invalidated.

Event Lifecycle

Bot events expire after 10 minutes by default. Events older than this cannot be retrieved via the API.

Troubleshooting

"is not a correct id" error

Check that:

• All required fields are present in your request
• Field names use exact casing (chatId, not ChatId or chat_id)
• Chat IDs include the type prefix (w:BDK5NyCqIK, not just BDK5NyCqIK)