Tencent Rtc Skills

Call TUICallKit Integration Skill (Multi-Platform Aggregation)

📌 Parent Skill: This is a sub-skill of tencent-rtc-skills (root skill).

If user's intent is ambiguous across products (Chat/Call/Live/Room), load the root skill first for product recommendation.

📌 Global Reference: This sub-skill follows the global standards defined in ROOT SKILL:

- Skill-First Principle (priority order)

- Boundary Recognition Pattern

- MCP Tools Reference (record_prompt, get_usersig, record_result)

- MCP Tool Call Sequence Pattern

- Documentation-Driven Integration Rules

- Silent Execution Rules

- Zero External Configuration

- Auto-Fetch Authentication Credentials

- Agent Execution Checklist Template

>

Call-specific rules below may EXTEND or OVERRIDE global rules where explicitly noted.

---

🔵 Boundary Recognition (Call-Specific)

Keywords That CONFIRM Call Scope

Only proceed with Call integration if user's request contains:

• call, phone call, video call, voice call
• 1-to-1, one-to-one, peer-to-peer
• dial, answer, hang up, incoming call, ringtone
• TUICallKit, CallKit
• WeChat call-like

OUT OF SCOPE → Redirect

📌 Reference: See ROOT SKILL for global Boundary Recognition Pattern.

⚠️ Special Case: "video conference" Redirection

CRITICAL: When user says "video conference", Agent MUST redirect to Room:

User: "Use CallKit to implement video conference"

Agent Response:
"Note: TUICallKit is designed for **peer-to-peer calls** (like WeChat calls), not for conferences.

For **video conference** needs, I strongly recommend **TUIRoomKit (Room)**:
- ✅ Designed specifically for meeting scenarios
- ✅ Supports member management (mute all, kick, roles)
- ✅ Supports screen sharing
- ✅ Suitable for multi-person meetings

If you really need simple 1-to-1 or small group calls (without meeting features), I can continue with TUICallKit.
Please confirm your requirements."

---

Overview

This Skill serves as the multi-platform aggregation entry point for Tencent Cloud Call TUICallKit, applicable to the following scenarios: 1. Users need audio/video call features but have not specified a platform/framework 2. Need to understand capability differences and selection recommendations across platforms 3. Need cross-platform common concepts and knowledge

Platform-Specific Guidance: Once the platform is determined, please use the corresponding sub-Skill:

• call/vue - Vue3 Web Applications
• call/react - React Web Applications
• call/android - Android Native Applications
• call/ios - iOS Native Applications
• call/flutter - Flutter Cross-Platform Applications

---

🎯 When to Use Call vs Room

Use Call (TUICallKit) When:

Use Room (TUIRoomKit) Instead When:

---

🔄 Product Selection Guidance

When user's requirement is ambiguous, clarify:

User: "Implement audio/video communication feature"

Agent should ask:
"What is your audio/video communication requirement:
1. **1-to-1 or Small Group Calls** (like WeChat calls, with incoming ringtone) → Recommend TUICallKit
2. **Multi-person Video Conference** (like Tencent Meeting, with member management) → Recommend TUIRoomKit

Please select your scenario, and I will load the corresponding integration guide."

---

Core Features

TUICallKit provides:

1. Call Types

• Voice Call - Audio-only calls
• Video Call - Audio + video calls
• Group Call - Multi-person calls (up to 9)

2. Call Flow

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  Idle   │ ──▶ │ Calling │ ──▶ │Connected│ ──▶ │  Ended  │
└─────────┘     └─────────┘     └─────────┘     └─────────┘
                    │               ▲
                    │  (Answer)     │
                    ▼               │
               ┌─────────┐         │
               │ Ringing │ ────────┘
               └─────────┘

3. UI Components

• Incoming Call UI - Shows caller info, accept/reject buttons
• Calling UI - Shows callee info, hang up button
• In-Call UI - Video view, controls (mute, speaker, camera)
• Floating Window - Mini window when app is backgrounded

4. Call Features

• Ringtone customization
• Call timeout handling
• Network quality indicators
• Camera/microphone control
• Speaker/earpiece switching

---

🔴 Mandatory MCP Tool Usage

📌 Reference: See ROOT SKILL "Global: MCP Tool Call Sequence Pattern" for universal sequence.

Call-Specific Tools

---

📁 Sub-Skill Directory

---

Keywords for Intent Matching

When user prompt contains these keywords, this skill (or its sub-skills) should be considered:

Primary Keywords (Strong match):

• call, phone call, video call, voice call
• TUICallKit, CallKit
• dial, answer, hang up, incoming call
• 1-to-1, one-to-one, peer-to-peer

Secondary Keywords (May also match Room):

• audio/video
• video chat

Exclusion Keywords (Prefer other products):

• meeting, conference → Room
• live streaming, host → Live
• chat, IM, message → Chat

React Chat TUIKit Component Selection Guide

This document helps developers choose the correct components and integration methods based on business requirements.

Decision Flow Chart

                    ┌─────────────────────────────┐
                    │  What type of chat feature  │
                    │        do you need?         │
                    └─────────────────────────────┘
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
        ┌───────────┐     ┌───────────┐     ┌───────────┐
        │ Complete  │     │ Embedded  │     │  Highly   │
        │  IM App   │     │   Chat    │     │Customized │
        └───────────┘     └───────────┘     └───────────┘
                │                 │                 │
                ▼                 ▼                 ▼
        ┌───────────┐     ┌───────────┐     ┌───────────┐
        │ full-     │     │ chat-only │     │ Composite │
        │ featured  │     │           │     │Integration│
        └───────────┘     └───────────┘     └───────────┘
                │                 │                 │
                ▼                 ▼                 ▼
        ┌───────────┐     ┌───────────┐     ┌───────────┐
        │ <TUIKit/> │     │ <Chat/>   │     │ Individual│
        │Full Suite │     │Chat Window│     │ Components│
        └───────────┘     └───────────┘     └───────────┘

Scenario Comparison Table

Scenario 1: Complete Instant Messaging Application

Characteristics:

• Need conversation list + chat window
• Need contacts/friend management
• Standalone chat module or Tab

Recommended Solution: full-featured mode

MCP Call:

Tool: get_web_chat_uikit_integration
Parameters: { framework: "react", goals: ["full-featured"] }

Applicable Cases:

• Social Apps
• Enterprise Internal Communication Tools
• WeChat/WeCom-like Applications
• Online Education Platforms (Teacher-Student Communication)

---

Scenario 2: Embedded Customer Service/Consultation Window

Characteristics:

• Only need chat window
• Embed into existing pages
• No conversation list needed

Recommended Solution: chat-only mode

MCP Call:

Tool: get_web_chat_uikit_integration
Parameters: { framework: "react", goals: ["chat-only"] }

Applicable Cases:

• E-commerce Customer Service Window
• Order Detail Page Private Chat
• Online Medical Consultation
• Technical Support Dialog

