App State Library

Turnkey

Embed-SDK React

Embed-SDK Web

Provides accessors for various app states used in App Builder. Some accessors accept a selector method that allows for selective subscribing of data.

turnkey

You can access them under the customization-api module as a named export.

react-sdk

You can access them under the @appbuilder/react module as a named export.

web-sdk

You can access them under the @appbuilder/web module as a named export.

---

useRecording(selector?: Selector): RecordingContextInterface

The Recording app state governs the App Builder cloud recording functionality.

RecordingContextInterface

Key	Type	Description
isRecordingActive	boolean	Indicates if cloud recording is active in the application
startRecording	() => void	Starts cloud recording
stopRecording	() => void	Stops cloud recording

Usage example of the app state:

turnkey

import { useRecording } from "customization-api";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

react-sdk

import { useRecording } from "@appbuilder/react";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

web-sdk

import { useRecording } from "@appbuilder/web";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

---

---

useScreenshare(selector?: Selector): ScreenshareContextInterface

The Screenshare app state governs the App Builder Local User Screenshare functionality.

ScreenshareContextInterface

Key	Type	Description
isScreenshareActive	boolean	Indicates if screenshare is active for the local user
startScreenshare	() => void	Starts screenshare
stopScreenshare	() => void	Stops screenshare

Usage example of the app state:

turnkey

import { useScreenshare } from "customization-api";

...

const { isScreenshareActive, startScreenshare, stopScreenshare } = useScreenshare();

react-sdk

import { useScreenshare } from "@appbuilder/react";

...

const { isScreenshareActive, startScreenshare, stopScreenshare } = useScreenshare();

web-sdk

import { useScreenshare } from "@appbuilder/web";

...

const { isScreenshareActive, startScreenshare, stopScreenshare } = useScreenshare();

---

useSidePanel(selector?: Selector): SidePanelContextInterface

The SidePanel app state governs the sidePanel ui.

SidePanelContextInterface

Key	Type	Description
sidePanel	SidePanelType	Active sidepanel name
setSidePanel	( sidepanel: SidePanelType ) => void	Method to set active sidepanel name

SidePanelType: string

Pre-defined values for system usage: 'None' | 'Participants' | 'Chat' | 'Settings' | 'Transcript' | 'VirtualBackground'

To hide any Side Panel then setSidePanel to 'None'

setSidePanel('None')

To activate/display any existing Side Panel then setSidePanel with pre-defined values

setSidePanel('Participants')

To activate/display any Custom Side Panel(user-defined using customization API) then setSidePanel with custom side panel name

'Side-Panel-One' is name attribute which you have passed in customSidePanel API

setSidePanel('Side-Panel-One')

Usage example of the app state:

turnkey

import { useSidePanel, SidePanelType } from "customization-api";

...

const { sidePanel, setSidePanel } = useSidePanel();

react-sdk

import { useSidePanel, SidePanelType } from "@appbuilder/react";

...

const { sidePanel, setSidePanel } = useSidePanel();

web-sdk

import { useSidePanel, SidePanelType } from "@appbuilder/web";

...

const { sidePanel, setSidePanel } = useSidePanel();

---

useChatUIControl(selector?: Selector): ChatUIControlInterface

The ChatUIControl app state governs the chat ui.

ChatUIControlInterface

Key	Type	Description
groupActive	boolean	Determines if group tab is active in chat sidepanel
setGroupActive	(status: boolean) => void	Method to set group tab active status
privateActive	boolean	Determines if private tab is active in chat sidepanel
setPrivateActive	(status: boolean) => void	Method to set private tab active status
selectedChatUserId	uidtype	Uid of the user selected in private chat tab
setSelectedChatUserId	(uid: uidtype) => void	Method to set selected user
message	string	Content of message to be sent
setMessage	(message: string) => void	Method to set content of message to be sent
inputHeight	number	Initial Height of TextInput, it will expand dynamically based upon no of lines of text input.
setInputHeight	(height: number) => void	Method to update the height of TextInput
showEmojiPicker	boolean	Determines if the emoji panel needs to be shown or not
setShowEmojiPicker	(status: boolean) => void	Method to update the emoji picker status
uploadStatus	UploadStatus	Determines the upload progress status of the attachment message.
uploadedFiles	File[]	Content of the attachments to be sent.
setUploadedFiles	(uploadedFiles: File[]) => void	Method to update the content of attachments to be sent.

