Rooms API

Rooms¶

The room resource that the visitor can access has the following attributes.

Attribute	Type	Description
`id`	UUID	The unique identifier of this room
`display_name`	string	Name of the room
`language_code`	string	Language of this room in ISO 639-1 code, or `null` if undefined.
`is_online`	boolean	Are there any users online in this room that the the visitor can chat with
`brand`	object	The brand used in this room as an object. Contains almost same attributes as in HTTP API section without organization specific information. `null` if default.
`chat_dialog_title`	string	Overriden chat dialog title. This is `null` by default.
`chat_logo`	string	Overriden chat logo for room. This is `null` by default.
`dialog_brand_id`	UUID	Used chat dialog brand id or `null`.
`estimated_waiting_time`	number	Estimated waiting time in seconds if enabled or `null`.
`hide_chat_dialog`	boolean	Whether to hide the visitor chat dialog or not. This is `false` by default.
`is_download_chat_log_enabled`	boolean	Whether to enable downloading the chat log or not. This is `true` by default.
`show_queue_position`	boolean	Whether to show the visitor's queue position or not. This is `false` by default.

Retrieve room details¶

Get a single room object by its ID. This may be a shared room.

GET https://service.giosg.com/api/v5/public/orgs/<organization_id>/rooms/<room_id>

Retrieve room's brand details¶

Get a single room brand object used in room by room's ID. This may be a shared room.

GET https://service.giosg.com/api/v5/public/orgs/<organization_id>/rooms/<room_id>/brand

Returns 404 if the organization has not defined brand for the room.

Online users in a Room¶

Visitors can fetch a collection of online users in a room

Attribute	Type	Description
`id`	UUID	Unique identifier
`public_name`	string	The name of the user as it would be displayed for the visitor. This is user's alias if they have one, otherwise it is their real name.
`avatar`	object	The avatar of the user as an object. It contains attributes `id`and `url`. This is `null` if the user has no avatar.

Retrieve a list of online users in a room¶

GET https://service.giosg.com/api/v5/public/orgs/<organization_id>/rooms/<room_id>/online_users

Scheduled Task¶

Get Free Scheduled Task Slots¶

Overview:

This API endpoint retrieves the free scheduled task slots for a specific room within a specified date range, adhering to the room's service hours. The maximum allowed range is 5 days.

Endpoint

GET /api/v5/public/orgs/<organization_id>/rooms/<room_id>/free_scheduled_tasks

Path Parameters

Name	Type	Description
`organization_id`	UUID	The unique identifier of the organization.
`room_id`	UUID	The unique identifier of the room.

Query Parameters

Name	Type	Required	Description
`start_date`	string	No	The start date for the range in `YYYY-MM-DD` format. Defaults to today.
`end_date`	string	No	The end date for the range in `YYYY-MM-DD` format. Defaults to today.

Response

Response Format

Returns a list of free and occupied time slots within the specified date range.

[
    {
        "slot": "2024-12-03T09:00:00Z",
        "free": true,
        "duration": 30
    },
    {
        "slot": "2024-12-03T09:30:00Z",
        "free": false,
        "duration": 30
    }
]

Field Descriptions

Field	Type	Description
`slot`	datetime	ISO 8601 datetime string for the slot.
`free`	boolean	Indicates whether the slot is available.
`duration`	integer	Duration of the slot in minutes (default 30).

Behavior

Date Validation:

If the start_date or end_date is not in YYYY-MM-DD format, the API responds with a 400 Bad Request error.
The date range cannot exceed 5 days. If exceeded, the API responds with a 400 Bad Request error.

Room Validation:

The room_id must exist and belong to the specified organization_id. If not, a 404 Not Found error is returned.

Service Hours:

The room must have service hours enabled and a timezone defined. If missing, the API responds with a 400 Bad Request error.

Occupied Slots:

Occupied slots are fetched from all of the organization's existing scheduled tasks within the date range.

Free Slot Calculation:

Free slots are calculated based on service hours, occupied slots, and a default duration of 30 minutes.
Slots are only generated for future dates: today and past dates within the range produce no slots.

Error Responses

Invalid Date Format

Status: 400 Bad Request

Response:

{
    "error": "Invalid date format. Use 'YYYY-MM-DD'."
}

Date Range Exceeds Limit

Status: 400 Bad Request

Response:

{
    "error": "Date range cannot exceed 5 days."
}

Room Not Found

Status: 404 Not Found

Response:

{
    "error": "Room does not exists."
}

Missing Service Hours

Status: 400 Bad Request

Response:

{
    "error": "Room does not have service hours or timezone."
}

Internal Server Error

Status: 500 Internal Server Error

Response:

{
    "error": "An unexpected error occurred."
}

Examples

Request

GET /api/v5/public/orgs/123e4567-e89b-12d3-a456-426614174000/rooms/5f7c84e4-4e72-11ee-be56-0242ac120002/free_scheduled_tasks?start_date=2024-12-03&end_date=2024-12-05
Authorization: Bearer <your-token>

Response

[
    {
        "slot": "2024-12-03T09:00:00Z",
        "free": true,
        "duration": 30
    },
    {
        "slot": "2024-12-03T09:30:00Z",
        "free": false,
        "duration": 30
    },
    {
        "slot": "2024-12-03T10:00:00Z",
        "free": true,
        "duration": 30
    }
]

Create Scheduled Task¶

Overview:

This API endpoint creates a new scheduled task for a visitor. Two task types are supported: telephony tasks (type 1), where an agent calls the visitor at the scheduled time, and generic tasks (type 2). Telephony tasks can optionally send an SMS confirmation with a reschedule link to the visitor.

Endpoint

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

Path Parameters

Name	Type	Description
`organization_id`	UUID	The unique identifier of the organization.
`room_id`	UUID	The unique identifier of the room.

Request Body

Field	Type	Required	Description
`visitor_id`	string	No	The visitor's ID in hexadecimal format. When given, the visitor is added as a member of the created chat session. Required for telephony tasks.
`type`	integer	Yes	Task type (1 = "Telephony", 2 = "Generic task").
`scheduled_time`	datetime	Yes	Scheduled time for the task in ISO 8601 format.
`send_sms`	boolean	No	Send an SMS confirmation with a reschedule link to the visitor. Only supported for telephony tasks and requires `reschedule_url`. Defaults to `false`.
`reschedule_url`	URL	No	Base URL included in the SMS for cancelling or rescheduling the task. The task id is appended as a `task_id` query parameter. Required when `send_sms` is `true`.

Example Request

{
    "visitor_id": "5f7c84e44e7211eebe560242ac120002",
    "type": 1,
    "scheduled_time": "2024-12-03T15:00:00Z",
    "send_sms": true,
    "reschedule_url": "https://example.com/reschedule"
}

Response

Response Format

Returns the details of the created scheduled task.

{
    "id": "UUID",
    "room_id": "UUID",
    "organization_id": "UUID",
    "scheduled_time": "ISO 8601 datetime string",
    "type": 1,
    "send_sms": false,
    "reschedule_url": "URL or null",
    "chat_id": "UUID"
}

Field Descriptions

Field	Type	Description
`id`	UUID	Unique identifier for the scheduled task.
`room_id`	UUID	Identifier for the associated room.
`organization_id`	UUID	Identifier for the associated organization.
`scheduled_time`	datetime	Scheduled time for the task in ISO 8601 format.
`type`	integer	Task type (1 = "Telephony", 2 = "Generic task").
`send_sms`	boolean	Whether an SMS confirmation was requested.
`reschedule_url`	URL/null	Base URL used in the SMS for cancelling or rescheduling the task, or `null`.
`chat_id`	UUID	Identifier of the chat session created for the task.

Behavior

Visitor Validation:

For telephony tasks, the visitor must have a phone_number visitor variable stored for the room. If it is missing, the API responds with a 400 Bad Request error.

Task Type Validation:

Only task types 1 (Telephony) and 2 (Generic task) are supported. Requests with any other type return a 403 Forbidden response.

Room and Organization Validation:

The provided room_id must correspond to an existing room. If the room does not exist, a 404 Not Found error is returned.

Scheduled Time Validation:

The scheduled time must be on a full or half hour (minutes 00 or 30).
The scheduled time must be on a future date (not today) and at most 90 days ahead.
The scheduled time must fall within the room's service hours, and the slot must not already be taken by another scheduled task of the organization.
Telephony tasks additionally require the room to have a telephony configuration.
If any of these checks fail, the API responds with a 400 Bad Request error: {"error": "Scheduled time is not valid."}.

Task Creation Workflow:

Chat Creation:

A new chat session of type scheduled is created for the associated room.

Visitor Membership:

A membership record for the visitor is added to the chat session if a visitor_id is provided.

Scheduled Task:

The scheduled task is created with the provided details.

SMS Confirmation:

If send_sms is true, an SMS with a cancel/reschedule link (<reschedule_url>?task_id=<id>) is sent to the visitor's phone number.
If sending the SMS fails, the task is deleted, the created chat is closed, further SMS sending to that number is temporarily blocked, and the API responds with a 400 Bad Request error describing the failure.

Error Responses

Bad Request

Status: 400 Bad Request
Reason: Invalid or missing required fields, an invalid scheduled time, a missing visitor phone number for a telephony task, or a failed SMS send.

Unauthorized

Status: 401 Unauthorized
Reason: Missing or invalid authentication token.

Not Found

Status: 404 Not Found
Reason: The specified room does not exist.

Forbidden

Status: 403 Forbidden
Reason: Unsupported task type, unauthorized access, or SMS sending to the visitor's number is temporarily blocked after a failed send.

Internal Server Error

Status: 500 Internal Server Error
Reason: An unexpected error occurred during task creation.

Examples

Request

POST /api/v5/public/orgs/123e4567-e89b-12d3-a456-426614174000/rooms/5f7c84e4-4e72-11ee-be56-0242ac120002/scheduled_tasks
Authorization: Bearer <your-token>
Content-Type: application/json

{
    "visitor_id": "5f7c84e44e7211eebe560242ac120002",
    "type": 1,
    "scheduled_time": "2024-12-03T15:00:00Z",
    "send_sms": true,
    "reschedule_url": "https://example.com/reschedule"
}

Response

{
    "id": "d52e1c78-4e72-11ee-be56-0242ac120002",
    "room_id": "5f7c84e4-4e72-11ee-be56-0242ac120002",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "scheduled_time": "2024-12-03T15:00:00Z",
    "type": 1,
    "send_sms": true,
    "reschedule_url": "https://example.com/reschedule",
    "chat_id": "3e0b1814-4e72-11ee-be56-0242ac120002"
}

Retrieve or Cancel Scheduled Task¶

Overview:

This API endpoint retrieves the details of an existing scheduled task, or cancels it. Cancelling a task deletes it and closes the associated chat session. This is the endpoint that a page behind the SMS reschedule link would typically use.

Endpoints

Retrieve: GET /api/v5/public/orgs/<organization_id>/rooms/<room_id>/scheduled_tasks/<task_id>/
Cancel: DELETE /api/v5/public/orgs/<organization_id>/rooms/<room_id>/scheduled_tasks/<task_id>/

Path Parameters

Name	Type	Description
`organization_id`	UUID	The unique identifier of the organization.
`room_id`	UUID	The unique identifier of the room.
`task_id`	UUID	The unique identifier of the scheduled task.

Retrieve Task

Returns the task in the same format as the create endpoint:

{
    "id": "UUID",
    "room_id": "UUID",
    "organization_id": "UUID",
    "scheduled_time": "ISO 8601 datetime string",
    "type": 1,
    "send_sms": false,
    "reschedule_url": "URL or null",
    "chat_id": "UUID"
}

Cancel Task

Deletes the scheduled task and closes the associated chat session. Returns 204 No Content on success.

Error Responses

Not Found

Status: 404 Not Found
Reason: The specified task_id does not exist.

Internal Server Error

Status: 500 Internal Server Error
Reason: An unexpected error occurred while processing the request.

Examples

Request

DELETE /api/v5/public/orgs/123e4567-e89b-12d3-a456-426614174000/rooms/5f7c84e4-4e72-11ee-be56-0242ac120002/scheduled_tasks/d52e1c78-4e72-11ee-be56-0242ac120002/
Authorization: Bearer <your-token>

Response

204 No Content