---

Scenario 3: Highly Customized Interface

Characteristics:

• Need complete control over UI styles
• Need custom interaction logic
• Only use partial features

Recommended Solution: Composite Integration (use individual components)

MCP Call:

Tool: get_web_chat_uikit_component_detail
Parameters: { framework: "react", componentName: "<specific_component>" }

Component Combination Examples:

---

Component Feature Comparison

Core Components

Fine-Grained Components

---

Recommendations by Business Scenario

E-commerce Platform

Recommended Components:
├── Buyer Side: chat-only mode
│   └── Embed Chat component in order page
│
└── Seller Side: full-featured mode
    └── Standalone customer service workstation

Online Education

Recommended Components:
├── Student Side: 
│   ├── ConversationList (course group list)
│   └── Chat (course group chat)
│
└── Teacher Side:
    ├── ConversationList (class group list)
    ├── Chat (group chat/private chat)
    └── ContactList (student management)

Medical Consultation

Recommended Components:
├── Patient Side: chat-only mode
│   └── Consultation window
│
└── Doctor Side: 
    ├── ConversationList (patient list)
    ├── Chat (consultation dialogue)
    └── ChatSetting (conversation management)

Enterprise Internal Communication

Recommended Components:
└── full-featured mode
    ├── ConversationList (conversation list)
    ├── Chat (chat window)
    ├── ContactList (contacts)
    └── Search (global search)

---

Component Dependency Relationships

TUIKit (Complete Suite)
├── ConversationList (Conversation List)
│   └── Avatar
├── Chat (Chat Window)
│   ├── ChatHeader (Header)
│   │   └── Avatar
│   ├── MessageList (Message List)
│   │   └── Avatar
│   └── MessageInput (Input Box)
├── ContactList (Contacts)
│   └── Avatar
├── Search
└── ChatSetting (Settings)

Dependency Notes:

• When using Chat component, it automatically includes ChatHeader, MessageList, MessageInput
• If individual customization is needed, you can import sub-components only

---

React-Specific Considerations

Hooks Usage

When using TUIKit components with React hooks:

import { useState, useEffect } from 'react';
import { TUIConversationService } from '@tencentcloud/chat-uikit-engine';

function ChatPage() {
  const [isReady, setIsReady] = useState(false);
  
  useEffect(() => {
    // Set up conversation after login
    TUIConversationService.switchConversation('C2Cadministrator')
      .then(() => setIsReady(true));
  }, []);
  
  if (!isReady) return <div>Loading...</div>;
  
  return <Chat />;
}

Context Providers

TUIKit uses React Context for state management. Ensure components are wrapped properly:

import { TUIKit } from '@tencentcloud/chat-uikit-react';

function App() {
  return (
    <TUIKit SDKAppID={SDKAppID} userID={userID} userSig={userSig}>
      {/* All chat components must be inside TUIKit */}
      <YourChatComponents />
    </TUIKit>
  );
}

Performance Optimization

For large conversation lists, consider:

import { memo } from 'react';

// Memoize custom components to prevent unnecessary re-renders
const MemoizedConversationItem = memo(({ conversation }) => {
  return <div>{conversation.conversationID}</div>;
});

---

Get Component Details

After determining needed components, get detailed documentation via MCP tool:

Tool: get_web_chat_uikit_component_detail
Parameters: 
  - framework: "react"
  - componentName: "conversation-list" (or other component name)

componentName Options:

• component-list - Component Overview
• tuikit - Complete Suite
• chat - Chat Window
• chat-header - Chat Header
• conversation-list - Conversation List
• message-list - Message List
• message-input - Message Input
• contact-list - Contacts
• search - Search
• chat-setting - Chat Settings
• avatar - Avatar

---

Version Requirements

React Chat TUIKit Troubleshooting Guide

This document collects in-depth troubleshooting experience beyond the MCP FAQ tool for Agent and developer reference.

---

1. React Version Issues 🔴

1.1 React 19 Compatibility Error

Symptoms:

Error: React 19 is not supported

or

Warning: Invalid hook call. Hooks can only be called inside of the body of a function component.

Cause: TUIKit currently does not support React 19

Solution: When creating a new project, ensure React version is 18.2.0:

# Using Vite
npm create vite@latest my-chat-app -- --template react
cd my-chat-app

# Modify package.json to use React 18.2.0

Modify package.json:

{
  "dependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

Then reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

1.2 Multiple React Instances

Symptoms:

Warning: Invalid hook call. Hooks can only be called inside of the body of a function component.

Cause: Multiple React instances in the project

Solution:

# Check for duplicate React installations
npm ls react

# If multiple versions exist, ensure only one version
npm dedupe

---

2. Vite Build Errors

2.1 esbuild Related Errors

Symptoms:

Error: The esbuild binary for the current platform is not installed

or

Error: Cannot find module 'esbuild'

Cause: Some dependency packages are incompatible with esbuild

Solution: Add patch configuration to package.json:

{
  "overrides": { 
    "esbuild": "npm:esbuild-wasm@latest" 
  },
  "resolutions": { 
    "esbuild": "npm:esbuild-wasm@latest" 
  }
}

Then reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

2.2 Dependency Resolution Errors

Symptoms:

[vite] Internal server error: Failed to resolve import

Solution: Add configuration to vite.config.ts:

export default defineConfig({
  optimizeDeps: {
    include: ['@tencentcloud/chat-uikit-react']
  }
});

2.3 React Refresh Plugin Error

Symptoms:

Error: @vitejs/plugin-react cannot be used with React 19

Solution: Ensure using React 18.2.0 and update vite plugin:

npm install @vitejs/plugin-react@latest

---

3. CSS Style Issues

3.1 Styles Not Matching Integration Documentation 🔴

Symptoms: Generated code uses custom style class names or modifies official styles

Cause: Agent did not strictly follow CSS styles in integration documentation when generating code

Solution: 1. Re-call get_web_chat_uikit_integration MCP tool to get latest integration documentation 2. Completely copy all CSS style code from integration documentation 3. Strictly use class names, variable names, and style properties from integration documentation 4. Prohibit any form of modification or customization

CSS Specifications Agent Must Follow:

• ✅ Use official class names (e.g., .chat-layout, .chat-content-panel)
• ✅ Use official CSS variables (e.g., --bg-color-operate, --stroke-color-primary)
• ✅ Completely copy official #root style configuration
• ❌ Prohibited from creating custom style class names
• ❌ Prohibited from modifying official style properties

3.2 Component Styles Not Taking Effect

Checklist: 1. Confirm style files have been imported 2. Check import order (TUIKit styles should come before custom styles) 3. Check if CSS Reset is overriding

Correct Import Method:

// index.tsx or App.tsx - Import in order following integration documentation
import '@tencentcloud/chat-uikit-react/styles/index.css';

3.3 Style Conflicts with Other UI Frameworks

Symptoms: Style disorder when using Material UI / Ant Design and other frameworks

Solution:

/* Add scope isolation on chat container */
.chat-container {
  box-sizing: border-box;
}

.chat-container * {
  box-sizing: border-box;
}

---

4. chat-only Mode Issues

4.1 Contains Features It Shouldn't Have

Symptoms: Code generated in chat-only mode contains Sidebar, ChatSetting, or in-conversation search features that user didn't request

Cause: Agent didn't correctly judge user requirements and arbitrarily added extended features

Judgment Criteria:

• ✅ Should Add: User explicitly states "need ChatSetting", "want to integrate search", "add settings feature", etc.
• ❌ Should Not Add: User only says "build chat-only chat window" without mentioning extended features

Features Excluded by Default: 1. Sidebar 2. ChatSetting (Chat Settings) 3. Search (In-conversation Search) 4. ConversationList (Conversation List)

Solution: Regenerate code, ensure extended features are not included by default

4.2 Conversation Activation Failed

Symptoms: Empty chat window in chat-only mode

Cause: setActiveConversation not set correctly

Solution: Ensure code contains default conversation activation logic:

import { TUIConversationService } from '@tencentcloud/chat-uikit-engine';

// Activate default conversation after successful login
TUIConversationService.switchConversation('C2Cadministrator');

---

5. Login & Authentication Issues

5.1 Login Timeout

Symptoms:

Error: Login timeout

Troubleshooting Steps: 1. Check network connection 2. Check if SDKAppID is correct 3. Check if UserSig has expired 4. Check firewall/proxy settings

5.2 Invalid UserSig

Common Causes:

• UserSig has expired (default validity is 7 days)
• UserID doesn't match the UserID used when generating UserSig
• SDKAppID mismatch

Solution: Re-call get_usersig MCP tool to generate new credentials.

5.3 Credential Configuration Error

Symptoms: Agent created config.js or .env file

Cause: Violated "Zero External Configuration" rule

Correct Approach:

• ❌ Prohibited from creating config.js, .env and other configuration files
• ✅ Inject SDKAppID, UserID, UserSig directly into code variables

// Correct: Use credentials directly in code
const SDKAppID = 1400000000; // Obtained from get_usersig
const userID = 'user001';
const userSig = 'eJw...'; // Obtained from get_usersig

---

6. Dependency Installation Issues

6.1 Node.js Version Incompatible

Symptoms:

Error: The engine "node" is incompatible with this module

Solution:

# Check Node version
node -v

# Use nvm to switch to compatible version (requires 16+)
nvm install 18
nvm use 18

6.2 Dependency Installation Failed

Symptoms:

npm ERR! peer dep missing: react@^18.0.0

Solution:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

6.3 TypeScript Type Errors

Symptoms:

Cannot find module '@tencentcloud/chat-uikit-react' or its corresponding type declarations

Solution: Add to tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true
  }
}

---

7. Message Sending Issues

7.1 Message Send Failed

Troubleshooting Steps: 1. Confirm successful login 2. Check if target user/group exists 3. Check network connection 4. View console error messages

Common Error Codes:

7.2 Image/File Send Failed

Common Causes:

• File size exceeds limit (images 20MB, files 100MB)
• File format not supported
• Upload service configuration issue

---

8. Project Startup Issues

8.1 Auto-Start Failed

Symptoms: Project didn't start normally after executing npm install && npm run dev

Troubleshooting Steps: 1. Check scripts configuration in package.json 2. Check if port is occupied 3. Check if dependencies are fully installed

Standard Start Command:

cd [project_path] && npm install && npm run dev

8.2 Component Not Found

Symptoms: Console error showing component is undefined or cannot find module

Solution: Ensure TUIKit is correctly imported in your App component:

import React from 'react';
import { TUIKit } from '@tencentcloud/chat-uikit-react';
import '@tencentcloud/chat-uikit-react/styles/index.css';

function App() {
  return (
    <TUIKit SDKAppID={SDKAppID} userID={userID} userSig={userSig}>
      {/* Chat components */}
    </TUIKit>
  );
}

export default App;

8.3 Hooks Error in Class Components

Symptoms:

Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

Cause: Attempting to use TUIKit hooks in class components

Solution: Convert class components to functional components or create wrapper components:

// Wrong: Class component
class ChatPage extends React.Component {
  // Cannot use hooks here
}

// Correct: Functional component
function ChatPage() {
  // Can use hooks here
  return <Chat />;
}

---

9. Debugging Tips

9.1 Enable SDK Logs

import TIM from '@tencentcloud/chat';

// Enable Debug mode
TIM.setLogLevel(0); // 0: Debug, 1: Log, 2: Warn, 3: Error

9.2 Listen to Global Events

import { TUIStore, StoreName } from '@tencentcloud/chat-uikit-engine';

// Listen to conversation list changes
TUIStore.watch(StoreName.CONV, {
  conversationList: (list) => {
    console.log('Conversation list updated:', list);
  }
});

9.3 React Developer Tools

Use React Developer Tools browser extension to:

• Inspect component hierarchy
• Check component props and state
• Profile component performance

9.4 Network Request Analysis

In browser developer tools Network panel:

• Filter wss:// to view WebSocket connections
• Filter XHR to view HTTP requests
• Check error messages in request responses

---

10. Common React-Specific Issues

10.1 State Update After Unmount

Symptoms:

Warning: Can't perform a React state update on an unmounted component

Solution: Clean up subscriptions and async operations in useEffect cleanup:

useEffect(() => {
  let mounted = true;
  
  // Async operation
  fetchData().then(data => {
    if (mounted) {
      setData(data);
    }
  });
  
  return () => {
    mounted = false;
  };
}, []);

10.2 StrictMode Double Rendering

Symptoms: Components render twice in development

Cause: React StrictMode intentionally double-invokes certain functions

Solution: This is expected behavior in development. It will not happen in production. If it causes issues:

// In index.tsx, you can remove StrictMode for testing
// But keep it for better error detection
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

---

Related Resources

• Official Documentation: Obtain via MCP tool get_web_chat_uikit_integration
• FAQ Query: Query via MCP tool get_faq
• Component API: Obtain via MCP tool get_web_chat_uikit_component_detail

Vue Chat TUIKit Component Selection Guide

This document helps developers choose the correct components and integration methods based on business requirements.

Decision Flow Chart

                    ┌─────────────────────────────┐
                    │  What type of chat feature  │
                    │        do you need?         │
                    └─────────────────────────────┘
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
        ┌───────────┐     ┌───────────┐     ┌───────────┐
        │ Complete  │     │ Embedded  │     │  Highly   │
        │  IM App   │     │   Chat    │     │Customized │
        └───────────┘     └───────────┘     └───────────┘
                │                 │                 │
                ▼                 ▼                 ▼
        ┌───────────┐     ┌───────────┐     ┌───────────┐
        │ full-     │     │ chat-only │     │ Composite │
        │ featured  │     │           │     │Integration│
        └───────────┘     └───────────┘     └───────────┘
                │                 │                 │
                ▼                 ▼                 ▼
        ┌───────────┐     ┌───────────┐     ┌───────────┐
        │ <TUIKit/> │     │ <Chat/>   │     │ Individual│
        │Full Suite │     │Chat Window│     │ Components│
        └───────────┘     └───────────┘     └───────────┘

