Enable services

Agora's ConvoAI Device Kit R1 is based on Agora's IoT SDK and Conversational AI Engine.

This page shows you how to sign up for an Agora account, create a new project, and get the app ID and app certificate to generate a temporary token.

To join a ConvoAI Device Kit R1 session, you need an Agora App ID. This section shows you how to set up an Agora account, create an Agora project and get the required information from Agora Console.

To use Agora products and services, create an Agora account with your email, phone number, or a third-party account.

Sign up with email

1. Go to the signup page.

2. Fill in the required fields.

3. Carefully read the Terms of Service, Privacy Policy, and Acceptable Use Policy, and tick the checkbox.

4. Click Continue.

5. Enter your verification code and click Confirm.

6. Follow the on-screen instructions to provide your name, company name, and phone number, set a password, and click Continue.

Sign up with a third-party account

1. On the Agora Console login page, select the third-party account you want to use.

2. Follow the on-screen instructions to complete verification.

3. Click Create a new account.

4. Carefully read the Terms of Service, Privacy Policy, and Acceptable Use Policy, and select the checkbox.

5. Click Continue.

Once you sign up successfully, your account is automatically logged in. Follow the on-screen instructions to create your first project and test out real-time communications.

For later visits, log in to Agora Console with your phone number, email address, or linked third-party account.

To create an Agora project, do the following:

1. In Agora Console, open the Projects page.

2. Click Create New.

3. Follow the on-screen instructions to enter a project name and use case, and check Secured mode: APP ID + Token (Recommended) as the authentication mechanism.

   

4. Click Submit. You see the new project on the Projects page.

Agora automatically assigns a unique identifier to each project, called an App ID.

To copy this App ID, find your project on the Projects page in Agora Console, and click the copy icon in the App ID column.

Use the following features from your Agora account to implement security and authentication features in your apps.

When generating an authentication token on your app server, you need an App Certificate, in addition to the App ID.

To get an App Certificate, do the following:

1. On the Projects page, click the pencil icon to edit the project you want to use.

   

2. Click the copy icon under Primary Certificate.

   

To ensure communication security, best practice is to use tokens to authenticate the users who log in from your app.

To generate a temporary RTC token for use in your Video SDK projects:

1. On the Projects page, click the pencil icon next to your project.

2. On the Security panel, click Generate Temp Token, enter a channel name in the pop-up box and click Generate. Copy the generated RTC token for use in your ConvoAI Device Kit R1 projects.

To generate a token for other Agora products:

1. In your browser, navigate to the Agora token builder.

2. Choose the Agora product your user wants to log in to. Fill in App ID and App Certificate with the details of your project in Agora Console.

3. Customize the token for each user. The required fields are visible in the Agora token builder.

4. Click Generate Token.

   The token appears in Token Builder.

5. Copy the token and use it in your app.

For more information on managing other aspects of your Agora account, see Agora console overview.

Before using ConvoAI Device Kit R1, enable it for your app ID in Agora Console.

Note

The following steps apply to the new version of Agora Console. If you are using the old version, switch to the new version by clicking Switch to the new version at the top of the screen.

1. Navigate to the Projects page, locate your project in the My Projects list and click the associated ✏️ icon to configure it.

   

2. Under All features select Conversational AI > Configurations and toggle the switch to Enable Conversational AI.

   

After enabling, you can call the ConvoAI Device Kit R1 RESTful API.

Before using ConvoAI Device Kit R1 RESTful API, set up REST authentication. The following REST authentication methods are available:

• Basic HTTP authentication

  Generate a Base64-encoded credential with the customer ID and customer secret provided by Agora and pass the credential with the Authorization parameter in the request header.

info

Implement authentication on the server to mitigate the risk of data leakage.

To generate a set of customer ID and customer secret, do the following:

1. In Agora Console, click Developer Toolkit > RESTful API.

   

