Videochat handshake API

Endpoint	Method	Description
videochat:requestDirectVideochat	websocket	Request direct videochat
videochat:invite	websocket	Invite to videochat
videochat:acceptVideochatRequest	websocket	Accept videochat request
videochat:declineVideochatRequest	websocket	Decline videochat request
videochat:mergeToVideochat	websocket	Merge to videochat
videochat:videochatRequested	websocketEvent	Videochat requested event
videochat:directVideochatRequestAccepted	websocketEvent	Direct videochat request accepted event
videochat:videochatAccepted	websocketEvent	Videochat accepted event
videochat:videochatDeclined	websocketEvent	Videochat declined event

Request direct videochat

Method: websocket

Endpoint: videochat:requestDirectVideochat

Description: Request direct videochat call with a user.

If opponent user not found, server will answer with error code 1021.

If opponent user is not available, server will answer with error code 10011.

If opponent user is available, server will answer with videochatRequestId, which is used for handshake operation.

Request:

{
    "data": {
        "targetUser": string
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "videochatRequestId": string
    }
    "error": { "status": bool, "code": int, "message": string }
}

Invite to videochat

Method: websocket

Endpoint: videochat:invite

Description: Invite user to an existing videochat.

If opponent user not found, server will answer with error code 1021.

If opponent user is not available, server will answer with error code 10011.

If opponent user is available, server will send him an event to join videochat.

Request:

{
    "data": {
        "targetUser": string
        "videochatId": string
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "videochatRequestId": string
    }
    "error": { "status": bool, "code": int, "message": string }
}

Accept videochat request

Method: websocket

Endpoint: videochat:acceptVideochatRequest

Description: Accept incoming videochat call. This API could be requested only by opponent user who is receiving incoming videochat call.

Request:

{
    "data": {
        "videochatRequestId": string
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "videochatId": string
        "videochatMode": string  // videochat/conference/networkConference
        "videochatEngine": string  // twilio/agora/livekit
        "videochatAppId": string  // appId for agora
        "videochatUrl": string  // videochat server url for livekit
        "room": string
        "identity": string
        "uid": int  // numeric identity for agora
        "token": string
        "sharedSecret": string  // shared secret for livekit E2E
        "user": { user simple structure }
        "permissions": {
            "isModerator": bool  // deprecated, use isOwner and isPanelist instead
            "isOwner": bool  // owner and moderator of the videochat, cannot be demoted
            "isPanelist": bool  // temporary moderator of the videochat
            "isPresenter": bool  // have permission to make a presentation, only one active presenter per videochat
            "isCoPresenter": bool  // have permission to participate and speak in the videochat, appears near the presenter on the presentation board
            "isPromoted": bool  // have permission to participate and speak in the videochat
            "isParticipant": bool  // have permission to participate in the videochat, can ask for a promotion
            "isListener": bool  // have permission to listen the videochat stream, doesn't participate in actual conversation
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Decline videochat request

Method: websocket

Endpoint: videochat:declineVideochatRequest

Description: Decline videochat call. This API could be requested by both, initiator and opponent user.

Request:

{
    "data": {
        "videochatRequestId": string
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "error": { "status": bool, "code": int, "message": string }
}

Merge to videochat

Method: websocket

Endpoint: videochat:mergeToVideochat

Description: If User A has incoming DIRECT call request (from User B) while in another videochat, he could merge User B to current videochat.

Request:

{
    "data": {
        "videochatId": string
        "videochatRequestId": string
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "error": { "status": bool, "code": int, "message": string }
}

Videochat requested event

Event: videochat:videochatRequested

Description: Opponent user will receive this event when he is requested to join videochat. User can accept or decline incoming call using videochatRequestId.

Data:

{
    "data": {
        "videochatRequestId": string
        "user": { user simple structure }  // user who initiated videochat request
        "participants": [{ user simple structure }]  // current videochat participants (max 10)
        "counter": int  // total users in videochat
    }
    "error": { "status": bool, "code": int, "message": string }
}

Direct videochat request accepted event

Event: videochat:directVideochatRequestAccepted

Description: Direct videochat initiator user will receive this event when opponent user accepts the call.

Data:

{
    "data": {
        "videochatId": string
        "videochatMode": string  // videochat/conference/networkConference
        "videochatEngine": string  // twilio/agora/livekit
        "videochatAppId": string  // appId for agora
        "videochatUrl": string  // videochat server url for livekit
        "room": string
        "identity": string
        "uid": int  // numeric identity for agora
        "token": string
        "sharedSecret": string  // shared secret for livekit E2E
        "user": { user simple structure }
        "permissions": {
            "isModerator": bool  // deprecated, use isOwner and isPanelist instead
            "isOwner": bool  // owner and moderator of the videochat, cannot be demoted
            "isPanelist": bool  // temporary moderator of the videochat
            "isPresenter": bool  // have permission to make a presentation, only one active presenter per videochat
            "isCoPresenter": bool  // have permission to participate and speak in the videochat, appears near the presenter on the presentation board
            "isPromoted": bool  // have permission to participate and speak in the videochat
            "isParticipant": bool  // have permission to participate in the videochat, can ask for a promotion
            "isListener": bool  // have permission to listen the videochat stream, doesn't participate in actual conversation
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Videochat accepted event

Event: videochat:videochatAccepted

Description: Opponent user will receive this event in all his sockets (if has many) if he accepts the call. This way other sockets would know that the call is already accepted.

Data:

{
    "data": {
        "videochatRequestId": string
    }
    "error": { "status": bool, "code": int, "message": string }
}

Videochat declined event

Event: videochat:videochatDeclined

Description: Initiator user will receive this event when opponent user declines the call. Opponent user will receive this event in all his sockets (if has many) if he declines the call. This way other sockets would know that the call is already declined.

Data:

{
    "data": {
        "videochatRequestId": string
    }
    "error": { "status": bool, "code": int, "message": string }
}

Models

User Simple

{
    "id": string
    "firstName": string
    "lastName": string
    "privacyMode": int  // 0 - Default, 1 - Incognito
    "avatar": string
    "avatar3D": {  // field is not returned if empty
        "assetId": string
        "assetSkins": map[string]string  // map of selected skins per variants
        "avatarUrl": string  // url to gbl file (Ready Player Me)
        "avatarUserId": string  // user id for session recovery (Ready Player Me)
    }
    "companyName": string  // name of company that user represents
    "companyTitle": string  // user title in the company
}