Scenario Comparison Table

Scenario 1: Complete Instant Messaging Application

Characteristics:

• Need conversation list + chat window
• Need contacts/friend management
• Standalone chat module or Tab

Recommended Solution: full-featured mode

MCP Call:

Tool: get_web_chat_uikit_integration
Parameters: { framework: "vue", goals: ["full-featured"] }

Applicable Cases:

• Social Apps
• Enterprise Internal Communication Tools
• WeChat/WeCom-like Applications
• Online Education Platforms (Teacher-Student Communication)

---

Scenario 2: Embedded Customer Service/Consultation Window

Characteristics:

• Only need chat window
• Embed into existing pages
• No conversation list needed

Recommended Solution: chat-only mode

MCP Call:

Tool: get_web_chat_uikit_integration
Parameters: { framework: "vue", goals: ["chat-only"] }

Applicable Cases:

• E-commerce Customer Service Window
• Order Detail Page Private Chat
• Online Medical Consultation
• Technical Support Dialog

---

Scenario 3: Highly Customized Interface

Characteristics:

• Need complete control over UI styles
• Need custom interaction logic
• Only use partial features

Recommended Solution: Composite Integration (use individual components)

MCP Call:

Tool: get_web_chat_uikit_component_detail
Parameters: { framework: "vue", componentName: "<specific_component>" }

Component Combination Examples:

---

Component Feature Comparison

Core Components

Fine-Grained Components

---

Recommendations by Business Scenario

E-commerce Platform

Recommended Components:
├── Buyer Side: chat-only mode
│   └── Embed TUIChat component in order page
│
└── Seller Side: full-featured mode
    └── Standalone customer service workstation

Online Education

Recommended Components:
├── Student Side: 
│   ├── conversation-list (course group list)
│   └── chat (course group chat)
│
└── Teacher Side:
    ├── conversation-list (class group list)
    ├── chat (group chat/private chat)
    └── contact-list (student management)

Medical Consultation

Recommended Components:
├── Patient Side: chat-only mode
│   └── Consultation window
│
└── Doctor Side: 
    ├── conversation-list (patient list)
    ├── chat (consultation dialogue)
    └── chat-setting (conversation management)

Enterprise Internal Communication

Recommended Components:
└── full-featured mode
    ├── conversation-list (conversation list)
    ├── chat (chat window)
    ├── contact-list (contacts)
    └── search (global search)

---

Component Dependency Relationships

TUIKit (Complete Suite)
├── ConversationList (Conversation List)
│   └── Avatar
├── Chat (Chat Window)
│   ├── ChatHeader (Header)
│   │   └── Avatar
│   ├── MessageList (Message List)
│   │   └── Avatar
│   └── MessageInput (Input Box)
├── ContactList (Contacts)
│   └── Avatar
├── Search
└── ChatSetting (Settings)

Dependency Notes:

• When using Chat component, it automatically includes ChatHeader, MessageList, MessageInput
• If individual customization is needed, you can import sub-components only

---

Get Component Details

After determining needed components, get detailed documentation via MCP tool:

Tool: get_web_chat_uikit_component_detail
Parameters: 
  - framework: "vue"
  - componentName: "conversation-list" (or other component name)

componentName Options:

• component-list - Component Overview
• tuikit - Complete Suite
• chat - Chat Window
• chat-header - Chat Header
• conversation-list - Conversation List
• message-list - Message List
• message-input - Message Input
• contact-list - Contacts
• search - Search
• chat-setting - Chat Settings
• avatar - Avatar

Vue Chat TUIKit Troubleshooting Guide

This document collects in-depth troubleshooting experience beyond the MCP FAQ tool for Agent and developer reference.

---

1. Vite Build Errors

1.1 esbuild Related Errors

Symptoms:

Error: The esbuild binary for the current platform is not installed

or

Error: Cannot find module 'esbuild'

Cause: Some dependency packages are incompatible with esbuild

Solution: Add patch configuration to package.json:

{
  "overrides": { 
    "esbuild": "npm:esbuild-wasm@latest" 
  },
  "resolutions": { 
    "esbuild": "npm:esbuild-wasm@latest" 
  }
}

Then reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

1.2 Dependency Resolution Errors

Symptoms:

[vite] Internal server error: Failed to resolve import

Solution: Add configuration to vite.config.ts:

export default defineConfig({
  optimizeDeps: {
    include: ['@tencentcloud/chat-uikit-vue3']
  }
});

---

2. CSS Style Issues

2.1 Styles Not Matching Integration Documentation 🔴

Symptoms: Generated code uses custom style class names or modifies official styles

Cause: Agent did not strictly follow CSS styles in integration documentation when generating code

Solution: 1. Re-call get_web_chat_uikit_integration MCP tool to get latest integration documentation 2. Completely copy all CSS style code from integration documentation 3. Strictly use class names, variable names, and style properties from integration documentation 4. Prohibit any form of modification or customization

CSS Specifications Agent Must Follow:

• ✅ Use official class names (e.g., .chat-layout, .chat-content-panel)
• ✅ Use official CSS variables (e.g., --bg-color-operate, --stroke-color-primary)
• ✅ Completely copy official #app style configuration
• ❌ Prohibited from creating custom style class names
• ❌ Prohibited from modifying official style properties

2.2 Component Styles Not Taking Effect

Checklist: 1. Confirm style files have been imported 2. Check import order (TUIKit styles should come before custom styles) 3. Check if CSS Reset is overriding

Correct Import Method:

// main.ts - Import in order following integration documentation
import '@tencentcloud/chat-uikit-vue3/styles/index.css';

2.3 Style Conflicts with Other UI Frameworks

Symptoms: Style disorder when using Element Plus / Ant Design Vue and other frameworks

Solution:

/* Add scope isolation on chat container */
.chat-container {
  box-sizing: border-box;
}

.chat-container * {
  box-sizing: border-box;
}

---

3. chat-only Mode Issues

3.1 Contains Features It Shouldn't Have

Symptoms: Code generated in chat-only mode contains Sidebar, ChatSetting, or in-conversation search features that user didn't request

Cause: Agent didn't correctly judge user requirements and arbitrarily added extended features

Judgment Criteria:

• ✅ Should Add: User explicitly states "need ChatSetting", "want to integrate search", "add settings feature", etc.
• ❌ Should Not Add: User only says "build chat-only chat window" without mentioning extended features

Features Excluded by Default: 1. Sidebar 2. ChatSetting (Chat Settings) 3. Search (In-conversation Search) 4. ConversationList (Conversation List)