Usage example of the app state:

turnkey

import { useRecording } from "customization-api";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

react-sdk

import { useRecording } from "@appbuilder/react";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

web-sdk

import { useRecording } from "@appbuilder/web";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

---

useMessages(): MessageInterface

The Messages app state governs the chat messages.

MessageInterface

Key	Type	Description
groupMessages	MessageStoreInterface[]	Array of all the group messages
privateMessages	{ [key: string]: MessageStoreInterface[] }	Object containing all private messages
sendMessage	( option: ChatOption, messageStatusCallback?: MessageStatusCallback ) => void	Method to send a message.
deleteMessage	( msgId: string, to?:string , chatType?: SDKChatType ) => void	Method to delete a message
groupUnreadCount	number	Number of unread group messages
setGroupUnreadCount	(count: number) => void	method to set number of unread group messages
individualUnreadCount	{ [key: string]: number }	object containing number of unread private messages corresponding to each uid
setIndividualUnreadCount	(count: { [key: string]: number } ) => void	method to set number of unread private messages

MessageStoreInterface

key	type	description
createdTimestamp	number	message creation timestamp
updatedTimestamp?	number	last message update timestamp
msg	string	message content
msgId	string	message id
isDeleted	boolean	indicates if message is deleted
uid	UidType	uid of the message sender
type	ChatMessageType	type of message
thumb	string	thumbnail of the image message
url	string	URL of the attachment message
fileName	string	name of the attachment message
ext	string	extension of the attachment message

usage example of the app state:

turnkey

import { useMessages } from "customization-api";

const {
  groupMessages,
  privateMessages,
  sendMessage,
  deleteMessage,
  groupUnreadCount,
  setGroupUnreadCount,
  indIvidualUnreadCount,
  setIndividualUnreadCount,
} = useMessages();

react-sdk

import { useMessages } from "@appbuilder/react";

const {
  groupMessages,
  privateMessages,
  sendMessage,
  deleteMessage,
  groupUnreadCount,
  setGroupUnreadCount,
  indIvidualUnreadCount,
  setIndividualUnreadCount,
} = useMessages();

web-sdk

import { useMessages } from "@appbuilder/web";

const {
  groupMessages,
  privateMessages,
  sendMessage,
  deleteMessage,
  groupUnreadCount,
  setGroupUnreadCount,
  indIvidualUnreadCount,
  setIndividualUnreadCount,
} = useMessages();

---

useVideoQuality() : videoQualityInterface

The Video Quality app state provides option to change the encoder resolution for video and screenShare profiles

videoQualityInterface

Here's the table for the properties related to video and screen share quality settings:

Key	Type	Description
currentVideoQuality	VideoEncoderConfigurationPreset | VideoEncoderConfiguration	The current video quality configuration.
setVideoQuality	(videoQuality: VideoEncoderConfigurationPreset | VideoEncoderConfiguration) => void	Function to set the video quality configuration.
currentScreenShareQuality	ScreenEncoderConfigurationPreset | VideoEncoderConfiguration	The current screen share quality configuration.
setScreenShareQuality	(screenShareQuality: ScreenEncoderConfigurationPreset | VideoEncoderConfiguration) => void	Function to set the screen share quality configuration.
videoEncoderPresets	VideoEncoderConfigurationPreset[]	An array of available video encoder presets.
screenShareEncoderPresets	ScreenEncoderConfigurationPreset[]	An array of available screen share encoder presets.

usage example of the app state:

turnkey

import { useVideoQuality } from "customization-api";

const { setVideoQuality, setScreenShareQuality } = useVideoQuality();

