Humanity API

Humanity API simulates work of matchmaking questionnaire.

Endpoint	Method	Description
humanity:getQuestionnaireTemplate	websocket	Humanity: get questionnaire template
humanity:listSearchCards	websocket	Humanity: list search cards
humanity:updateSearchCard	websocket	Humanity: update search card
humanity:searchBySearchCard	websocket	Humanity: search rooms by search card
humanity:searchCardUpdated	websocketEvent	Humanity: search card updated event

Humanity: get questionnaire template

Method: websocket

Endpoint: humanity:getQuestionnaireTemplate

Description: Api returns same structure as matchmaking:getQuestionnaireTemplate, but with professional matrix values

Request:

{ empty }

Response:

{
    "data": {
        "template": {
            "fields": [{
                "fieldId": string  // unique id
                "type": string  // Tags/OneOfTags/Gender/Bool/StringInput/DateOfBirth
                "isRequired": bool  // this field is required to be filled in
                "isSearchable": bool  // questionnaire could be searched by this field
                "profileSection": string  // personal information/company information/social media profile
                "title": string  // title for questionnaire
                "searchTitle": string  // title for search
                "profileTitle": string  // title for profile information
                "values": { custom structure }  // available values in case of Tags/OneOfTags/Gender
                "default": { custom structure }  // default from values
                "isNested": bool  // this field has parent question
                "nestedDependsOnFieldId": string  // fieldId of parent question
                "nestedDependsOnValue": { custom structure }  // value of parent question
            }]
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Humanity: list search cards

Method: websocket

Endpoint: humanity:listSearchCards

Description: Api returns search cards for professional matrix.

Request:

{ empty }

Response:

{
    "data": {
        "searchCards": [{
            "targetUserId": string
            "parameters": map[string]{ custom structure }
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

Humanity: update search card

Method: websocket

Endpoint: humanity:updateSearchCard

Description: Api updates search card for professional matrix

Request:

{
    "data": {
        "targetUser": string
        "parameters": map[string]{ custom structure }
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "searchCard": {
            "targetUserId": string
            "parameters": map[string]{ custom structure }
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Humanity: search rooms by search card

Method: websocket

Endpoint: humanity:searchBySearchCard

Description: Api returns list of rooms according to search card criteria.

Api returns PRIVATE rooms as well, so there could be scenario when user doesn't have permission to view room, and should ask room owner for access.

Request:

{
    "data": {
        "isExactSearch": bool  // if true, return only rooms with exact matrix match
        "offset": int
        "size": int
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "rooms": [{ room structure }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

Humanity: search card updated event

Event: humanity:searchCardUpdated

Data:

{
    "data": {
        "searchCard": {
            "targetUserId": string
            "parameters": map[string]{ custom structure }
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Models

Room

{
    "id": string
    "created": timestamp
    "updated": timestamp
    "explorerStatus": string  // show/hide room in explorer
    "subscriptionStatus": string  // free/active/expired
    "environmentId": string  // id of environment asset
    "price": float  // price for room template
    "allowEmbed": bool  // allow embedding room to non valuverse web pages
    "roomIdentity": string  // verus identity of room
    "metadata": {
        "name": string
        "description": string
        "location": string
        "privacy": string  // private/public/openForAttendees
        "tags": [ string ]
        "firstStyle": string
    }
    "alias": string
    "group": string
    "domains": [ string ]
    "thumbnail": { resource structure }
    "preview": { resource structure }
    "content": [{ room style structure }]
    "owners": [{ user simple structure }]
    "invitedUsers": [{ user simple structure }]
    "stories": [{ storyline structure }]
    "cameraPositions": [{ camera position structure }]
    "hasJourneyPath": bool
    "hasPlacementAreas": bool
    "templateStyles": [ string ]
}

Resource

{
    "id": string
    "created": timestamp
    "updated": timestamp
    "title": string
    "description": string
    "location": string
    "date": string
    "category": string
    "linkId": string  // id of resource link is pointing to
    "linkType": string  // global/local
    "encryptionVersion": string  // encryption version, like 'verus.v1'
    "encryptionEpoch": int  // epoch defines key bundle that was used for encryption
    "encryptionEpk": string  // ephemeral public key that should be used to decrypt cypher data
    "belonging": string  // determines resource location in the system in a way 'belongingType:belongingPath(networkId)'
    "status": string  // pending/processing/ready/failed
    "metadata": {
        "fileName": string
        "fileSize": int
        "fileDate": timestamp
        "behaviourType": string
        "contentType": string
        "convertedFrom": string
        "link": string
        "origin": { resource origin structure }
        "geolocation": { geolocation structure }
        "dimensions": { dimensions structure }
    }
    "thumbnail": string
    "fromTemplate": bool
    "totalReactions": int  // amount of users who reacted to the resource
    "data": {
        "audio": { resource data audio structure }
        "video": { resource data video structure }
        "amazon": { resource data amazon structure }
        "imdb": { resource data imdb structure }
        "youtube": { resource data youtube structure }
        "pinterest": { resource data pinterest structure }
        "pixabay": { resource data pixabay structure }
        "facebook": { resource data facebook structure }
        "remoteUrl": { resource data remote url structure }
        "liveStream": { live stream data structure }
        "aiGeneration": { ai generation data structure }
        "thumbnailUrl": string
        "downloadUrl": string
        "directory": { resource data directory structure }
        "channel": { channel data structure }
        "googleDrive": { google drive structure }
    }
    "customParams": map[string]{ custom structure }  // client defined parameters
    "actions": [{ programmatic action with children structure }]  // custom programmatic actions from users
}

Resource Origin

{
    "type": string
    "device": string
    "deviceName": string
    "path": string
}

Geolocation

{
    "latitude": float
    "longitude": float
}

Dimensions

{
    "width": int
    "height": int
    "orientation": int
}

Resource Data Audio

{
    "title": string
    "artist": string
    "album": string
    "genre": string
    "duration": int
    "durationFloat": float
}

Resource Data Video

{
    "duration": int
    "durationFloat": float
    "hasAlphaChannel": bool  // true, if video generated from gif with transparent pixels
    "alphaChannel": string  // alpha channel video resource (if generated from gif)
}

Resource Data Amazon

{
    "asin": string
    "summary": string
    "author": [ string ]
    "manufacturer": string
    "title": string
    "publicationDate": string
    "url": string
}

Resource Data Imdb

{
    "Actors": string
    "Genre": string
    "Ratings": [{
        "Source": string
        "Value": string
    }]
    "Released": string
    "Runtime": string
    "Website": string
    "Year": string
    "Trailers": [ string ]
    "imdbID": string
}

Resource Data Youtube

{
    "videoId": string
    "formatId": string
}

Resource Data Pinterest

{
    "pin": string
    "url": string
}

Resource Data Pixabay

{
    "id": string
    "pageUrl": string
}

Resource Data Facebook

{
    "id": string
}

Resource Data Remote Url

{
    "url": string
    "urlType": string
    "favicon": string
    "title": string
}

Live Stream Data

{
    "streamId": string
    "assetId": string
    "playbackUrl": string
    "masterUrl": string
}

AI Generation Data

{
    "generationModel": string  // the model used for image generation [dall-e-3]
    "prompt": string  // a text description of the desired image
    "revisedPrompt": string  // the prompt that was used to generate the image, if there was any revision to the prompt
    "url": string  // the URL of the generated image
}

Resource Data Directory

{
    "innerContentType": string
    "innerContentCount": int
}

Channel Data

{
    "communityId": string
    "channelId": string
    "subChannelId": string
    "messageId": string
}

Google Drive

{
    "fileId": string
    "name": string
    "mimeType": string
}

Programmatic Action with children

{
    "localId": string  // local action id, operated by client side only
    "eventName": string
    "actionName": string
    "actionData": {
        "usedPropId": string
        "usedRoomId": string
        "usedNetworkId": string
        "usedStorylineId": string
        "usedQuestionId": int
        "usedQuestionnaireId": int
        "usedSegmentId": string
        "usedPlacementAreaId": string
        "usedRoomPoint": string
        "animationData": map[string]{ custom structure }
    }
    "childActions": [{ programmatic action structure }]
}

Programmatic Action

{
    "localId": string  // local action id, operated by client side only
    "eventName": string
    "actionName": string
    "actionData": {
        "usedPropId": string
        "usedRoomId": string
        "usedNetworkId": string
        "usedStorylineId": string
        "usedQuestionId": int
        "usedQuestionnaireId": int
        "usedSegmentId": string
        "usedPlacementAreaId": string
        "usedRoomPoint": string
        "animationData": map[string]{ custom structure }
    }
}

Room Style

{
    "id": string
    "created": timestamp
    "updated": timestamp
    "assetId": string
    "panels": [{ room panel structure }]
}

Room Panel

{
    "id": string
    "created": timestamp
    "updated": timestamp
    "type": string
    "mobileGeometry": { geometry structure }
    "props": [{ room prop structure }]
}

Geometry

{
    "scale": float
    "size": { xyz structure }
    "position": { xyz structure }
    "rotation": { xyz structure }
}

XYZ

{
    "x": float
    "y": float
    "z": float
}

Room Prop

{
    "id": string
    "created": timestamp
    "updated": timestamp
    "mobileGeometry": { geometry structure }
    "title": string
    "description": string
    "tags": [ string ]
    "propTypes": [ string ]  // booth/fileCabinet/socialCircleStatic/socialCircleDynamic/entireRoomChat
    "parentId": string  // prop id of parent where current prop is standing
    "actionType": string
    "webLink": string
    "webTitle": string
    "isInteractive": bool  // show prop when clicking next/previous in room prop list
    "showType": int  // 0 - None, 1 - GoldPanel, 2 - BoothPanel
    "contentPickerType": int  // 0 - Default, 1 - AudioContainer, 2 - VideoContainer
    "contentSorting": {
        "type": string  // default/name/date/type/size
        "direction": string  // asc/desc
    }
    "contentAppend": string  // default direction for content appending (start/end)
    "isAllowTextchat": bool  // if true - allow prop textchat
    "allowUserParams": bool  // if true - allow custom params per user
    "customParams": map[string]{ custom structure }  // client defined params
    "actions": [{ programmatic action with children structure }]  // custom programmatic actions from users
    "dataBound": {  // bound prop data to some action
        "isEnabled": bool
        "dataBoundAction": string
    }
    "assetId": string
    "assetTitle": string
    "assetSkins": map[string]string  // map of selected skins per variants
    "roomId": string
    "roomTitle": string
    "styleId": string
    "panelId": string
    "placementAreaId": string  // in case if prop is a part of placement area
    "contentSource": {  // if present, current prop will fetch content from source prop
        "roomId": string
        "propId": string
    }
    "contentCount": int  // amount of resources in prop
    "content": [{ resource structure }]  // prop resources
}

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
}

Storyline

{
    "id": string
    "created": timestamp
    "updated": timestamp
    "title": string
    "data": string
    "published": bool
    "roomId": string
    "propId": string
}

Camera Position

{
    "id": string
    "created": timestamp
    "updated": timestamp
    "position": { xyz structure }
    "rotation": { xyzw structure }
    "name": string
    "cameraMode": int
}

XYZW

{
    "x": float
    "y": float
    "z": float
    "w": float
}