Solution: Regenerate code, ensure extended features are not included by default

3.2 Conversation Activation Failed

Symptoms: Empty chat window in chat-only mode

Cause: setActiveConversation not set correctly

Solution: Ensure code contains default conversation activation logic:

import { TUIConversationService } from '@tencentcloud/chat-uikit-engine';

// Activate default conversation after successful login
TUIConversationService.switchConversation('C2Cadministrator');

---

4. Login & Authentication Issues

4.1 Login Timeout

Symptoms:

Error: Login timeout

Troubleshooting Steps: 1. Check network connection 2. Check if SDKAppID is correct 3. Check if UserSig has expired 4. Check firewall/proxy settings

4.2 Invalid UserSig

Common Causes:

• UserSig has expired (default validity is 7 days)
• UserID doesn't match the UserID used when generating UserSig
• SDKAppID mismatch

Solution: Re-call get_usersig MCP tool to generate new credentials.

4.3 Credential Configuration Error

Symptoms: Agent created config.js or .env file

Cause: Violated "Zero External Configuration" rule

Correct Approach:

• ❌ Prohibited from creating config.js, .env and other configuration files
• ✅ Inject SDKAppID, UserID, UserSig directly into code variables

// Correct: Use credentials directly in code
const SDKAppID = 1400000000; // Obtained from get_usersig
const userID = 'user001';
const userSig = 'eJw...'; // Obtained from get_usersig

---

5. Dependency Installation Issues

5.1 Node.js Version Incompatible

Symptoms:

Error: The engine "node" is incompatible with this module

Solution:

# Check Node version
node -v

# Use nvm to switch to compatible version (requires 16+)
nvm install 18
nvm use 18

5.2 Dependency Installation Failed

Symptoms:

npm ERR! peer dep missing: vue@^3.0.0

Solution:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

5.3 TypeScript Type Errors

Symptoms:

Cannot find module '@tencentcloud/chat-uikit-vue3' or its corresponding type declarations

Solution: Add to tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true
  }
}

---

6. Message Sending Issues

6.1 Message Send Failed

Troubleshooting Steps: 1. Confirm successful login 2. Check if target user/group exists 3. Check network connection 4. View console error messages

Common Error Codes:

6.2 Image/File Send Failed

Common Causes:

• File size exceeds limit (images 20MB, files 100MB)
• File format not supported
• Upload service configuration issue

---

7. Project Startup Issues

7.1 Auto-Start Failed

Symptoms: Project didn't start normally after executing npm install && npm run dev

Troubleshooting Steps: 1. Check scripts configuration in package.json 2. Check if port is occupied 3. Check if dependencies are fully installed

Standard Start Command:

cd [project_path] && npm install && npm run dev

7.2 Component Not Registered

Symptoms: Console error showing component is undefined

Solution: Ensure TUIKit is correctly registered in main.ts:

import { createApp } from 'vue';
import App from './App.vue';
import { TUIComponents, TUIChatKit } from '@tencentcloud/chat-uikit-vue3';

const app = createApp(App);
app.use(TUIChatKit);
TUIComponents.forEach(component => {
  app.component(component.name, component);
});
app.mount('#app');

---

8. Debugging Tips

8.1 Enable SDK Logs

import TIM from '@tencentcloud/chat';

// Enable Debug mode
TIM.setLogLevel(0); // 0: Debug, 1: Log, 2: Warn, 3: Error

8.2 Listen to Global Events

import { TUIStore, StoreName } from '@tencentcloud/chat-uikit-engine';

// Listen to conversation list changes
TUIStore.watch(StoreName.CONV, {
  conversationList: (list) => {
    console.log('Conversation list updated:', list);
  }
});

8.3 Network Request Analysis

In browser developer tools Network panel:

• Filter wss:// to view WebSocket connections
• Filter XHR to view HTTP requests
• Check error messages in request responses

---

Related Resources

• Official Documentation: Obtain via MCP tool get_web_chat_uikit_integration
• FAQ Query: Query via MCP tool get_faq
• Component API: Obtain via MCP tool get_web_chat_uikit_component_detail

腾讯云 RTC Skills - AI 智能体技能包

<p align="center"> <a href="./README.md">English</a> | <a href="./README_CN.md">中文</a> </p>

🚀 AI 智能体技能包，用于快速集成腾讯云实时音视频 (RTC) 产品，包括 TUIRoomKit（视频会议）、TUICallKit（音视频通话）、TUILiveKit（直播）和 TUIKit（即时通讯）。只需描述您的需求，AI 助手即可生成可直接运行的代码。

🚀 快速开始

1. 获取凭证 - 登录 腾讯云控制台 获取 SDKAppID 和 SecretKey 2. 配置 MCP Server - 在您的 AI IDE 中配置 MCP（参见 安装步骤） 3. 克隆 Skills 仓库：

   git clone https://github.com/Tencent-RTC/tencent-rtc-skills.git ~/.skills/tencent-rtc-skills

4. 配置 Skills 路径 - 在您的 AI IDE 设置中添加技能路径 5. 开始构建 - 只需描述您想要创建的内容！

📋 目录

• 快速开始
• 概述
• 产品覆盖
• 前置条件
• 安装步骤
• 第一步：安装 MCP Server
• 第二步：安装 Skills
• 使用示例
• 工作原理
• 常见问题
• 许可证

🌟 概述

本仓库提供的 AI 智能体技能包，可以让 AI 助手（如 Claude、Cursor、CodeBuddy）实现：

• 🎯 智能推荐 根据用户需求推荐最合适的腾讯云 RTC 产品
• 📖 实时获取文档 通过 MCP（模型上下文协议）获取最新集成文档
• 🔐 自动生成凭证 基于控制台配置的 SDKAppID 自动生成测试所需的 UserID、UserSig
• 💻 生成生产级代码 基于官方最佳实践生成可直接运行的代码
• ⚡ 自动执行 自动安装依赖并启动项目

🎯 产品覆盖

✅ 前置条件

在安装 Skills 之前，请确保您已具备：

• Node.js >= 18.0.0
• npm >= 9.0.0
• 支持 Skills 和 MCP 的 AI IDE 或智能体（如 CodeBuddy、Cursor、Claude Desktop）
• 已开通 IM/TRTC 服务的腾讯云账号

📦 安装步骤

第一步：安装 MCP Server

Skills 需要配合 腾讯云 RTC MCP Server 使用，用于获取实时文档和生成凭证。

📦 NPM 包地址: @tencentcloud/sdk-mcp

方式 A：使用 npx（推荐）

将以下配置添加到您的 MCP 配置文件中。请将 <您的_SDKAPPID> 和 <您的_SECRETKEY> 替换为您的实际凭证。

配置文件位置：