2. Click Add a secret, and click OK. A set of customer ID and customer secret is generated.

3. Click Download in the Customer Secret column. Read the pop-up window carefully, and save the downloaded key_and_secret.txt file in a secure location.

4. Use the customer ID (key) and customer secret (secret) to generate a Base64-encoded credential, and pass the Base64-encoded credential to the Authorization parameter in the HTTP request header.

You can download the customer secret from Agora Console only once. Be sure to keep it secure.

For testing and debugging, you can use a third-party online tool to quickly generate your Authorization header. Enter your Customer ID as the Username and your Customer Secret as the Password. Your generated header should look like this::

_1

Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=a

The following sample code implements basic HTTP authentication and sends a RESTful API request to get the basic information of all your current Agora projects.

caution

The Agora RESTful API only supports HTTPS with TLS 1.0, 1.1, or 1.2 for encrypted communication. Requests over plain HTTP are not supported and will fail to connect.

Golang

package mainimport (  "fmt"  "strings"  "net/http"  "io/ioutil"  "encoding/base64")// HTTPS basic authentication example in Golang using the <Vg k="VSDK" /> Server RESTful APIfunc main() {  // Customer ID  customerKey := "Your customer ID"  // Customer secret  customerSecret := "Your customer secret"  // Concatenate customer key and customer secret and use base64 to encode the concatenated string  plainCredentials := customerKey + ":" + customerSecret  base64Credentials := base64.StdEncoding.EncodeToString([]byte(plainCredentials))  url := "https://api.agora.io/dev/v2/projects"  method := "GET"  payload := strings.NewReader(``)  client := &http.Client {  }  req, err := http.NewRequest(method, url, payload)  if err != nil {    fmt.Println(err)    return  }  // Add Authorization header  req.Header.Add("Authorization", "Basic " + base64Credentials)  req.Header.Add("Content-Type", "application/json")  // Send HTTP request  res, err := client.Do(req)  if err != nil {    fmt.Println(err)    return  }  defer res.Body.Close()  body, err := ioutil.ReadAll(res.Body)  if err != nil {    fmt.Println(err)    return  }  fmt.Println(string(body))}

Node.js

// HTTP basic authentication example in node.js using the <Vg k="VSDK" /> Server RESTful APIconst https = require('https')// Customer IDconst customerKey = "Your customer ID"// Customer secretconst customerSecret = "Your customer secret"// Concatenate customer key and customer secret and use base64 to encode the concatenated stringconst plainCredential = customerKey + ":" + customerSecret// Encode with base64encodedCredential = Buffer.from(plainCredential).toString('base64')authorizationField = "Basic " + encodedCredential// Set request parametersconst options = {  hostname: 'api.agora.io',  port: 443,  path: '/dev/v2/projects',  method: 'GET',  headers: {    'Authorization':authorizationField,    'Content-Type': 'application/json'  }}// Create request object and send requestconst req = https.request(options, res => {  console.log(`Status code: ${res.statusCode}`)  res.on('data', d => {    process.stdout.write(d)  })})req.on('error', error => {  console.error(error)})req.end()

PHP

<?php// HTTP basic authentication example in PHP using the Agora Server RESTful API// Customer ID and secret$customerKey = "Your customer ID";   // Replace with your actual customer ID$customerSecret = "Your customer secret"; // Replace with your actual customer secret// Concatenate customer key and customer secret$credentials = $customerKey . ":" . $customerSecret;// Encode with base64$base64Credentials = base64_encode($credentials);// Create authorization header$authHeader = "Authorization: Basic " . $base64Credentials;// Initialize cURL$curl = curl_init();// Set cURL optionscurl_setopt_array($curl, [    CURLOPT_URL => 'https://api.agora.io/dev/v2/projects',    CURLOPT_RETURNTRANSFER => true,    CURLOPT_ENCODING => '',    CURLOPT_MAXREDIRS => 10,    CURLOPT_TIMEOUT => 0,    CURLOPT_FOLLOWLOCATION => true,    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,    CURLOPT_CUSTOMREQUEST => 'GET',    CURLOPT_HTTPHEADER => [        $authHeader,        'Content-Type: application/json',    ],]);// Execute cURL request$response = curl_exec($curl);// Check for cURL errorsif ($response === false) {    echo "Error in cURL: " . curl_error($curl);} else {    // Output the response    echo $response;}// Close cURL sessioncurl_close($curl);?>