const videoEncoderConfig = {
  width: 960,
  height: 720,
  frameRate: 30,
  bitRateMax: 1380,
  bitRateMin: 800,
};
setScreenShareQuality(videoEncoderConfig);
// setScreenShareQuality('480p_1')
setVideoQuality("720p_3");

react-sdk

import { useVideoQuality } from "@appbuilder/react";

const { setVideoQuality, setScreenShareQuality } = useVideoQuality();

const videoEncoderConfig = {
  width: 960,
  height: 720,
  frameRate: 30,
  bitRateMax: 1380,
  bitRateMin: 800,
};
setScreenShareQuality(videoEncoderConfig);
// setScreenShareQuality('480p_1')
setVideoQuality("720p_3");

web-sdk

import { useVideoQuality } from "@appbuilder/web";

const { setVideoQuality, setScreenShareQuality } = useVideoQuality();

const videoEncoderConfig = {
  width: 960,
  height: 720,
  frameRate: 30,
  bitRateMax: 1380,
  bitRateMin: 800,
};
setScreenShareQuality(videoEncoderConfig);
// setScreenShareQuality('480p_1')
setVideoQuality("720p_3");

---

useVirtualBackground(): virtualBackgroundInterface

The Virtual Background app state that governs the ui for virtual background.

virtualBackgroundInterface

Key	Type	Description
virtualBackgrounds	VBOption[]	An array of available virtual background options.
addVirtualBackgrounds	(options: VBOption[]) => void	Function to add new virtual background options to the list.
setVBPreview	(type: VBMode, path: string) => void	Function to set a preview of a virtual background.
applyVirtualBackground	() => void	Function to apply the selected virtual background.
isVirtualBackgroundPanelOpen	boolean	A boolean value that returns true if the virtual background panel is open, and false otherwise.
hideVirtualBackgroundPanel	() => void	Function to hide the virtual background panel.
showVirtualBackgroundPanel	() => void	Function to show the virtual background panel.

usage example of the app state:

turnkey

import { useVirtualBackground } from "customization-api";

const {
  virtualBackgrounds,
  addVirtualBackgrounds,
  applyVirtualBackground,
  setVBPreview,
} = useVirtualBackground();

react-sdk

import { useVirtualBackground } from "@appbuilder/react";

const {
  virtualBackgrounds,
  addVirtualBackgrounds,
  applyVirtualBackground,
  setVBPreview,
} = useVirtualBackground();

web-sdk

import { useVirtualBackground } from "@appbuilder/web";

const {
  virtualBackgrounds,
  addVirtualBackgrounds,
  applyVirtualBackground,
  setVBPreview,
} = useVirtualBackground();

---

useBeautyEffects(): BeautyEffectInterface

The Beauty Effects app state controls the application of image enhancement options.

BeautyEffectsInterface

Key	Type	Description
applyBeautyEffect	(config: BeautyEffects) => void	Function to apply the given beauty effects configuration.
removeBeautyEffect	() => void	Function to remove the applied beauty effects.

usage example of the app state:

turnkey

import { useBeautyEffects } from "customization-api";

const { applyBeautyEffect } = useBeautyEffects();

applyBeautyEffect({
  lighteningContrastLevel: 1,
  rednessLevel: 0.5,
  sharpnessLevel: 1,
  lighteningLevel: 1,
  smoothnessLevel: 1,
});

react-sdk

import { useBeautyEffects } from "@appbuilder/react";

const { applyBeautyEffect } = useBeautyEffects();

applyBeautyEffect({
  lighteningContrastLevel: 1,
  rednessLevel: 0.5,
  sharpnessLevel: 1,
  lighteningLevel: 1,
  smoothnessLevel: 1,
});

web-sdk

import { useBeautyEffects } from "@appbuilder/web";

const { applyBeautyEffect } = useBeautyEffects();

applyBeautyEffect({
  lighteningContrastLevel: 1,
  rednessLevel: 0.5,
  sharpnessLevel: 1,
  lighteningLevel: 1,
  smoothnessLevel: 1,
});

---