• Cursor: ~/.cursor/mcp.json（如不存在请创建）
• CodeBuddy: 设置 → MCP 服务器（UI 配置）
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "tencentcloud-sdk-mcp": {
      "command": "npx",
      "args": ["-y", "@tencentcloud/sdk-mcp@latest"],
      "env": {
        "SDKAPPID": "<您的_SDKAPPID>",
        "SECRETKEY": "<您的_SECRETKEY>"
      }
    }
  }
}

注意：更新配置后，请重启您的 AI IDE 以使更改生效。

方式 B：全局安装

npx -y @tencentcloud/sdk-mcp@latest

然后使用全局安装的二进制文件路径进行配置。

获取凭证信息

1. 登录 腾讯云控制台 2. 进入 即时通信 IM 或 实时音视频 TRTC 控制台 3. 创建新应用或选择已有应用 4. 复制 SDKAppID 和 密钥 (SecretKey)

第二步：安装 Skills

方法 A：从 GitHub 克隆（推荐）

# 克隆仓库
git clone https://github.com/Tencent-RTC/tencent-rtc-skills.git

# 或克隆到指定位置
git clone https://github.com/Tencent-RTC/tencent-rtc-skills.git ~/.skills/tencent-rtc-skills

然后在您的 AI IDE 中配置技能路径：

CodeBuddy 配置： 1. 打开设置 → 技能管理 2. 添加克隆的仓库路径（如 ~/.skills/tencent-rtc-skills）作为技能源

Cursor 配置： 1. 打开 Cursor 设置（Cmd/Ctrl + ,） 2. 搜索 "Skills" 或导航到技能部分 3. 将克隆的仓库路径添加到技能配置中

验证：配置完成后，尝试让 AI 助手 "创建一个视频会议应用" - 如果它能识别腾讯云 RTC 产品，则说明配置成功。

方法 B：下载 ZIP 文件

1. 访问 Releases 页面 2. 下载最新版本的 ZIP 文件 3. 解压到您选择的位置 4. 在 AI IDE 中配置解压后的路径

⚙️ 工作原理

当您描述想要构建的内容时，AI 智能体会：

1. 分析您的请求 - 识别关键词，如 "视频会议"、"直播" 等 2. 激活相应技能 - 加载相关的腾讯云 RTC 产品技能（Room、Call、Live 或 Chat） 3. 获取文档 - 使用 MCP 获取最新的集成指南和 API 文档 4. 生成凭证 - 自动从您的 SDKAppID 创建测试用的 UserID 和 UserSig 5. 创建代码 - 根据官方最佳实践生成可直接运行的代码 6. 设置项目 - 安装依赖并准备项目结构

整个过程是自动化的 - 您只需描述需求，智能体会处理其余一切。

💬 使用示例

配置好 Skills 和 MCP 后，只需描述您想要构建的内容：

视频会议

用 Vue3 创建一个支持屏幕共享的视频会议应用

音视频通话

在我的 React 项目中添加 1对1 视频通话功能

直播

实现一个支持主播和观众模式的直播页面

聊天应用

为我现有的项目添加即时通讯功能

❓ 常见问题

MCP Server 连接失败

1. 检查 Node.js 版本：node --version（需要 >= 18.0.0） 2. 验证配置文件语法：确保 JSON 格式正确（无尾随逗号，引号正确） 3. 检查环境变量：确认 SDKAPPID 和 SECRETKEY 设置正确（无多余空格） 4. 重启 IDE：配置更改后务必重启 5. 查看日志：在 IDE 的控制台/日志中查看 MCP 连接错误

Skills 无法加载

1. 验证仓库路径：确保路径存在且可访问 2. 检查文件结构：确认仓库中存在 SKILL.md 文件 3. IDE 兼容性：验证您的 AI IDE 版本支持自定义技能 4. 路径格式：使用绝对路径或 ~ 展开（如 ~/.skills/tencent-rtc-skills）

凭证相关错误

1. 账号状态：确认腾讯云 RTC 账号处于活跃状态且未被暂停 2. 服务激活：确保控制台中已启用 IM/TRTC 服务 3. 凭证匹配：仔细检查 SDKAppID 和 SecretKey 是否完全匹配（区分大小写） 4. 控制台位置：确保从控制台中正确的应用复制凭证

常见问题解答

Q：我没有腾讯云 RTC 账号，该怎么办？ A：在 腾讯云控制台 注册并开通 IM/TRTC 服务。提供免费试用额度。

Q：如何确认 MCP 是否正常工作？ A：尝试让 AI 助手 "为 SDKAppID 123456 生成凭证"。如果返回凭证信息，说明 MCP 已连接。

Q：Skills 已安装但 AI 无法识别腾讯云 RTC 产品。 A：确保技能路径配置正确并重启 IDE。检查仓库中是否包含 SKILL.md 文件。

📄 许可证

本项目采用 MIT 许可证 - 详情请查看 LICENSE 文件。

---

<p align="center"> 由 <a href="https://cloud.tencent.com/document/product/269">Tencent Cloud</a> 提供技术支持 </p>

Tencent RTC Skills for AI Agents

<p align="center"> <a href="./README.md">English</a> | <a href="./README_CN.md">中文</a> </p>

Build video conferencing, live streaming, voice/video calls, and chat applications faster than ever. Just describe what you want, and your AI assistant will generate production-ready code with Tencent RTC products (TUIRoomKit, TUICallKit, TUILiveKit, TUIKit).

🚀 Quick Start

1. Get your credentials from Tencent RTC Console 2. Configure MCP Server in your AI IDE (see Installation) 3. Clone the Skills repository:

   git clone https://github.com/Tencent-RTC/tencent-rtc-skills.git ~/.skills/tencent-rtc-skills

4. Configure Skills path in your AI IDE settings 5. Start building - just describe what you want to create!

📋 Table of Contents

• Quick Start
• Overview
• Product Coverage
• Prerequisites
• Installation
• Step 1: Install MCP Server
• Step 2: Install Skills
• Usage Examples
• How It Works
• Troubleshooting
• License

🌟 Overview

This repository provides AI Agent Skills that enable AI assistants (Claude, Cursor, CodeBuddy, etc.) to:

• 🎯 Recommend the appropriate Tencent RTC product based on your requirements
• 📖 Retrieve up-to-date documentation via MCP (Model Context Protocol)
• 🔐 Generate test credentials (UserID, UserSig) from your SDKAppID
• 💻 Create production-ready code following official best practices
• ⚡ Execute project setup and run commands automatically

🎯 Product Coverage

These Skills support the following Tencent RTC products:

✅ Prerequisites

Before installing, ensure you have:

• Node.js >= 18.0.0
• npm >= 9.0.0
• An AI IDE or agent that supports Skills and MCP (e.g., CodeBuddy, Cursor, Claude Desktop)
• A Tencent account with Chat/TRTC services enabled

📦 Installation

Step 1: Install MCP Server

The Skills require the Tencent RTC MCP Server to retrieve documentation and generate credentials.

📦 NPM Package: @tencent-rtc/mcp

