Real-time chatting immerses people in the sounds of human connections, keeping them engaged in your app longer. The Agora Voice SDK provides crystal-clear voice chat for your web, mobile and native apps.
This page shows the minimum code you need to integrate crystal-clear voice chat functionality into your app using the Voice SDK for Web.
The following figure shows the workflow of a voice call implemented by the Agora SDK.
As shown in the figure, the workflow for adding Voice Call in your project is as follows:
Retrieve a token
A token is the credential that authenticates a user when your app client joins a channel. In a test or production environment, your app client retrieves tokens from a server in your security infrastructure.
Join a channel
Call joinChannel
to create and join a channel. App clients that pass the same channel name join the same channel.
Publish and subscribe to audio in the channel
You can use the LocalTrack
and RemoteTrack
objects to publish and subscirbe to audio tracks in the channel.
For an app client to join an RTC channel, you need the following information:
In order to follow the procedure in this page, you must have:
Create a new directory named agora_web_quickstart
. For a minimal Web app client, create the following files in the directory :
index.html
: The visual interface with the user.basicVoiceCall.js
: The programmable interface with AgoraRTCClient
to implement the client logic.package.json
: Install and manage the dependencies of your project. To create the package.json
file, you can navigate to the agora_web_quickstart
directory on the command line and run npm init
.The following section shows how to use the Agora Voice SDK for Web to add Voice Call into your Web app step by step.
Integrate the Agora Web SDK into your project through npm, as follows:
In package.json
, add agora-rtc-sdk-ng
and its version number to the dependencies
field:
{
"name": "agora_web_quickstart",
"version": "1.0.0",
"description": "",
"main": "basicVoiceCall.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"dependencies": {
"agora-rtc-sdk-ng": "latest"
},
"author": "",
"license": "ISC"
}
To import the AgoraRTC
module in your project, copy the following code into basicVoiceCall.js
.
import AgoraRTC from "agora-rtc-sdk-ng"
To implement the user interface, copy the following code into index.html
:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Agora Voice Web SDK Quickstart</title>
<!--
This line is used to refer to the bundle.js file packaged by webpack. A sample webpack configuration is shown in the later step of running your app.
-->
<script src="./dist/bundle.js"></script>
</head>
<body>
<h2 class="left-align">Agora Voice Web SDK Quickstart</h2>
<div class="row">
<div>
<button type="button" id="join">JOIN</button>
<button type="button" id="leave">LEAVE</button>
</div>
</div>
</body>
</html>
The client logic you implement in order to add Voice Call to your app is:
createClient
to create an AgoraRTCClient
object.join
to join an RTC channel with the App ID, user ID, token, and channel name. createMicrophoneAudioTrack
to create a local audio track from the audio sampled by a microphone, and then call publish
to publish the local audio tracks in the channel.client.on("user-published")
event. When the SDK triggers this event, get an AgoraRTCRemoteUser
object from this event.subscribe
to subscribe to the AgoraRTCRemoteUser
object and get the RemoteAudioTrack
objects of the remote user.play
to play the remote audio tracks.The following figure shows the API call sequence of a basic one-to-one Voice Call.
To implement this logic, do the following:
basicVoiceCall.js
.Your App ID
and Your temp token
with values from your Agora project.let rtc = {
localAudioTrack: null,
client: null
};
let options = {
// Pass your App ID here.
appId: "Your App ID",
// Set the channel name.
channel: "test",
// Pass your temp token here.
token: "Your temp token",
// Set the user ID.
uid: 123456
};
async function startBasicCall() {
// Create an AgoraRTCClient object.
rtc.client = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });
// Listen for the "user-published" event, from which you can get an AgoraRTCRemoteUser object.
rtc.client.on("user-published", async (user, mediaType) => {
// Subscribe to the remote user when the SDK triggers the "user-published" event
await rtc.client.subscribe(user, mediaType);
console.log("subscribe success");
// If the remote user publishes an audio track.
if (mediaType === "audio") {
// Get the RemoteAudioTrack object in the AgoraRTCRemoteUser object.
const remoteAudioTrack = user.audioTrack;
// Play the remote audio track.
remoteAudioTrack.play();
}
// Listen for the "user-unpublished" event
rtc.client.on("user-unpublished", async (user) => {
// Unsubscribe from the tracks of the remote user.
await rtc.client.unsubscribe(user);
});
});
window.onload = function () {
document.getElementById("join").onclick = async function () {
// Join an RTC channel.
await rtc.client.join(options.appId, options.channel, options.token, options.uid);
// Create a local audio track from the audio sampled by a microphone.
rtc.localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack();
// Publish the local audio tracks to the RTC channel.
await rtc.client.publish([rtc.localAudioTrack]);
console.log("publish success!");
}
document.getElementById("leave").onclick = async function () {
// Destroy the local audio track.
rtc.localAudioTrack.close();
// Leave the channel.
await rtc.client.leave();
}
}
}
startBasicCall()
This quickstart uses webpack to package the project and webpack-dev-server
to run your project.
In package.json
, add webpack
, webpack-cli
, and webpack-dev-server
to the dependencies
field, and the build
and start:dev
commands to the scripts
field.
{
"name": "agora_web_quickstart",
"version": "1.0.0",
"description": "",
"main": "basicVoiceCall.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"build": "webpack --config webpack.config.js",
"start:dev": "webpack serve --open --config webpack.config.js"
},
"dependencies": {
"agora-rtc-sdk-ng": "latest",
"webpack": "5.28.0",
"webpack-dev-server": "3.11.2",
"webpack-cli": "4.10.0"
},
"author": "",
"license": "ISC"
}
Create a file named webpack.config.js
in the project directory to configure webpack, with the following code:
const path = require("path");
module.exports = {
entry: "./basicVoiceCall.js",
output: {
filename: "bundle.js",
path: path.resolve(__dirname, "./dist"),
},
devServer: {
compress: true,
port: 9000,
},
};
To install dependencies, run the following command:
npm install
To build and run the project using webpack, run the following command:
# Use webpack to package the project
npm run build
Use webpack-dev-server to run the project:
npm run start:dev
A local web server automatically opens in your browser. You see the following page:
Click JOIN to start a voice call. However, being in a call on your own is no fun. Ask a friend to join the same voice call with you on the demo app.
Generating a token by hand is not helpful in a production context. Authenticate Your Users with Tokens shows you how to start a video call with a token that you retrieve from your server.
Agora also provides an open-source sample project on GitHub for your reference.
In addition to integrating the Agora Web SDK into your project through npm, you can also choose either of the following methods to integrate the Agora Web SDK into your project:
Through the CDN: Add the following code to the line before <style>
in the index.html
file of your project.
<script src="https://download.agora.io/sdk/release/AgoraRTC_N-4.14.2.js"></script>
Manually download the latest Agora Web SDK 4.x, copy the .js
file to the directory of your project files, and add the following code to the line before the <style>
tag in your project.
<script src="./AgoraRTC_N-4.14.2.js"></script>
AgoraRTC
object. You can visit the AgoraRTC
object to operate the Web SDK.