---
url: /apidocs/videochat.md
---
## Videochat API

| Endpoint | Method | Description |
|-----|-----|-----|
| [/api/v0/rpc/videochat.setMicrophoneStatus](#set-microphone-status) | jsonRpc | Set microphone status |
| [videochat:subscribe](#videochat-subscribe) | websocket | Videochat subscribe |
| [videochat:unsubscribe](#videochat-unsubscribe) | websocket | Videochat unsubscribe |
| [videochat:subscribeToRoomVideochats](#subscribe-to-room-videochats) | websocket | Subscribe to room videochats |
| [videochat:unsubscribeFromRoomVideochats](#unsubscribe-from-room-videochats) | websocket | Unsubscribe from room videochats |
| ~~[videochat:subscribeToPlaygroundVideochat](#subscribe-to-playground-videochat-deprecated)~~ | websocket | Subscribe to playground videochat: deprecated |
| ~~[videochat:unsubscribeFromPlaygroundVideochat](#unsubscribe-from-playground-videochat)~~ | websocket | Unsubscribe from playground videochat |
| ~~[videochat:status](#videochat-status-deprecated)~~ | websocket | Videochat status: deprecated |
| [videochat:getStatus](#videochat-status) | websocket | Videochat status |
| [videochat:getRaisedHands](#get-raised-hands) | websocket | Get raised hands |
| [videochat:getTokenForVideochat](#get-token-for-new-videochat) | websocket | Get token for new videochat |
| [videochat:getTokenForPropConference](#get-token-for-prop-conference) | websocket | Get token for prop conference |
| [videochat:getTokenForDirectVideochat](#get-token-for-direct-videochat) | websocket | Get token for direct videochat |
| [videochat:getTokenForPersonalConference](#get-token-for-personal-conference) | websocket | Get token for personal conference |
| [videochat:getTokenForPlaygroundVideochat](#get-token-for-playground-videochat) | websocket | Get token for playground videochat |
| [videochat:getTokenForSpeedDatingVideochat](#get-token-for-speed-dating-videochat) | websocket | Get token for speed dating videochat |
| [videochat:getToken](#get-token-for-videochat) | websocket | Get token for videochat |
| [videochat:getAdditionalTokenForVideochat](#get-additional-token-for-videochat) | websocket | Get additional token for videochat |
| [videochat:getListenerTokenForVideochat](#get-listener-token-for-videochat) | websocket | Get listener token for videochat |
| [videochat:onConnection](#on-participant-connected-to-videochat) | websocket | On participant connected to videochat |
| [videochat:onDisconnection](#on-participant-disconnected-from-videochat) | websocket | On participant disconnected from videochat |
| [videochat:endVideochat](#end-videochat) | websocket | End videochat |
| [videochat:transfer](#transfer-videochat) | websocket | Transfer videochat |
| [videochat:userGoesToBackgroundMode](#videochat-user-goes-to-background-mode) | websocket | Videochat user goes to background mode |
| [videochat:userReturnsFromBackgroundMode](#videochat-user-returns-from-background-mode) | websocket | Videochat user returns from background mode |
| [videochat:changeParticipantPermissions](#change-videochat-participant-permissions) | websocket | Change videochat participant permissions |
| [videochat:requestConferencePromotion](#request-conference-promotion) | websocket | Request conference promotion |
| [videochat:declineConferencePromotion](#decline-conference-promotion) | websocket | Decline conference promotion |
| [videochat:startScreenShare](#start-videochat-screen-share) | websocket | Start videochat screen share |
| [videochat:stopScreenShare](#stop-videochat-screen-share) | websocket | Stop videochat screen share |
| [videochat:muteAll](#videochat-mute-all) | websocket | Videochat mute all |
| [videochat:unmuteAll](#videochat-unmute-all) | websocket | Videochat unmute all |
| [videochat:setMicrophoneStatus](#set-microphone-status) | websocket | Set microphone status |
| [videochat:setHandStatus](#set-hand-status) | websocket | Set hand status |
| [videochat:setPresenterOnlyMode](#set-presenter-only-mode) | websocket | Set presenter only mode |
| [videochat:removeVideoStream](#remove-videochat-video-stream) | websocket | Remove videochat video stream |
| [videochat:turnOffUserOption](#turn-off-user-option) | websocket | Turn off user option |
| [videochat:startLiveStream](#videochat-start-live-stream) | websocket | Videochat start live stream |
| [videochat:stopLiveStream](#videochat-stop-live-stream) | websocket | Videochat stop live stream |
| [videochat:startLiveStreamOnly](#videochat-start-live-stream-only) | websocket | Videochat start live stream only |
| [videochat:startRecording](#videochat-start-recording) | websocket | Videochat start recording |
| [videochat:stopRecording](#videochat-stop-recording) | websocket | Videochat stop recording |
| [videochat:setSettings](#videochat-set-settings) | websocket | Videochat set settings |
| [videochat:deleteSettings](#videochat-delete-settings) | websocket | Videochat delete settings |
| [videochat:getSettings](#videochat-get-settings) | websocket | Videochat get settings |
| [videochat:getVideochatInfoOfRoomProps](#get-videochat-info-of-room-props) | websocket | Get videochat info of room props |
| [videochat:broadcastAction](#videochat-broadcast-action) | websocket | Videochat broadcast action |
| [videochat:requestLastBroadcastAction](#videochat-request-last-broadcast-action) | websocket | Videochat request last broadcast action |
| [videochat:setCustomData](#set-videochat-custom-data) | websocket | Set videochat custom data |
| [videochat:getCustomData](#get-videochat-custom-data) | websocket | Get videochat custom data |
| [videochat:searchRoomsWithActiveVideochat](#search-rooms-with-active-videochat) | websocket | Search rooms with active videochat |
| [videochat:started](#videochat-started-event) | websocketEvent | Videochat started event |
| ~~[videochat:videochatStarted](#videochat-started-event-deprecated)~~ | websocketEvent | Videochat started event: deprecated |
| [videochat:videochatEnded](#videochat-ended-event) | websocketEvent | Videochat ended event |
| [videochat:videochatStatusUpdated](#videochat-status-updated-event) | websocketEvent | Videochat status updated event |
| [videochat:sourceChanged](#videochat-source-changed-event) | websocketEvent | Videochat source changed event |
| [videochat:identityConnected](#videochat-identity-connected-event) | websocketEvent | Videochat identity connected event |
| [videochat:identityDisconnected](#videochat-identity-disconnected-event) | websocketEvent | Videochat identity disconnected event |
| ~~[videochat:participantConnected](#participant-connected-event)~~ | websocketEvent | Participant connected event |
| ~~[videochat:participantDisconnected](#participant-disconnected-event)~~ | websocketEvent | Participant disconnected event |
| ~~[videochat:participantUpdated](#participant-updated-event)~~ | websocketEvent | Participant updated event |
| [videochat:conferencePromotionRequested](#conference-promotion-requested-event) | websocketEvent | Conference promotion requested event |
| [videochat:conferencePromotionDeclined](#conference-promotion-declined-event) | websocketEvent | Conference promotion declined event |
| [videochat:participantIdentityUpdated](#participant-identity-updated-event) | websocketEvent | Participant identity updated event |
| [videochat:userInvitedToVideochat](#user-invited-to-videochat-event) | websocketEvent | User invited to videochat event |
| [videochat:shareScreenStarted](#share-screen-started-event) | websocketEvent | Share screen started event |
| [videochat:shareScreenStopped](#share-screen-stopped-event) | websocketEvent | Share screen stopped event |
| [videochat:muteAll](#videochat-mute-all-event) | websocketEvent | Videochat mute all event |
| [videochat:unmuteAll](#videochat-unmute-all-event) | websocketEvent | Videochat unmute all event |
| [videochat:removeVideoStream](#remove-videochat-video-stream-event) | websocketEvent | Remove videochat video stream event |
| [videochat:turnOffUserOption](#videochat-turn-off-option-event) | websocketEvent | Videochat turn off option event |
| [videochat:liveStreamStarted](#videochat-live-stream-started-event) | websocketEvent | Videochat live stream started event |
| [videochat:liveStreamStopped](#videochat-live-stream-stopped-event) | websocketEvent | Videochat live stream stopped event |
| [videochat:recordingStarted](#videochat-recording-started-event) | websocketEvent | Videochat recording started event |
| [videochat:recordingStopped](#videochat-recording-stopped-event) | websocketEvent | Videochat recording stopped event |
| [videochat:propVideochatCountChanged](#prop-videochat-count-changed-event) | websocketEvent | Prop videochat count changed event |
| [videochat:action](#videochat-action-event) | websocketEvent | Videochat action event |
| [videochat:customDataUpdated](#videochat-custom-data-updated-event) | websocketEvent | Videochat custom data updated event |

### Set microphone status

**Method:** jsonRpc

**HTTP Method:** POST

**Path:** /api/v0/rpc/videochat.setMicrophoneStatus

**Description:** Indicate that user has changed microphone status.

Statuses:

* 0 - Off

* 1 - On

* 2 - Not Available

**Headers:**

X-Session-Id: sessionToken

**Request:**

**Response:**

### Videochat subscribe

**Method:** websocket

**Endpoint:** videochat:subscribe

**Description:** Subscribes user socket to videochat broadcasting channel.

**Request:**

**Response:**

### Videochat unsubscribe

**Method:** websocket

**Endpoint:** videochat:unsubscribe

**Description:** Subscribes user socket to videochat broadcasting channel.

**Request:**

**Response:**

### Subscribe to room videochats

**Method:** websocket

**Endpoint:** videochat:subscribeToRoomVideochats

**Description:** Subscribes user socket to all room videochat broadcasting channels.

**Request:**

**Response:**

### Unsubscribe from room videochats

**Method:** websocket

**Endpoint:** videochat:unsubscribeFromRoomVideochats

**Description:** Unsubscribes user socket from all room videochat broadcasting channels.

**Request:**

**Response:**

### Subscribe to playground videochat: deprecated

**Method:** websocket

**Endpoint:** videochat:subscribeToPlaygroundVideochat

**DEPRECATED**

**Description:** Subscribes user socket to playground videochat broadcasting channel.

**Request:**

**Response:**

### Unsubscribe from playground videochat

**Method:** websocket

**Endpoint:** videochat:unsubscribeFromPlaygroundVideochat

**DEPRECATED**

**Description:** Unsubscribes user socket from playground videochat broadcasting channel.

**Request:**

**Response:**

### Videochat status: deprecated

**Method:** websocket

**Endpoint:** videochat:status

**DEPRECATED**

**Request:**

**Response:**

### Videochat status

**Method:** websocket

**Endpoint:** videochat:getStatus

**Request:**

**Response:**

### Get raised hands

**Method:** websocket

**Endpoint:** videochat:getRaisedHands

**Description:** Returns identities that currently have their hand raised, ordered by the time they raised it (earliest first).

**Request:**

**Response:**

### Get token for new videochat

**Method:** websocket

**Endpoint:** videochat:getTokenForVideochat

**Description:** Api returns identity and token for **room**, **prop** or **group** videochat. Creates new videochat if it does not exist.

Token should be used only once. Each time client wants to connect to videochat, it should request new token.

Api could return following errors:

* 10002 - Not enough videochat permissions
* 10009 - Participant limit reached
* 10010 - Videochat not started by manager

**Request:**

**Response:**

### Get token for prop conference

**Method:** websocket

**Endpoint:** videochat:getTokenForPropConference

**Description:** Api returns identity and token for **prop** videochat. Creates new prop conference if it does not exist. See [videochat:getTokenForVideochat](#get-token-for-room-videochat) for more info on api restrictions.

**Request:**

**Response:**

### Get token for direct videochat

**Method:** websocket

**Endpoint:** videochat:getTokenForDirectVideochat

**Description:** Api creates new **direct** videochat with provided participants, and returns identity and token. In order to connect to existing videochat user should use videochat:getToken. See [videochat:getTokenForVideochat](#get-token-for-room-videochat) for more info on api restrictions.

**Request:**

**Response:**

### Get token for personal conference

**Method:** websocket

**Endpoint:** videochat:getTokenForPersonalConference

**Description:** Api creates new **personal conference**, and returns identity and token. Any other user can connect to that conference using videochat:getToken api. See [videochat:getTokenForVideochat](#get-token-for-room-videochat) for more info on api restrictions.

**Request:**

**Response:**

### Get token for playground videochat

**Method:** websocket

**Endpoint:** videochat:getTokenForPlaygroundVideochat

**Description:** Api creates new **playground** videochat, and returns identity and token. In order to connect to existing videochat user should use videochat:getToken. See [videochat:getTokenForVideochat](#get-token-for-room-videochat) for more info on api restrictions.

**Request:**

**Response:**

### Get token for speed dating videochat

**Method:** websocket

**Endpoint:** videochat:getTokenForSpeedDatingVideochat

**Description:** Api creates new **speedDating** videochat, and returns identity and token. In order to connect to existing videochat user should use videochat:getToken. See [videochat:getTokenForVideochat](#get-token-for-room-videochat) for more info on api restrictions.

**Request:**

**Response:**

### Get token for videochat

**Method:** websocket

**Endpoint:** videochat:getToken

**Description:** Api returns identity and token for existing videochat. Token should be used only once. Each time client wants to connect to videochat, it should request new token.

**Request:**

**Response:**

### Get additional token for videochat

**Method:** websocket

**Endpoint:** videochat:getAdditionalTokenForVideochat

**Description:** Api returns additional identity and token for videochat. Additional identity is used for Agora screen sharing, as it does not support multitrack. Only one additional identity could be generated for user:socket pair.

**Request:**

**Response:**

### Get listener token for videochat

**Method:** websocket

**Endpoint:** videochat:getListenerTokenForVideochat

**Description:** Api returns listener token for existing videochat. Videochat listener doesn't participate in videochat, but can watch/listen its stream.

**Request:**

**Response:**

### On participant connected to videochat

**Method:** websocket

**Endpoint:** videochat:onConnection

**Description:** Client informs server that it is connected to the videochat. This event is mentioned to duplicate (ensure that at least one is received) events from videochat engine server (twilio/agora/livekit).

**Request:**

**Response:**

### On participant disconnected from videochat

**Method:** websocket

**Endpoint:** videochat:onDisconnection

**Description:** Client informs server that it is disconnected from the videochat. This event is mentioned to duplicate (ensure that at least one is received) events from videochat engine server (twilio/agora/livekit).

**Request:**

**Response:**

### End videochat

**Method:** websocket

**Endpoint:** videochat:endVideochat

**Description:** Api ends videochat. Available for direct call participants and conference moderators.

**Request:**

**Response:**

### Transfer videochat

**Method:** websocket

**Endpoint:** videochat:transfer

**Description:** Moves an active direct videochat to a new source (e.g. escalating a direct call into a newly created group), keeping the same videochatId, participants and engine session. Only direct videochats can be transferred. Caller must already be an active participant of the videochat, and have permission to join/start a videochat at the new source.

**Request:**

**Response:**

### Videochat user goes to background mode

**Method:** websocket

**Endpoint:** videochat:userGoesToBackgroundMode

**Description:** Sets videochat identity connection status to `in-background`. If user is in background mode and socket disconnects:

* Keep user in videochat participant list.

* Keep user role (presenter, co-presenter, etc).

* Do not send `videochat:participantDisconnected` event.

**Request:**

**Response:**

### Videochat user returns from background mode

**Method:** websocket

**Endpoint:** videochat:userReturnsFromBackgroundMode

**Description:**

* Sets videochat identity connection status to `active`.

* Changes videochat identity socket to a new value.

* Subscribes new socket to videochat events.

**Request:**

**Response:**

### Change videochat participant permissions

**Method:** websocket

**Endpoint:** videochat:changeParticipantPermissions

**Description:** Room owners are videochat moderators by default. Moderator can add any permissions to other users. Presenter can transfer presentation permissions or promote/demote participant voice/video. Only one participant with presenter permission can be presented in the videochat.

**Request:**

**Response:**

### Request conference promotion

**Method:** websocket

**Endpoint:** videochat:requestConferencePromotion

**Description:** Videochat participant can request promotion (in order to ask question to presenter).

**Request:**

**Response:**

### Decline conference promotion

**Method:** websocket

**Endpoint:** videochat:declineConferencePromotion

**Description:** Promotion request could be declined by moderator, presenter or by user himself.

**Request:**

**Response:**

### Start videochat screen share

**Method:** websocket

**Endpoint:** videochat:startScreenShare

**Description:** Notify server and other participants on screen sharing start.

**Request:**

**Response:**

### Stop videochat screen share

**Method:** websocket

**Endpoint:** videochat:stopScreenShare

**Description:** Notify server and other participants on screen sharing stop.

**Request:**

**Response:**

### Videochat mute all

**Method:** websocket

**Endpoint:** videochat:muteAll

**Description:** Request all participant identities (except initiator) to mute microphones. Server doesn't change microphone statuses, but sets isMuted in videochat model.

**Request:**

**Response:**

### Videochat unmute all

**Method:** websocket

**Endpoint:** videochat:unmuteAll

**Description:** Request previously muted identities to unmute microphones.

**Request:**

**Response:**

### Set microphone status

**Method:** websocket

**Endpoint:** videochat:setMicrophoneStatus

**Description:** Indicate that user has changed microphone status.

Statuses:

* 0 - Off

* 1 - On

* 2 - Not Available

**Request:**

**Response:**

### Set hand status

**Method:** websocket

**Endpoint:** videochat:setHandStatus

**Description:** Indicate that user has changed hand status.

Statuses:

* 0 - Off

* 1 - Low

* 2 - Raise

**Request:**

**Response:**

### Set presenter only mode

**Method:** websocket

**Endpoint:** videochat:setPresenterOnlyMode

**Description:** Indicate that only presenter should be shown to other users (if set to true).

**Request:**

**Response:**

### Remove videochat video stream

**Method:** websocket

**Endpoint:** videochat:removeVideoStream

**Description:** Indicate that videochat participant has removed video stream. This api is needed because Agora iOS SDK doesn't receive event when user repeatedly removes video stream.

**Request:**

**Response:**

### Turn off user option

**Method:** websocket

**Endpoint:** videochat:turnOffUserOption

**Description:** Videochat moderator or presenter can call this api to ask target client to turn off some of his options.

Videochat options:

* 0 - All

* 1 - Camera

* 2 - Microphone

* 3 - Screen Share

* 4 - Raised Hand

**Request:**

**Response:**

### Videochat start live stream

**Method:** websocket

**Endpoint:** videochat:startLiveStream

**Description:** Videochat moderator can call this api to start MUX live stream and recording.

**Request:**

**Response:**

### Videochat stop live stream

**Method:** websocket

**Endpoint:** videochat:stopLiveStream

**Description:** Videochat moderator can call this api to stop MUX live stream (also stops recording if active).

**Request:**

**Response:**

### Videochat start live stream only

**Method:** websocket

**Endpoint:** videochat:startLiveStreamOnly

**Description:** Videochat moderator can call this api to start MUX live stream without recording.

**Request:**

**Response:**

### Videochat start recording

**Method:** websocket

**Endpoint:** videochat:startRecording

**Description:** Videochat moderator can call this api to start MUX recording on an active live stream.

**Request:**

**Response:**

### Videochat stop recording

**Method:** websocket

**Endpoint:** videochat:stopRecording

**Description:** Videochat moderator can call this api to stop MUX recording without stopping the live stream.

**Request:**

**Response:**

### Videochat set settings

**Method:** websocket

**Endpoint:** videochat:setSettings

**Request:**

**Response:**

### Videochat delete settings

**Method:** websocket

**Endpoint:** videochat:deleteSettings

**Request:**

**Response:**

### Videochat get settings

**Method:** websocket

**Endpoint:** videochat:getSettings

**Request:**

**Response:**

### Get videochat info of room props

**Method:** websocket

**Endpoint:** videochat:getVideochatInfoOfRoomProps

**Description:** Get information of all running prop videochats in the room.

**Request:**

**Response:**

### Videochat broadcast action

**Method:** websocket

**Endpoint:** videochat:broadcastAction

**Description:** Api broadcasts action (`videochat:action`) to all participants in the videochat. Same as `videochat:sync:presentationAction` but doesn't require presentation to be started.

**Request:**

**Response:**

### Videochat request last broadcast action

**Method:** websocket

**Endpoint:** videochat:requestLastBroadcastAction

**Description:** Request last broadcast action. If event exists, its data will be sent to socket. If event doesn't exist, nothing happens. Same as `videochat:sync:requestLastSyncEvent` but doesn't require presentation to be started.

**Request:**

**Response:**

### Set videochat custom data

**Method:** websocket

**Endpoint:** videochat:setCustomData

**Description:** Api sets custom data to videochat and broadcasts it to all participants.

**Request:**

**Response:**

### Get videochat custom data

**Method:** websocket

**Endpoint:** videochat:getCustomData

**Description:** Api returns videochat custom data.

**Request:**

**Response:**

### Search rooms with active videochat

**Method:** websocket

**Endpoint:** videochat:searchRoomsWithActiveVideochat

**Description:** Api returns list of rooms that have currently active videochats.

**Request:**

**Response:**

### Videochat started event

**Event:** videochat:started

**Data:**

### Videochat started event: deprecated

**Event:** videochat:videochatStarted

**DEPRECATED**

**Data:**

### Videochat ended event

**Event:** videochat:videochatEnded

**Data:**

### Videochat status updated event

**Event:** videochat:videochatStatusUpdated

**Data:**

### Videochat source changed event

**Event:** videochat:sourceChanged

**Description:** Event is sent to videochat participants when the videochat is transferred to a new source (e.g. a direct call escalated into a group call). VideochatId and the engine session stay the same.

**Data:**

### Videochat identity connected event

**Event:** videochat:identityConnected

**Description:** Event is triggered when user identity is connected to videochat.

**Data:**

### Videochat identity disconnected event

**Event:** videochat:identityDisconnected

**Description:** Event is triggered when user identity is disconnected from videochat.

**Data:**

### Participant connected event

**Event:** videochat:participantConnected

**DEPRECATED**

**Description:** Event is triggered when new user is connected to videochat. When user connects to videochat from second device/tab, `videochat:participantUpdated` event is triggered instead.

**Data:**

### Participant disconnected event

**Event:** videochat:participantDisconnected

**DEPRECATED**

**Description:** Event is triggered when user is disconnected from videochat. If user has multiple devices/tabs connected to videochat and one of these connections disconnects - `videochat:participantUpdated` event is triggered instead.

**Data:**

### Participant updated event

**Event:** videochat:participantUpdated

**DEPRECATED**

**Data:**

### Conference promotion requested event

**Event:** videochat:conferencePromotionRequested

**Data:**

### Conference promotion declined event

**Event:** videochat:conferencePromotionDeclined

**Data:**

### Participant identity updated event

**Event:** videochat:participantIdentityUpdated

**Data:**

### User invited to videochat event

**Event:** videochat:userInvitedToVideochat

**Description:** Event will be sent to videochat participants when new user is invited to the videochat.

**Data:**

### Share screen started event

**Event:** videochat:shareScreenStarted

**Data:**

### Share screen stopped event

**Event:** videochat:shareScreenStopped

**Data:**

### Videochat mute all event

**Event:** videochat:muteAll

**Data:**

### Videochat unmute all event

**Event:** videochat:unmuteAll

**Data:**

### Remove videochat video stream event

**Event:** videochat:removeVideoStream

**Data:**

### Videochat turn off option event

**Event:** videochat:turnOffUserOption

**Data:**

### Videochat live stream started event

**Event:** videochat:liveStreamStarted

**Data:**

### Videochat live stream stopped event

**Event:** videochat:liveStreamStopped

**Data:**

### Videochat recording started event

**Event:** videochat:recordingStarted

**Data:**

### Videochat recording stopped event

**Event:** videochat:recordingStopped

**Data:**

### Prop videochat count changed event

**Event:** videochat:propVideochatCountChanged

**Data:**

### Videochat action event

**Event:** videochat:action

**Data:**

### Videochat custom data updated event

**Event:** videochat:customDataUpdated

**Data:**

## Models

#### User Simple