Option A: Using npx (Recommended)

Add the following configuration to your MCP config file. Replace <YOUR_SDKAPPID> and <YOUR_SECRETKEY> with your actual credentials.

Configuration file locations:

• Cursor: ~/.cursor/mcp.json (create if it doesn't exist)
• CodeBuddy: Settings → MCP Servers (UI configuration)
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "tencent-rtc": {
      "command": "npx",
      "args": ["-y", "@tencent-rtc/mcp@latest"],
      "env": {
        "SDKAPPID": "<YOUR_SDKAPPID>",
        "SECRETKEY": "<YOUR_SECRETKEY>"
      }
    }
  }
}

Note: After updating the configuration, restart your AI IDE for changes to take effect.

Option B: Global Installation

npx -y @tencent-rtc/mcp@latest

Then configure your MCP client to use the globally installed binary path.

Obtaining Your Credentials

1. Log in to the Tencent RTC Console 2. Navigate to the Chat or TRTC console 3. Create a new application or select an existing one 4. Copy your SDKAppID and SecretKey

Step 2: Install Skills

Method A: Clone from GitHub (Recommended)

# Clone the repository
git clone https://github.com/Tencent-RTC/tencent-rtc-skills.git

# Or clone to a specific location
git clone https://github.com/Tencent-RTC/tencent-rtc-skills.git ~/.skills/tencent-rtc-skills

Then configure the skill path in your AI IDE:

For CodeBuddy: 1. Open Settings → Skills 2. Add the cloned repository path (e.g., ~/.skills/tencent-rtc-skills) as a skill source

For Cursor: 1. Open Cursor Settings (Cmd/Ctrl + ,) 2. Search for "Skills" or navigate to the Skills section 3. Add the cloned repository path to your skills configuration

Verification: After configuration, try asking your AI assistant to "create a video conference app" - if it recognizes Tencent RTC products, the setup is successful.

Method B: Download ZIP

1. Visit the Releases page 2. Download the latest release ZIP file 3. Extract it to your preferred location 4. Configure the extracted path in your AI IDE

⚙️ How It Works

When you describe what you want to build, the AI agent:

1. Analyzes your request - Identifies keywords like "video conference", "live streaming", etc. 2. Activates the appropriate skill - Loads the relevant Tencent RTC product skill (Room, Call, Live, or Chat) 3. Retrieves documentation - Uses MCP to fetch the latest integration guides and API docs 4. Generates credentials - Automatically creates test UserID and UserSig from your SDKAppID 5. Creates code - Generates production-ready code following official best practices 6. Sets up project - Installs dependencies and prepares the project structure

The entire process is automated - you just describe your requirements and the agent handles the rest.

💬 Usage Examples

Once Skills and MCP are configured, describe what you want to build:

Video Conference

Create a video conference application using Vue3 with screen sharing support

Audio/Video Call

Build a 1-to-1 video call feature for my React app

Live Streaming

Implement a live streaming page with host and audience modes

Chat Application

Add instant messaging functionality to my existing project

❓ Troubleshooting

MCP Server Not Connecting

1. Check Node.js version: node --version (requires >= 18.0.0) 2. Verify configuration file syntax: Ensure JSON is valid (no trailing commas, proper quotes) 3. Check environment variables: Confirm SDKAPPID and SECRETKEY are set correctly (no extra spaces) 4. Restart your IDE: Always restart after configuration changes 5. Check logs: Look for MCP connection errors in your IDE's console/logs

Skills Not Loading

1. Verify repository path: Ensure the path exists and is accessible 2. Check file structure: Confirm SKILL.md files exist in the repository 3. IDE compatibility: Verify your AI IDE version supports custom skills 4. Path format: Use absolute paths or ~ expansion (e.g., ~/.skills/tencent-rtc-skills)

Credential Errors

1. Account status: Verify your Tencent RTC account is active and not suspended 2. Service activation: Ensure Chat/TRTC services are enabled in your console 3. Credential matching: Double-check that SDKAppID and SecretKey match exactly (case-sensitive) 4. Console location: Make sure you're copying credentials from the correct application in the console

Common Issues

Q: I don't have a Tencent RTC account. What should I do? A: Sign up at Tencent RTC Console and activate Chat/TRTC services. Free tier is available for testing.

Q: How do I know if MCP is working? A: Try asking your AI assistant to "generate credentials for SDKAppID 123456". If it responds with credentials, MCP is connected.

Q: Skills are installed but AI doesn't recognize Tencent RTC products. A: Ensure the skill path is correctly configured and restart your IDE. Check that the repository contains SKILL.md files.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

<p align="center"> Powered by <a href="https://trtc.io/products/chat">Tencent RTC</a> </p>

TRTC Web SDK v4 → v5 Migration Reference Guide

This is the authoritative reference for API and event mapping between v4 (trtc-js-sdk) and v5 (trtc-sdk-v5).

Package Change

Architecture Change

Complete API Mapping Table

Complete Event Mapping Table

v5 New Events (No v4 Equivalent)

v5 New Capabilities

Plugin System

import { PluginName } from 'trtc-sdk-v5/plugins/plugin-name';
const trtc = TRTC.create({ plugins: [new PluginName()] });
await trtc.startPlugin('PluginName', options);
await trtc.updatePlugin('PluginName', newOptions);
await trtc.stopPlugin('PluginName');

Available plugins: Beauty, BasicBeauty, VirtualBackground, AIDenoiser, AudioMixer, Watermark, CDNStreaming, CrossRoom, DeviceDetector, VideoMixer, VoiceChanger, FaceDetection, RealtimeTranscriber, Chorus, Debug, etc.

switchRoom

await trtc.switchRoom({ roomId: newRoomId });

sendCustomMessage

await trtc.sendCustomMessage({ cmdId: 1, data: new Uint8Array([1, 2, 3]) });
trtc.on(TRTC.EVENT.CUSTOM_MESSAGE, ({ userId, cmdId, data }) => { });

Critical Behavioral Differences

1. Environment detection API renamed: TRTC.checkSystemRequirements() → TRTC.isSupported(). The return result structure is the same ({ result, detail }), but v5's detail adds isWebCodecsSupported, isScreenShareSupported, isSmallStreamSupported fields. 2. autoReceiveVideo: Since v5.6.0, defaults to false. Must listen to REMOTE_VIDEO_AVAILABLE and call startRemoteVideo() manually. 3. autoReceiveAudio: Defaults to true. Remote audio auto-subscribes and plays. Set autoReceiveAudio: false in enterRoom to control manually. 4. Statistics: No getStatistics() method. All stats via TRTC.EVENT.STATISTICS event (fires every 2s). 5. roomId types: v5 supports both numeric roomId (range: 1~4294967294) and string strRoomId. 6. Autoplay handling: v5 provides AUTOPLAY_FAILED event and enableAutoPlayDialog option in enterRoom. 7. screen share: v5 uses startScreenShare()/stopScreenShare(), no need to create a separate stream. 8. `mode` → `scene`: The mode parameter in v4's createClient() maps to scene in v5's enterRoom(). 9. Role constants: 'anchor'/'audience' strings → TRTC.TYPE.ROLE_ANCHOR/TRTC.TYPE.ROLE_AUDIENCE constants. 10. Audio volume event: The audioVolume field in v4's event callback is renamed to volume in v5.