useContent(selector?: Selector): ContentStateInterface

The Content app state governs the information necessary to render each user content view displayed in the videocall screen.

it is composed of:

ContentStateInterface

key	type	description
defaultContent	ContentObjects	Object containing information necessary to render the content view corresponding to each uid in the Content app state
activeUids	array<Uidtype>	Array of all uids in the Content app state

Each ContentObject in the defaultContent is passed as a prop to corresponding type of content component. All the resulting components are then passed to the layouts as an array to be rendered as desired.

For eg. The Content app state contains a contentobject of type:'rtc' for each user in the room by default stored in defaultContent. It is used to display user video feeds coming from AgoraRTC hence they contain all the necessary information like: uid to identify and subscribe to the video and audio, audio and video mute states to correctly display fallbacks and icons, etc. each ContentObject is passed as a prop to MaxVideoView. After which the resulting array of components is passed to layout to be rendered.

tip

You can add custom content objects to the render app state using the 'AddCustomContent' action in dispatch

Usage example of the app state:

turnkey

import { useContent } from "customization-api";

...

const { defaultContent, activeUids } = useContent();

react-sdk

import { useContent } from "@appbuilder/react";

...

const { defaultContent, activeUids } = useContent();

web-sdk

import { useContent } from "@appbuilder/web";

...

const { defaultContent, activeUids } = useContent();

---

useLocalUserInfo(): LocalUserInfo

The LocalUserInfo app state contains the local user information like uid, audio and video mute states etc.

Usage example of the app state:

turnkey

import { useLocalUserInfo } from "customization-api";

...

const {
  uid,
  audio,
  video,
  type,
  streamType
  name,
  screenUid,
  offline,
} = useLocalUserInfo();

react-sdk

import { useLocalUserInfo } from "@appbuilder/react";

...

const {
  uid,
  audio,
  video,
  type,
  streamType
  name,
  screenUid,
  offline,
} = useLocalUserInfo();

web-sdk

import { useLocalUserInfo } from "@appbuilder/web";

...

const {
  uid,
  audio,
  video,
  type,
  streamType
  name,
  screenUid,
  offline,
} = useLocalUserInfo();

---

useLayout(selector?: Selector): LayoutContextInterface

The Layout app state governs the video call screen content display layout.

LayoutContextInterface

Key	Type	Description
currentLayout	string	Name of the current layout. Can be grid, pinned or any other key defined in the custom layout API
setLayout	( layoutName: string ) => void	Sets the current layout with given layout name

Usage example of the app state:

turnkey

import { useLayout } from "customization-api";

...

const { currentLayout, setLayout } = useLayout();

react-sdk

import { useLayout } from "@appbuilder/react";

...

const { currentLayout, setLayout } = useLayout();

web-sdk

import { useLayout } from "@appbuilder/web";

...

const { currentLayout, setLayout } = useLayout();

---

useRoomInfo(selector?: Selector): RoomInfoContextInterface

The RoomInfo app state contains information about the active room.

RoomInfoContextInterface

Key	Type	Description
isJoinDataFetched	boolean	Indicates room info has been fetched from the backend
data?	RoomData	Room info data

RoomData

Key	Type	Description
isHost	boolean	Indicates if the user joined using the Host URL or using the Attendee URL
meetingTitle	string	Room title
roomId	{  attendee: string,  host?: string, }	Host and attendee roomIds
pstn?	{  number: string,  pin: string }	PSTN info
isSeparateHostLink	boolean	Indicates if separate host and attendee links generated
channel?	string	Channel name of current room
uid?	UidType	Uid of the local user
token?	string	RTC authentication token required to join the channel
rtmToken?	string	RTM authentication token required to join the channel
encryptionSecret?	string	Packet encryption secret
screenShareUid?	string	Uid of local user's screenshare
screenShareToken?	string	Authentication token for local user's screenshare
loginToken?	string	Used to authenticate API Request.(Applicable for SDK Usage)

Usage example of the app state:

turnkey

import { useRoomInfo } from "customization-api";

...

