UI Kit quickstart

Instant messaging connects people wherever they are and allows them to communicate with others in real time. Agora offers an open-source Chat UI Kit project on GitHub. With built-in user interfaces for key Chat features, the Agora Chat UI Kit enables you to quickly embed real-time messaging into your app without requiring extra effort on the UI.

info

For the latest Agora Chat UIKit documentation, refer to the UIKit 2.x Documentation GitHub repository.

Legacy UIkit 1.x documentation

This page shows sample code to add peer-to-peer messaging into your app by using the Agora Chat UI Kit.

The following figure shows the workflow of how clients send and receive peer-to-peer messages:

Chat UI kit workflow

1. Clients retrieve a token from your app server.
2. Client A and Client B log in to Agora Chat.
3. Client A sends a message to Client B. The message is sent to the Agora Chat server, and the server delivers the message to Client B. When Client B receives the message, the SDK triggers an event. Client B listens for the event and gets the message.

• React 16.8.0 or later.
• React DOM 16.8.0 or later.
• A Windows or macOS computer that has a browser supported by the Agora Chat SDK:
  • Internet Explorer 11 or later
  • Firefox 10 or later
  • Chrome 54 or later
  • Safari 11 or later
• A valid Agora Account.
• An Agora project that has enabled the Chat service.
• An App key and a user token generated on your app server.

This sections introduces how to create an app and add the Chat UI Samples to the project.

1. In your terminal, run the following command to create an app:

   # Install CLI
   

   npm install create-react-app
   

   # Create an app named my-app
   

   npx create-react-app my-app
   

   cd my-app
   

   Once you successfully create the app, the project structure is as follows:

   my-app
   

   ├── package.json
   

   ├── public # The static directory for Webpack
   

   │ ├── favicon.ico
   

   │ ├── index.html # The default one-page app
   

   │ └── manifest.json
   

   ├── src
   

   │ ├── App.css # The css file of the app
   

   │ ├── App.js # The code of the app
   

   │ ├── App.test.js
   

   │ ├── index.css # The layout when launching the file
   

   │ ├── index.js # Launch the file
   

   │ ├── logo.svg
   

   │ └── serviceWorker.js
   

   └── yarn.lock
   

2. Run one of the following commands to add the Chat UI Samples to your project.

   To add the UI Samples using npm:

   npm install agora-chat-uikit --save
   

   To add the UI Samples using yarn

   yarn add agora-chat-uikit
   

The Web Chat UIKit contains the EaseApp component, which contains the conversation list and applies to use cases where you want to quickly launch a real-time chat app.

This section introduces the steps you need to take to quickly implement one-to-one messaging with EaseApp.

1. Import EaseApp.

   Open my-app/src/App.js, and replace the code with the following:

   // App.js
   

   import React, {Component} from 'react';
   

   import { EaseApp } from "agora-chat-uikit"
   

   import './App.css';
   

   
   

   class App extends Component {
   

   render() {
   

   return (
   

   <div className="container">
   

   <EaseApp
   

   // The App key for your chat project
   

   appkey= "xxx"
   

   // The user ID of the current user
   

   username= "xxx"
   

   // The <Vg k="COMPANY" /> token
   

   agoraToken= "xxx"
   

   />
   

   </div>
   

   );
   

   }
   

   }
   

   
   

   export default App;
   

2. Set the layout for the conversation.

   Open my-app/src/App.css, and replace the content with the following:

   /** App.css */
   

   .container {
   

   height: 100%;
   

   width: 100%
   

   }
   

In your terminal, run the following command to launch the app:

npm run start

You can see the app launch in your browser. Before you can send a message, refer to Add a contact or Join a chat group to add a contact or join a chat group.

This section includes more advanced features you can implement in your project.

EaseChat provides the following attributes for customization. You can customize the features and layout by setting these attributes. To ensure the functionality of EaseChat, ensure that you set all the required parameters.

Attribute	Type	Required	Description
appkey	String	Yes	The unique identifier that the Chat service assigns to each app. The rule is $(OrgName)#{AppName}.
username	String	Yes	The user ID.
agoraToken	String	Yes	The Agora token.
to	String	Yes	In one-to-one messaging, it is the user ID of the recipient; in group chat, it is the group ID.
showByselfAvatar	Boolean	No	Whether to display the avatar of the current user. true: Yes (Default) false: No
easeInputMenu	String	No	The mode of the input menu. (Default) all: The complete mode. noAudio: No audio. noEmoji: No emoji. noAudioAndEmoji: No audio or emoji. onlyText: Only text.
menuList	Array	No	The extensions of the input box on the right panel. (Default) menuList: [ {name:'Send a pic', value:'img'},{name:'Send a file', value:'file'}]
handleMenuItem	function({item, key})	No	The callback event triggered by clicking on the right panel of the input box.
successLoginCallback	function(res)	No	The callback event for a successful login.
failCallback	function(err)	No	The callback event for a failed method call.

In use-cases where you want to add your own business logic, you can use the various callback events provided by the Chat UI Samples, as shown in the following steps:

1. Get the SDK instance

   const WebIM = EaseApp.getSdk({ appkey: 'xxxx' })
   

2. Add callback events

   Call addEventHandler to add the callback events.

   // Use nameSpace to differentiate the different business logics. You can add multiple callback events according to your needs.。
   

   WebIM.conn.addEventHandler('nameSpace'),{
   

   onOpend:()=>{},
   

   onTextMessage:()=>{},
   

   .... })
   

   Refer to EventHandlerType for the complete list of callback events you can add.

Agora Chat provides an open-source AgoraChat sample project on GitHub that has integrated the UI Samples. You can download the project to try it out or view the source code.