Try Live
Add Docs
Rankings
Pricing
Enterprise
Docs
Install
Theme
Install
Docs
Pricing
Enterprise
More...
More...
Try Live
Rankings
Create API Key
Add Docs
Agora Documentation
https://github.com/agoraio/docs-source
Admin
Agora Documentation is a comprehensive technical documentation platform for Agora's real-time
...
Tokens:
3,225,181
Snippets:
29,336
Trust Score:
9.9
Update:
2 weeks ago
Context
Skills
Chat
Benchmark
94.2
Suggestions
Latest
Show doc for...
Code
Info
Show Results
Context Summary (auto-generated)
Raw
Copy
Link
# Agora Documentation Agora provides a comprehensive suite of real-time communication (RTC) APIs and SDKs that enable developers to add voice, video, messaging, and AI-powered conversational capabilities to their applications. The platform supports multiple products including Video Calling, Voice Calling, Interactive Live Streaming, Broadcast Streaming, Chat, Signaling, Cloud Recording, Real-time Speech-to-Text, and Conversational AI. These services are available across all major platforms including Web, iOS, Android, Windows, macOS, React Native, Flutter, Unity, and Unreal Engine. The Agora ecosystem is built around RESTful APIs for server-side operations and client SDKs for building real-time applications. The platform offers features like ultra-low latency communication, global coverage through the Software-Defined Real-Time Network (SDRTN), AI-powered audio enhancement, content moderation, and seamless integration with third-party services for speech recognition, text-to-speech, and large language models. --- ## Cloud Recording REST API The Cloud Recording REST API enables you to record real-time audio and video streams from Agora channels and store them in third-party cloud storage. It supports individual recording (separate files per user), composite recording (mixed into single file), and web page recording modes. ### Acquire Recording Resource Request a cloud recording resource ID before starting a recording session. The resource ID is valid for 5 minutes. ```bash # Acquire a cloud recording resource curl --location --request POST 'https://api.agora.io/v1/apps/<appid>/cloud_recording/acquire' \ --header 'Authorization: Basic <Base64_encoded_credentials>' \ --header 'Content-Type: application/json' \ --data-raw '{ "cname": "my-channel", "uid": "10001", "clientRequest": {} }' # Response { "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY..." } ``` ### Start Cloud Recording Start recording a channel using the acquired resource ID. Configure recording mode, storage settings, and transcoding options. ```bash # Start composite recording with AWS S3 storage curl --location --request POST 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/mode/composite/start' \ --header 'Authorization: Basic <Base64_encoded_credentials>' \ --header 'Content-Type: application/json' \ --data-raw '{ "cname": "my-channel", "uid": "10001", "clientRequest": { "token": "<rtc_token>", "storageConfig": { "secretKey": "<aws_secret_key>", "vendor": 1, "region": 0, "bucket": "my-recording-bucket", "accessKey": "<aws_access_key>" }, "recordingConfig": { "channelType": 0, "streamTypes": 2, "audioProfile": 1, "videoStreamType": 0, "maxIdleTime": 30, "transcodingConfig": { "width": 640, "height": 480, "fps": 15, "bitrate": 500 } } } }' # Response { "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a", "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY..." } ``` ### Query Recording Status Check the current status of an active recording session to monitor progress and obtain file information. ```bash # Query recording status curl --location --request GET 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/composite/query' \ --header 'Authorization: Basic <Base64_encoded_credentials>' \ --header 'Content-Type: application/json' # Response { "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a", "serverResponse": { "status": 5, "fileList": [{ "filename": "my-channel__uid_s_10001__uid_e_video.mp4", "trackType": "video", "uid": "10001", "mixedAllUser": true, "isPlayable": true }] } } ``` ### Stop Cloud Recording End the recording session and finalize file uploads to cloud storage. ```bash # Stop recording curl --location --request POST 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/composite/stop' \ --header 'Authorization: Basic <Base64_encoded_credentials>' \ --header 'Content-Type: application/json' \ --data-raw '{ "cname": "my-channel", "uid": "10001", "clientRequest": {} }' # Response { "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a", "serverResponse": { "uploadingStatus": "uploaded" } } ``` --- ## Conversational AI Agent REST API The Conversational AI API enables you to create AI-powered voice agents that can have real-time conversations with users. It integrates ASR (Automatic Speech Recognition), LLM (Large Language Models), and TTS (Text-to-Speech) services to create natural voice interactions. ### Start Conversational AI Agent Create and start an AI agent instance that joins an RTC channel and interacts with users via voice. ```bash # Start a conversational AI agent with OpenAI GPT-4o and Microsoft TTS curl --request POST \ --url 'https://api.agora.io/api/conversational-ai-agent/v2/projects/<appid>/join' \ --header 'Authorization: Basic <Base64_encoded_credentials>' \ --header 'Content-Type: application/json' \ --data '{ "name": "support-agent-001", "properties": { "channel": "customer-support-room", "token": "<rtc_token>", "agent_rtc_uid": "1001", "remote_rtc_uids": ["1002"], "idle_timeout": 120, "llm": { "url": "https://api.openai.com/v1/chat/completions", "api_key": "<openai_api_key>", "system_messages": [ { "role": "system", "content": "You are a helpful customer support agent. Be concise and friendly." } ], "max_history": 32, "greeting_message": "Hello! How can I assist you today?", "failure_message": "I apologize, I am having trouble processing that. Please try again.", "params": { "model": "gpt-4o-mini", "temperature": 0.7, "max_tokens": 150 } }, "tts": { "vendor": "microsoft", "params": { "key": "<azure_speech_key>", "region": "eastus", "voice_name": "en-US-JennyNeural", "speed": 1.0 } }, "asr": { "language": "en-US", "vendor": "deepgram", "params": { "model": "nova-2" } }, "turn_detection": { "mode": "default", "config": { "speech_threshold": 0.5, "start_of_speech": { "mode": "vad", "vad_config": { "interrupt_duration_ms": 160, "prefix_padding_ms": 800 } }, "end_of_speech": { "mode": "semantic", "semantic_config": { "silence_duration_ms": 320, "max_wait_ms": 3000 } } } } } }' # Response { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "create_ts": 1737111452, "status": "RUNNING" } ``` ### Query Agent Status Check the current status and configuration of a running AI agent. ```bash # Query agent status curl --request GET \ --url 'https://api.agora.io/api/conversational-ai-agent/v2/projects/<appid>/agents/<agent_id>/query' \ --header 'Authorization: Basic <Base64_encoded_credentials>' # Response { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "status": "RUNNING", "create_ts": 1737111452, "channel": "customer-support-room" } ``` ### Stop Conversational AI Agent Stop an AI agent and remove it from the channel. ```bash # Stop the AI agent curl --request POST \ --url 'https://api.agora.io/api/conversational-ai-agent/v2/projects/<appid>/agents/<agent_id>/leave' \ --header 'Authorization: Basic <Base64_encoded_credentials>' # Response { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "status": "STOPPED" } ``` ### AI Agent with MCP Server Integration Start an AI agent with Model Context Protocol (MCP) server integration for external tool invocation. ```bash # Start agent with MCP tools enabled curl --request POST \ --url 'https://api.agora.io/api/conversational-ai-agent/v2/projects/<appid>/join' \ --header 'Authorization: Basic <Base64_encoded_credentials>' \ --data '{ "name": "mcp-agent", "properties": { "channel": "support-channel", "token": "<rtc_token>", "agent_rtc_uid": "1001", "remote_rtc_uids": ["1002"], "advanced_features": { "enable_tools": true }, "llm": { "url": "https://api.openai.com/v1/chat/completions", "api_key": "<openai_api_key>", "system_messages": [ { "role": "system", "content": "You are a helpful assistant. User name is {{user_name}}." } ], "template_variables": { "user_name": "John" }, "params": {"model": "gpt-4o-mini"}, "mcp_servers": [ { "name": "weather-service", "transport": "streamable_http", "endpoint": "https://api.example.com/mcp", "allowed_tools": ["get_weather", "get_forecast"], "timeout_ms": 5000 } ] }, "tts": { "vendor": "minimax", "params": { "group_id": "<minimax_group_id>", "key": "<minimax_key>", "model": "speech-01-turbo", "voice_setting": {"voice_id": "English_captivating_female1"} } }, "asr": {"language": "en-US"} } }' ``` --- ## Real-time Speech-to-Text REST API (v7.x) The Real-time STT API enables real-time transcription of audio streams in RTC channels. It supports multiple languages, translation, and subtitle recording to cloud storage. ### Start Real-time Transcription Join a channel and start transcribing audio streams with optional translation. ```bash # Start real-time STT with transcription and translation curl --request POST \ --url 'https://api.agora.io/api/speech-to-text/v1/projects/<appid>/join' \ --header 'Authorization: Basic <Base64_encoded_credentials>' \ --header 'Content-Type: application/json' \ --data '{ "languages": ["en-US", "es-ES"], "maxIdleTime": 300, "rtcConfig": { "channelName": "meeting-room-1", "pubBotUid": "10001", "pubBotToken": "<rtc_token>", "subscribeAudioUids": ["2001", "2002", "2003"] }, "translateConfig": { "languages": [ { "source": "en-US", "target": ["es-ES", "fr-FR", "de-DE"] }, { "source": "es-ES", "target": ["en-US"] } ] }, "captionConfig": { "sliceDuration": 60, "storage": { "vendor": 1, "region": 0, "bucket": "my-transcription-bucket", "accesskey": "<aws_access_key>", "secretkey": "<aws_secret_key>", "fileNamePrefix": ["transcripts", "meeting-room-1"] } } }' # Response { "taskId": "abc123def456", "createTs": 1700000000, "status": "RUNNING" } ``` ### Query Transcription Status Check the status of an ongoing transcription task. ```bash # Query transcription status curl --request GET \ --url 'https://api.agora.io/api/speech-to-text/v1/projects/<appid>/tasks/<taskId>/query' \ --header 'Authorization: Basic <Base64_encoded_credentials>' # Response { "taskId": "abc123def456", "status": "RUNNING", "createTs": 1700000000 } ``` ### Stop Real-time Transcription End the transcription task and finalize subtitle file uploads. ```bash # Stop transcription curl --request POST \ --url 'https://api.agora.io/api/speech-to-text/v1/projects/<appid>/tasks/<taskId>/leave' \ --header 'Authorization: Basic <Base64_encoded_credentials>' # Response { "taskId": "abc123def456", "status": "STOPPED" } ``` --- ## Signaling (RTM) REST API The Signaling REST API enables server-side messaging including peer-to-peer messages, channel messages, and user/channel event queries without requiring SDK integration. ### Send Peer-to-Peer Message Send a message from one user to another through the Signaling server. ```bash # Send peer-to-peer message curl -X POST 'https://api.agora.io/dev/v2/project/<appid>/rtm/users/userA/peer_messages?wait_for_ack=true' \ -H 'Content-Type: application/json;charset=utf-8' \ -H 'Authorization: Basic <Base64_encoded_credentials>' \ -d '{ "destination": "userB", "enable_offline_messaging": false, "enable_historical_messaging": true, "payload": "Hello, this is a test message!" }' # Response (message delivered) { "result": "success", "request_id": "123456", "code": "message_delivered" } ``` ### Send Channel Message Broadcast a message to all users subscribed to a channel. ```bash # Send channel message curl -X POST 'https://api.agora.io/dev/v2/project/<appid>/rtm/users/admin/channel_messages' \ -H 'Content-Type: application/json;charset=utf-8' \ -H 'Authorization: Basic <Base64_encoded_credentials>' \ -d '{ "channel_name": "announcements", "enable_historical_messaging": true, "payload": "System maintenance scheduled for tonight at 10 PM UTC." }' # Response { "result": "success", "request_id": "789012", "code": "message_sent" } ``` ### Query User Events Retrieve user online/offline events within a specified time range. ```bash # Query user events curl -X GET 'https://api.agora.io/dev/v2/project/<appid>/rtm/hook/user_events?start_time=2024-01-01T00:00:00&end_time=2024-01-02T00:00:00' \ -H 'Authorization: Basic <Base64_encoded_credentials>' # Response { "result": "success", "events": [ { "user_id": "user123", "event_type": "login", "timestamp": 1704067200000 }, { "user_id": "user123", "event_type": "logout", "timestamp": 1704070800000 } ] } ``` --- ## Chat REST API The Chat REST API enables server-side message management including sending messages, managing users, groups, and chat rooms. ### Send One-to-One Text Message Send a text message from one user to another through the Chat server. ```bash # Send text message to a user curl -X POST 'https://<host>/<org_name>/<app_name>/messages/users' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <app_token>' \ -d '{ "from": "user1", "to": ["user2"], "type": "txt", "body": { "msg": "Hello! How are you doing today?" }, "ext": { "custom_field": "custom_value" } }' # Response { "path": "/messages/users", "uri": "https://XXXX/XXXX/XXXX/messages/users", "timestamp": 1657254052191, "action": "post", "data": { "user2": "1029457500870543736" }, "duration": 12 } ``` ### Send Image Message Send an image message by first uploading the file, then sending the message with the file reference. ```bash # Step 1: Upload image file curl -X POST 'https://<host>/<org_name>/<app_name>/chatfiles' \ -H 'Authorization: Bearer <app_token>' \ -H 'restrict-access: true' \ -F 'file=@/path/to/image.jpg' # Upload Response { "entities": [{ "uuid": "55f12940-XXXX-XXXX-8a5b-ff2336f03252" }], "share-secret": "VfXXXXNb_" } # Step 2: Send image message curl -X POST 'https://<host>/<org_name>/<app_name>/messages/users' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <app_token>' \ -d '{ "from": "user1", "to": ["user2"], "type": "img", "body": { "filename": "photo.jpg", "secret": "VfXXXXNb_", "url": "https://<host>/<org_name>/<app_name>/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252", "size": { "width": 480, "height": 720 } } }' ``` ### Send Group Message Send a message to all members of a chat group. ```bash # Send message to a group curl -X POST 'https://<host>/<org_name>/<app_name>/messages/chatgroups' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <app_token>' \ -d '{ "from": "admin", "to": ["group_id_123"], "type": "txt", "body": { "msg": "Important announcement for all group members!" } }' # Response { "data": { "group_id_123": "1029457500870543999" } } ``` --- ## Video SDK (Web) The Agora Video SDK for Web enables real-time video and voice communication in browser applications. It provides APIs for joining channels, publishing local media, and subscribing to remote streams. ### Initialize and Join Channel Create an RTC client, join a channel, and set up media publishing. ```javascript import AgoraRTC from "agora-rtc-sdk-ng"; // Configuration const appId = "<your_app_id>"; const channel = "test-channel"; const token = "<rtc_token>"; const uid = 0; // 0 means auto-assign // Initialize client const client = AgoraRTC.createClient({ mode: "rtc", // "rtc" for video calling, "live" for live streaming codec: "vp8" // "vp8" or "h264" }); // Local tracks let localAudioTrack = null; let localVideoTrack = null; // Set up event listeners before joining client.on("user-published", async (user, mediaType) => { await client.subscribe(user, mediaType); console.log("Subscribed to user:", user.uid); if (mediaType === "video") { const remoteContainer = document.createElement("div"); remoteContainer.id = `remote-${user.uid}`; remoteContainer.style.width = "640px"; remoteContainer.style.height = "480px"; document.getElementById("remote-players").append(remoteContainer); user.videoTrack.play(remoteContainer); } if (mediaType === "audio") { user.audioTrack.play(); } }); client.on("user-unpublished", (user, mediaType) => { if (mediaType === "video") { const container = document.getElementById(`remote-${user.uid}`); container?.remove(); } }); // Join channel and publish local media async function joinChannel() { try { await client.join(appId, channel, token, uid); console.log("Joined channel successfully"); // Create local tracks localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack(); localVideoTrack = await AgoraRTC.createCameraVideoTrack({ encoderConfig: "720p_2" // Video quality preset }); // Display local video const localContainer = document.getElementById("local-player"); localVideoTrack.play(localContainer); // Publish tracks to the channel await client.publish([localAudioTrack, localVideoTrack]); console.log("Published local tracks"); } catch (error) { console.error("Error joining channel:", error); } } // Leave channel and clean up async function leaveChannel() { if (localAudioTrack) { localAudioTrack.close(); localAudioTrack = null; } if (localVideoTrack) { localVideoTrack.close(); localVideoTrack = null; } await client.leave(); console.log("Left the channel"); } // Start the application joinChannel(); ``` ### Live Streaming with Host and Audience Roles Configure the client for live streaming with role-based permissions. ```javascript import AgoraRTC from "agora-rtc-sdk-ng"; const appId = "<your_app_id>"; const channel = "live-stream"; const token = "<rtc_token>"; // Create client for live streaming mode const client = AgoraRTC.createClient({ mode: "live", codec: "vp8", role: "host" // Initial role }); let localAudioTrack = null; let localVideoTrack = null; // Join as host (can publish and subscribe) async function joinAsHost() { await client.join(appId, channel, token, 0); client.setClientRole("host"); // Create and publish media tracks localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack(); localVideoTrack = await AgoraRTC.createCameraVideoTrack(); localVideoTrack.play("local-player"); await client.publish([localAudioTrack, localVideoTrack]); console.log("Joined as host and publishing"); } // Join as audience (can only subscribe) async function joinAsAudience() { await client.join(appId, channel, token, 0); // Set ultra-low latency for interactive live streaming const clientRoleOptions = { level: 2 }; client.setClientRole("audience", clientRoleOptions); console.log("Joined as audience"); } // Switch role from audience to host async function switchToHost() { client.setClientRole("host"); localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack(); localVideoTrack = await AgoraRTC.createCameraVideoTrack(); await client.publish([localAudioTrack, localVideoTrack]); console.log("Switched to host role"); } // Switch role from host to audience async function switchToAudience() { if (localAudioTrack) localAudioTrack.close(); if (localVideoTrack) localVideoTrack.close(); await client.unpublish(); client.setClientRole("audience", { level: 2 }); console.log("Switched to audience role"); } ``` ### Screen Sharing Enable screen sharing alongside camera video. ```javascript import AgoraRTC from "agora-rtc-sdk-ng"; let screenTrack = null; // Start screen sharing async function startScreenShare() { try { screenTrack = await AgoraRTC.createScreenVideoTrack({ encoderConfig: "1080p_1", optimizationMode: "detail" // For text/documents }, "auto"); // "auto" creates audio track if system audio is available // Handle array return when audio track is included if (Array.isArray(screenTrack)) { const [videoTrack, audioTrack] = screenTrack; await client.publish([videoTrack, audioTrack]); videoTrack.play("screen-player"); } else { await client.publish(screenTrack); screenTrack.play("screen-player"); } // Handle user stopping screen share via browser UI screenTrack.on("track-ended", () => { console.log("Screen sharing stopped by user"); stopScreenShare(); }); } catch (error) { console.error("Screen share error:", error); } } // Stop screen sharing async function stopScreenShare() { if (screenTrack) { if (Array.isArray(screenTrack)) { screenTrack.forEach(track => track.close()); } else { screenTrack.close(); } await client.unpublish(screenTrack); screenTrack = null; } } ``` --- ## Token Authentication Agora uses tokens for secure channel authentication. Generate tokens on your server using the App Certificate. ### Generate RTC Token (Node.js) ```javascript const { RtcTokenBuilder, RtcRole } = require('agora-access-token'); const appId = "<your_app_id>"; const appCertificate = "<your_app_certificate>"; const channelName = "test-channel"; const uid = 0; // 0 for auto-assign, or specific user ID const role = RtcRole.PUBLISHER; // PUBLISHER or SUBSCRIBER const tokenExpirationInSeconds = 3600; const privilegeExpirationInSeconds = 3600; // Generate token const token = RtcTokenBuilder.buildTokenWithUid( appId, appCertificate, channelName, uid, role, tokenExpirationInSeconds, privilegeExpirationInSeconds ); console.log("Generated RTC Token:", token); // Express.js endpoint example app.get('/rtc-token', (req, res) => { const { channelName, uid, role } = req.query; const token = RtcTokenBuilder.buildTokenWithUid( appId, appCertificate, channelName, parseInt(uid) || 0, role === 'publisher' ? RtcRole.PUBLISHER : RtcRole.SUBSCRIBER, 3600, 3600 ); res.json({ token }); }); ``` ### Generate Chat Token (Node.js) ```javascript const { ChatTokenBuilder } = require('agora-token'); const appId = "<your_app_id>"; const appCertificate = "<your_app_certificate>"; const userId = "user123"; const tokenExpirationInSeconds = 86400; // Generate user token for Chat const userToken = ChatTokenBuilder.buildUserToken( appId, appCertificate, userId, tokenExpirationInSeconds ); console.log("Generated Chat User Token:", userToken); // Generate app token for server-side API calls const appToken = ChatTokenBuilder.buildAppToken( appId, appCertificate, tokenExpirationInSeconds ); console.log("Generated Chat App Token:", appToken); ``` --- ## Summary Agora's real-time communication platform provides developers with comprehensive APIs and SDKs for building voice, video, messaging, and AI-powered applications. The main use cases include video conferencing and calling applications, live streaming platforms with host/audience roles, in-app messaging and chat features, AI-powered voice assistants and customer support bots, real-time transcription and translation services, and cloud recording for compliance and content archiving. The platform's global infrastructure ensures low-latency communication across 200+ countries with automatic network optimization. Integration typically follows a pattern of server-side token generation for authentication, client SDK initialization with appropriate mode (RTC for calling, live for streaming), channel joining with proper role configuration, media track creation and publishing, event-driven subscription to remote users, and optional server-side features like recording, transcription, or AI agents via REST APIs. The modular architecture allows developers to combine multiple services - for example, using Video SDK for real-time communication, Cloud Recording for archival, Real-time STT for accessibility, and Conversational AI for automated support - all within the same channel infrastructure.