Skip to content

Visitors API

Room visitors

A visitor has a separate representation for each room. Room visitor has the following attributes:

Attribute Type Description
id string Unique identifier for the visitor. This is the same for the same visitor regardless of the room from which the visitor was requested.
room_id UUID ID of the room from which this room visitor resource was requested
presence_expires_in integer The number of seconds the system should keep this visitor present. Only the latest provided value applies for the visitor.

Create a new room visitor

You can create a new visitor to the given room:

POST /api/v5/public/orgs/<organization_id>/rooms/<room_id>/visitors

Attribute Required
id required
presence_expires_in optional

Example request:

1
POST https://service.giosg.com/api/v5/public/orgs/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/rooms/ba85ce76-99f6-4ed3-8cb2-e22a0d12c513/visitors

Example payload:

1
2
3
4
{
  "id": "08119566026a4e1194a7a3244c90f925",
  "presence_expires_in": 60
}

Example response:

1
2
3
4
5
{
  "id": "08119566026a4e1194a7a3244c90f925",
  "room_id": "ba85ce76-99f6-4ed3-8cb2-e22a0d12c513",
  "presence_expires_in": 60
}

This endpoint returns:

  • 200 if there was an existing visitor with the given id
  • 201 if a new visitor was created successfully
  • 400 if required attributes are missing
  • 400 if the provided id is invalid
  • 400 if payload attributes are in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have access to the organization
  • 404 if the room was not found

Update room visitor presence

You can update room visitor presence:

PUT/PATCH /api/v5/public/orgs/<organization_id>/rooms/<room_id>/visitors/<visitor_id>

Attribute Required
presence_expires_in required

Example request:

1
PUT https://service.giosg.com/api/v5/public/orgs/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/rooms/ba85ce76-99f6-4ed3-8cb2-e22a0d12c513/visitors/08119566026a4e1194a7a3244c90f925

Example payload:

1
2
3
{
  "presence_expires_in": 40
}

Example response:

1
2
3
4
5
{
  "id": "08119566026a4e1194a7a3244c90f925",
  "room_id": "ba85ce76-99f6-4ed3-8cb2-e22a0d12c513",
  "presence_expires_in": 40
}

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing
  • 400 if payload attributes are in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have access to the organization
  • 404 if the room was not found
  • 404 if the visitor was not found