Common Migration Omissions Checklist

⚠️ These are the most frequently missed items during migration. Always verify each item when migrating code.

1. Publish Omission

v4: client.publish(stream) publishes both video + audio when the stream has both tracks v5: Must call trtc.startLocalVideo() + trtc.startLocalAudio() separately

How to confirm v4 publishes both video + audio:

• Search for TRTC.createStream({ audio: true, video: true }) — dual-track streams published via single publish()
• Search for client.publish(localStream) where localStream has audio: true, video: true
• If v4 code has two separate publish() calls (one for audio stream, one for video stream), v5 migration should also split into two calls

// ❌ Wrong: only migrated audio, video is missing
await trtc.startLocalAudio();

// ✅ Correct: video + audio must both be called
await trtc.startLocalVideo({ view: 'local' });
await trtc.startLocalAudio();

2. Unpublish Omission

v5: stopLocalVideo() + stopLocalAudio() must match the corresponding start calls

3. isSupported Return Value Confusion

Wrong: result.isSupported Correct: checkResult.result (v5 has the same return structure as v4: { result, detail })

// ❌ Wrong
TRTC.isSupported().then((result) => {
  if (!result.isSupported) { ... }
});

// ✅ Correct
TRTC.isSupported().then((checkResult) => {
  if (!checkResult.result) { ... }
});

4. Remote Stream Subscription Omission

v5 (audio): autoReceiveAudio defaults to true, no manual subscription needed

// ✅ Must add remote video listener
trtc.on(TRTC.EVENT.REMOTE_VIDEO_AVAILABLE, ({ userId, streamType }) => {
  trtc.startRemoteVideo({ userId, streamType, view: `remote-${userId}` });
});

5. Remote Stream DOM Readiness (Framework-Agnostic)

In v4, stream-subscribed fires after the stream is ready and the view element exists. In v5, REMOTE_VIDEO_AVAILABLE is only a signal — the view element may not exist yet if your app dynamically renders remote stream containers.

Two issues to check: 1. View element creation: Does REMOTE_USER_ENTER (or REMOTE_VIDEO_AVAILABLE) create the view container element before startRemoteVideo() is called? 2. DOM readiness: Is startRemoteVideo() called after the view element is inserted into the DOM? Use framework-specific microtask/queue flush if the element is rendered asynchronously.

// ❌ Wrong: view element may not exist yet
function handleRemoteVideoAvailable({ userId, streamType }) {
  trtc.startRemoteVideo({ userId, streamType, view: `remote-${userId}` });
}

// ✅ Correct: ensure view exists in DOM before calling startRemoteVideo
// React: use useEffect with empty deps, or flushSync
// Vue: use nextTick()
// Vanilla JS / others: ensure your render pipeline completes first
function handleRemoteVideoAvailable({ userId, streamType }) {
  // 1. Create the view container if not exists
  if (!document.getElementById(`remote-${userId}`)) {
    createViewElement(userId); // your framework's way to render the container
  }
  // 2. Wait for DOM update, then start remote video
  await waitForDOMUpdate(); // framework-specific: nextTick / flushSync / etc.
  trtc.startRemoteVideo({ userId, streamType, view: `remote-${userId}` });
}

Common Migration Patterns

Pattern 1: Basic Video Call

v4:

import TRTC from 'trtc-js-sdk';
const client = TRTC.createClient({ sdkAppId, userId, userSig, mode: 'rtc' });
client.on('stream-added', (e) => client.subscribe(e.stream));
client.on('stream-subscribed', (e) => e.stream.play('remote'));
client.on('stream-removed', (e) => e.stream.stop());
await client.join({ roomId });
const localStream = TRTC.createStream({ userId, audio: true, video: true });
await localStream.initialize();
localStream.play('local');
await client.publish(localStream);

v5:

import TRTC from 'trtc-sdk-v5';
const trtc = TRTC.create();

// 1. Ensure view container exists before calling startRemoteVideo
// (Your framework should create the DOM element for remote-${userId})
trtc.on(TRTC.EVENT.REMOTE_USER_ENTER, ({ userId }) => {
  // Create view container: document.createElement('div') + appendChild
  // Or update your framework's state (React setState / Vue store / etc.)
  addRemoteUser(userId); // your implementation
});

trtc.on(TRTC.EVENT.REMOTE_USER_EXIT, ({ userId }) => {
  removeRemoteUser(userId); // your implementation
});

// 2. Wait for DOM to be ready, then start remote video
// Use: nextTick() in Vue, setTimeout(fn, 0) in React, requestAnimationFrame, etc.
trtc.on(TRTC.EVENT.REMOTE_VIDEO_AVAILABLE, async ({ userId, streamType }) => {
  await waitForDOMReady(); // your framework's DOM flush mechanism
  trtc.startRemoteVideo({ userId, streamType, view: `remote-${userId}` });
});

trtc.on(TRTC.EVENT.REMOTE_VIDEO_UNAVAILABLE, ({ userId, streamType }) => {
  trtc.stopRemoteVideo({ userId, streamType });
});

await trtc.enterRoom({ sdkAppId, userId, userSig, roomId, scene: 'rtc' });
await trtc.startLocalVideo({ view: 'local' });
await trtc.startLocalAudio();

Pattern 2: Screen Share

v4 (v4.15+):

const shareStream = TRTC.createStream({ userId, audio: false, screen: true });
await shareStream.initialize();
await client.publish(shareStream, { isAuxiliary: true });
// stop
await client.unpublish(shareStream);
shareStream.close();

v5:

await trtc.startScreenShare();
trtc.on(TRTC.EVENT.SCREEN_SHARE_STOPPED, () => { /* handle stop */ });
// stop
await trtc.stopScreenShare();

Pattern 3: Statistics

v4:

setInterval(async () => {
  const transport = await client.getTransportStats();
  const localAudio = await client.getLocalAudioStats();
  const localVideo = await client.getLocalVideoStats();
  const remoteAudio = await client.getRemoteAudioStats();
  const remoteVideo = await client.getRemoteVideoStats();
}, 2000);

v5:

trtc.on(TRTC.EVENT.STATISTICS, (event) => {
  const { rtt, upLoss, downLoss, localStatistics, remoteStatistics } = event;
});

Pattern 4: Cleanup

v4:

await client.unpublish(localStream);
localStream.close();
await client.leave();
client.destroy();

v5:

await trtc.stopLocalVideo();
await trtc.stopLocalAudio();
await trtc.exitRoom();
trtc.destroy();