Create a Chatroom

The BlendVision Chatroom system uses a different access token from BlendVision One. To access the Chatroom APIs, you must acquire a separate access token. You must obtain the API token from BlendVision One to acquire the chatroom token. For more information about the API token, see Authentication.

Create a Chatroom

If you don't already have a chatroom, you can create one by sending a POST request to the following API:

POST /bv/chatroom/v1/chatrooms

A successful response will contain an id, which is the ID of the created chatroom.

Create an Access Token for Chatroom

Once the chatroom is created, you can create the access token by sending a POST request to the following API:

POST /bv/chatroom/v1/chatrooms/{id}/tokens

Replace {id} with the ID of your chatroom.

The request body should contain the following parameters:

Name	Type	Required	Description
`role`	string	No	The role of the token. Default is `ROLE_VIEWER` if not provided. Allowed values: `ROLE_VIEWER` and `ROLE_ADMIN`
`device_id`	string	No	The device identifier of the token. Default is a generated UUID string if not provided
`subject`	string	No	The user identifier of the token. Default is a generated guest UUID string if not provided
`name`	string	No	The user name associated with the token. Default is "Admin" or "Guest" based on the specified role if not provided

Here is an example of a request in cURL:

curl --request POST \
  --url https://api.one.blendvision.com/bv/chatroom/v1/chatrooms/id/tokens \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'authorization: Bearer <chatroom-token>' \
  --data '{
    "role": "ROLE_ADMIN",
    "device_id": "string",
    "subject": "string",
    "name": "string"
  }'

To manage the chatroom, the role field must be ROLE_ADMIN.

The following example illustrates the server's response to a successful request:

{
  "token": "eyJz93a...k4laUWw",
  "expires_in": 604800
}

This response is a JSON object comprising two key components:

token: A unique identifier required for authentication in future API calls, particularly for chatroom management.
expires_in: Specifies the token's validity duration in seconds. It is important to generate a new one before expiration to maintain uninterrupted API access.

Retrieve Chatroom Details

To fetch details about the created chatroom, use the token acquired in the previous step to make a request to the following API:

GET /bv/chatroom/v1/chatrooms

The following example illustrates the server's response to a successful request:

{
  "chatroom": {
    "id": "string",
    "muted": true,
    "status": "CHAT_STATUS_UNSPECIFIED",
    "blocked_users": [
      {
        "id": "string",
        "device_id": "string",
        "custom_name": "string",
        "blocked": true,
        "action_taker": {
          "id": "string",
          "device_id": "string",
          "custom_name": "string",
          "is_admin": true,
          "blocked": true
        }
      }
    ],
    "pinned_messages": [
      {
        "message": {
          "id": "string",
          "text": "string",
          "sender": {
            "id": "string",
            "device_id": "string",
            "custom_name": "string"
          }
        },
        "action_taker": {
          "id": "string",
          "device_id": "string",
          "custom_name": "string",
          "is_admin": true,
          "blocked": true
        }
      }
    ],
    "active_poll": {
      "id": "string",
      "type": "POLL_TYPE_UNSPECIFIED",
      "status": "POLL_STATUS_UNSPECIFIED",
      "votes_count": 0,
      "multi_choice": {
        "question": "string",
        "options": [
          {
            "id": "string",
            "text": "string",
            "corrected": true,
            "votes_count": 0
          }
        ]
      },
      "started_at": "2019-08-24T14:15:22Z",
      "ended_at": "2019-08-24T14:15:22Z"
    },
    "viewer_info": {
      "enabled": true,
      "count": 0,
      "version_number": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    },
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

The response contains several key fields:

id: Identifier of the chatroom.
muted: Indicates if the chatroom is muted.
status: The current status of the chatroom.
blocked_users: List of users who are blocked from the chatroom, along with the details of the action taker.
pinned_messages: Messages that are pinned in the chatroom, with details about the sender and the action taker.
active_poll: Information about any active poll in the chatroom.
viewer_info: Data about viewers, including count and last update.
created_at and updated_at: Timestamps for the creation and last update of the chatroom.

Each field provides vital information about the chatroom, offering a comprehensive view of its current state and settings.

Get Chatroom Configuration

To initialize a chatroom, you can request the chatroom configuration data using the following API with the acquired chatroom token:

GET /bv/chatroom/v1/chatrooms/config

Upon a successful request, the server responds with a JSON object structured as follows:

{
  "connection": {
    "endpoint": "string",
    "authorizer": "string",
    "token": "eyJz93a...k4laUWw",
    "signature": "string",
    "client_id": "string"
  },
  "topic": {
    "pub": "string",
    "sub": "string"
  },
  "user": {
    "is_admin": true,
    "customer_id": "string",
    "device_id": "string",
    "custom_name": "string"
  }
}

The JSON object contains several key components essential for chatroom connectivity and interaction.

connection: This object houses all the necessary information for establishing a connection to the chatroom.
- endpoint: The endpoint URL of the chatroom.
- authorizer: The authorizing entity for the chatroom.
- token: A unique token used for establishing a connection to the chatroom.
- signature: The signature corresponding to the chatroom token.
- client_id: The client identifier for the chatroom.
topic: Contains information related to the messaging topics within the chatroom.
- pub: The topic used for publishing messages to other clients.
- sub: The topic for subscribing to receive messages from other clients.
user: Provides detailed information about the user in the context of the chatroom.
- is_admin: Boolean indicating whether the user has administrative privileges.
- customer_id: The unique identifier associated with the customer.
- device_id: The device identifier of the user.
- custom_name: The customized name assigned to the customer.

This structured response ensures that all necessary data for chatroom configuration, including connection parameters, messaging topics, and user roles, are clearly defined and accessible for proper initialization and management of the chatroom.