const { isJoinDataFetched, data } = useRoomInfo();

react-sdk

import { useRoomInfo } from "@appbuilder/react";

...

const { isJoinDataFetched, data } = useRoomInfo();

web-sdk

import { useRoomInfo } from "@appbuilder/web";

...

const { isJoinDataFetched, data } = useRoomInfo();

---

useUserName(): [userName, setUserName]

The UserName app state governs the local user's display name.

Usage example of the app state:

turnkey

import { useUserName } from "customization-api";

...

const [userName, setUserName] = useUserName();

react-sdk

import { useUserName } from "@appbuilder/react";

...

const [userName, setUserName] = useUserName();

web-sdk

import { useUserName } from "@appbuilder/web";

...

const [userName, setUserName] = useUserName();

Returns:

userName: string

setUserName: (name: string) => void;

---

useRtc(selector?: Selector): RtcInterface

The RTC app state exposes the internal RtcEngineUnsafe object.

RtcInterface

Key	Type	Description
RtcEngineUnsafe	RtcEngineUnsafe	The RtcEngineUnsafe object from the AgoraRTC SDK
setDualStreamMode	( mode: DualStreamMode ): void	Method to modify dual stream mode

danger

Avoid using RtcEngineUnsafe directly to perform actions such as muting audio, joining a channel etc. Instead rely on Actions Library or Dispatch provided by the customization-api as they handle modifying the internal app states along with performing the required action.

Usage example of the app state:

turnkey

import { useRtc } from "customization-api";

...

const { RtcEngineUnsafe, setDualStreamMode } = useRtc();

react-sdk

import { useRtc } from "@appbuilder/react";

...

const { RtcEngineUnsafe, setDualStreamMode } = useRtc();

web-sdk

import { useRtc } from "@appbuilder/web";

...

const { RtcEngineUnsafe, setDualStreamMode } = useRtc();

---

useRtm(selector?: Selector): RtmInterface

The RTM app state exposes the internal RTM state

RtmInterface

Key	Type	Description
hasUserJoinedRTM	boolean	Boolean that indicates whether a user joined in the RTM connection or not

Usage example of the app state:

turnkey

import { useRtm } from "customization-api";

...

const { hasUserJoinedRTM } = useRtm();

react-sdk

import { useRtm } from "@appbuilder/react";

...

const {  hasUserJoinedRTM } = useRtm();

web-sdk

import { useRtm } from "@appbuilder/web";

...

const { hasUserJoinedRTM } = useRtm();

---

useActiveUids(): UserUids

The useActiveUids app state exposes the details of the users who are currently active in the call.

UserUids

Key	Value	Description
uidtype	UserUidsObject	key will be user id(uid) and value will contain name, isHost

UserUidsObject

Key	Type	Description
isHost	Boolean	Flag to identify whether user is host or not
name	String	user display name

Usage example of the app state:

turnkey

import { useActiveUids } from "customization-api";

...

const uids = useActiveUids();

react-sdk

import { useActiveUids } from "@appbuilder/react";

...

const uids = useActiveUids();

web-sdk

import { useActiveUids } from "@appbuilder/web";

...

const uids = useActiveUids();

---

useAIAgent(selector?: Selector): AIAgentContextInterface

The useAIAgent app state exposes the AI Agent state

AIAgentContextInterface

Key	Value	Description
agentUID	uidtype	UID of the AI Agent
agentId	string	It is used to identiy the AI agent
agentConnectionState	aiagentstate	It is used to identiy the AI agent connection state
toggleAgentConnection	toggleagentconnection	Function to start/stop agent connection

ToggleAgentConnection

(forceStop?: boolean) => Promise<boolean>

Usage example of the app state:

turnkey

import { useAIAgent } from "customization-api";

...

const {agentConnectionState} = useAIAgent();

react-sdk

import { useAIAgent } from "@appbuilder/react";

...

const {agentConnectionState} = useAIAgent();

web-sdk

import { useAIAgent } from "@appbuilder/web";

...

const {agentConnectionState} = useAIAgent();