Python

# -- coding utf-8 --# Python 3# HTTP basic authentication example in python using the <Vg k="VSDK" /> Server RESTful APIimport base64import http.client# Customer IDcustomer_key = "Your customer ID"# Customer secretcustomer_secret = "Your customer secret"# Concatenate customer key and customer secret and use base64 to encode the concatenated stringcredentials = customer_key + ":" + customer_secret# Encode with base64base64_credentials = base64.b64encode(credentials.encode("utf8"))credential = base64_credentials.decode("utf8")# Create connection object with basic URLconn = http.client.HTTPSConnection("api.agora.io")payload = ""# Create Header objectheaders = {}# Add Authorization fieldheaders['Authorization'] = 'basic ' + credentialheaders['Content-Type'] = 'application/json'# Send requestconn.request("GET", "/dev/v2/projects", payload, headers)res = conn.getresponse()data = res.read()print(data.decode("utf-8"))

Java

import java.io.IOException;import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.util.Base64;// HTTP basic authentication example in Java using the <Vg k="VSDK" /> Server RESTful APIpublic class Base64Encoding {    public static void main(String[] args) throws IOException, InterruptedException {        // Customer ID        final String customerKey = "Your customer ID";        // Customer secret        final String customerSecret = "Your customer secret";        // Concatenate customer key and customer secret and use base64 to encode the concatenated string        String plainCredentials = customerKey + ":" + customerSecret;        String base64Credentials = new String(Base64.getEncoder().encode(plainCredentials.getBytes()));        // Create authorization header        String authorizationHeader = "Basic " + base64Credentials;        HttpClient client = HttpClient.newHttpClient();        // Create HTTP request object        HttpRequest request = HttpRequest.newBuilder()                .uri(URI.create("https://api.agora.io/dev/v2/projects"))                .GET()                .header("Authorization", authorizationHeader)                .header("Content-Type", "application/json")                .build();        // Send HTTP request        HttpResponse<String> response = client.send(request,                HttpResponse.BodyHandlers.ofString());        System.out.println(response.body());    }}

C#

using System;using System.IO;using System.Net;using System.Text;// HTTP basic authentication example in C# using the <Vg k="VSDK" /> Server RESTful APInamespace Examples.System.Net{    public class WebRequestPostExample    {        public static void Main()        {            // Customer ID            string customerKey = "Your customer ID";            // Customer secret            string customerSecret = "Your customer secret";            // Concatenate customer key and customer secret and use base64 to encode the concatenated string            string plainCredential = customerKey + ":" + customerSecret;            // Encode with base64            var plainTextBytes = Encoding.UTF8.GetBytes(plainCredential);            string encodedCredential = Convert.ToBase64String(plainTextBytes);            // Create authorization header            string authorizationHeader = "Authorization: Basic " + encodedCredential;            // Create request object            WebRequest request = WebRequest.Create("https://api.agora.io/dev/v2/projects");            request.Method = "GET";            // Add authorization header            request.Headers.Add(authorizationHeader);            request.ContentType = "application/json";            WebResponse response = request.GetResponse();            Console.WriteLine(((HttpWebResponse)response).StatusDescription);            using (Stream dataStream = response.GetResponseStream())            {                StreamReader reader = new StreamReader(dataStream);                string responseFromServer = reader.ReadToEnd();                Console.WriteLine(responseFromServer);            }            response.Close();        }    }}