Pub API

Overview

Pub is a microservice for internal communications.

Making requests

Pub API requires valid API token or Access token

All requests should be made to https://api.giosg.com domain. Data is transferred using JSON encoding.

Typescript sdk

Typescript SDK is available via @giosg/pub-sdk npm package

Channel

Channel represents a chat.

Field	Type	Description
id	UUID	Unique identifier
name	str	Name of the channel
description	str	Description of the channel
organization_id	UUID	ID of the organization
created_at	datetime	When the channel was created
updated_at	datetime	When the channel was updated
avatar_url	URL	URL of the avatar picture
is_direct_message	boolean	Wheter the channel is a direct message channel or not
latest_message	PubMessage	Latest message
latest_message_created_at	datetime	Default ordering

Listing channels

GET /api/pub/v1/orgs/<organization_id>/channels

Responce is paginated collection

Creating channels

POST /api/pub/v1/orgs/<organization_id>/channels

Example payload:

{
  "name": "Public test channel",
  "description": "This is public channel for testing"
}

Retrieving a channel

GET /api/pub/v1/orgs/<organization_id>/channels/<channel_id>

Updating channels

PUT/PATCH /api/pub/v1/orgs/<organization_id>/channels/<channel_id>

Listing users joined channels

GET /api/pub/v1/orgs/<organization_id>/users/<user_id>/joined-channels

Retrieving a joined channel

GET /api/pub/v1/orgs/<organization_id>/users/<user_id>/joined-channels/<channel_id>

Direct message channels

Listing direct message channels

GET /api/pub/v1/orgs/<organization_id>/users/<user_id>/dm-channels

Creating direct message channels

POST /api/pub/v1/orgs/<organization_id>/users/<user_id>/dm-channels

Direct message channels are created once per members. One can not add members to a direct message channel. If a direct message channel already exists, existing channel is fetched instead of new one being created.

payload:

{
  "members": ["76d9a225-2e1c-4a41-98cb-e548b2826084"]
}

Retrieving a direct message channel

GET /api/pub/v1/orgs/<organization_id>/users/<user_id>/dm-channels/<dm_channel_id>

Message

Field	Type	Description
id	UUID	Unique identifier
channel_id	UUID	UUID of the channel
sender_id	UUID	UUID of the sender
organization_id	UUID	ID of the organization
created_at	datetime	When the channel was created
updated_at	datetime	When the channel was updated
body	object	The actual message

Message body

Field	Type	Description
version	number	Must be equal to 3
chunks	array of objects	Message chunks

Message chunks

Message consists of one or more chunks. Message chunk can be one of the following:

Field	Type	Description
type	"text"	Simple text
text	string	Chunk content

Field	Type	Description
type	"link"	A link
kind	"url" or "phone" or "email"	Link kind
text	string	Actual link

Field	Type	Description
type	"file"	File attachment
url	string	File location
name	string	File name
size	number	File size (optional)

Field	Type	Description
type	"audio"	Audio attachment
url	string	File location
title	string	File name

Field	Type	Description
type	"video"	Video attachment
url	string	File location
title	string	File name

Field	Type	Description
type	"image"	Image attachment
url	string	Image location

Listing messages of a channel

GET /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/messages

Creating a message

POST /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/messages

The id of the message can be created in the client. The body will contain the actual message in JSON. Currently the only required field in the body JSON is version.

Version	Status	Comment
1	Deprecated
2	Deprecated
3	Actual	Should be primarely used
n	-------	----------------------

payload:

{
  "id": "4b6d8087-f266-4de6-b391-62567d4a84b2",
  "body": {
    "version": 3,
    "chunks": [
      {
        "type": "text",
        "text": "Hello! Here is my message"
      }
    ]
  },
  "notify_users": ["3f770799-dc7c-4096-8b27-35a6eb45144c"],
  "notify_channel": true
}

Mentions are implemented with notify_users, notify_teams and notify_channel fields in the POST message. notify_users will send notification to given list of users if they have set the muted field to mentions in their Notification settings. notify_channel will send notification to all members of the channel, respectively.

Notice

notify_teams is not implemented yet, as pub does not yet know the concept of team.

Retrieving a message

GET /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/messages/<message_id>

Updating a message

PATCH /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/messages/<message_id>

payload:

{
  "body": {
    "version": 3,
    "chunks": [
      {
        "type": "text",
        "text": "Hello! Here is my message"
      }
    ]
  }
}

Channel member

Field	Type	Description
id	UUID	Unique identifier
channel	UUID	UUID of the channel
member_id	UUID	UUID of the member (user_id)
organization_id	UUID	ID of the organization
created_at	datetime	When the user was created
updated_at	datetime	When the user was updated
last_seen_at	datetime	When the user was last seen
unread_message_count	int	How many messages the user has not seen
is_admin	boolean	Is member channel admin or not
### Listing members of a channel

GET /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/members

Adding member to a channel (for public channels only)

POST /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/members

payload:

{
  "member_id": "93f8c232-14b4-4cf0-84c7-2ba6f17f17f7"
}

Retrieving a member

GET /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/members/<member_id>

Updating a member

PATCH /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/members/<member_id>

payload:

{
  "last_seen_at": "2016-09-01T11:31:36.042Z"
}

Notification settings

User may be able to control when to receive push notifications by adjusting notification settings. Notifcation settings are created automatically for every member with the field mode set to unmuted

Field	Type	Description
id	UUID	Unique identifier
channel	UUID	UUID of the channel
user_id	UUID	UUID of the member or user
organization_id	UUID	ID of the organization
created_at	datetime	When the user was created
updated_at	datetime	When the user was updated
mode	string	"muted", "mentions" or "unmuted"

Getting your notification settings for a channel

GET /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/members/<member_id>/notification_settings

Updating notification settings for a channel

PATCH /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/members/<member_id>/notification_settings

payload:

{
  "muted": "mentions"
}

Streams

Create live stream input for channel

POST /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/conference/create_stream

Create or ensure that working live stream input exists for given channel. If live stream input does not exist for the channel yet, a new input will be created. If live stream input exists, then it will be returned. This endpoint does not require any payload.

Field	Type	Description
rtmps_url	string	RTMP url for live stream endpoint, for example rtmps://live.cloudflare.com:443/live/foobarbaz
view_url	string	HSL playback url for stream, for example https://customer-hgtvj8sb4d5bnsnl.cloudflarestream.com/66be4bf738797e01e1fca35a7bdecdcd/manifest/video.m3u8
stream_key	string	Streaming key used with RTMPS url
stream_uid	string	Stream UID (Cloudflare ID) for the stream

List previously recorded live streams

GET /api/pub/v1/orgs/<organization_id>/channels/<channel_id>/conference/recorded_streams

List previously recorded streams that could be used to show previous streams in interactions for example.

Returns Paginated Collection of following items.

Field	Type	Description
uid	string	Stream UID (Cloudflare ID) for the stream
thumbnail	string	Url to thumbnail image of the stream
created	string	Sream recording creation time in ISO-8601 format string, for example: 2023-02-03T10:59:18.608491Z
modified	string	Sream recording lates modification time in ISO-8601 format string, for example: 2023-02-03T12:06:13.976265Z
size	int	The size of the media item in bytes.
duration	float	The duration of the video in seconds. A value of -1 means the duration is unknown. The duration becomes available after the upload and before the video is ready.
input	object	Object with width and height attributes. These tell the video height and width in pixels.
playback	object	Object with hls and dash attributes. These contain string's which are urls for playback.
meta	object	Object with name attribute. This is the name of the stream recording

List organizations live stream inputs.

GET /api/pub/v1/orgs/<organization_id>/conference/streams

List existing live stream inputs for organization. These can be shown in Interaction Builder for user to be able to select stream source for Live Stream Interaction.

Returns Paginated Collection of following items.

Field	Type	Description
channel	string	Channel ID this stream input is for
channel_name	string	Name of the channel this stream input is for
created	string	Creation time in ISO-8601 format string, for example: 2023-02-03T10:59:18.608491Z
uid	string	Stream UID (Cloudflare ID) for the stream
rtmps_url	string	RTMP url for live stream endpoint, for example rtmps://live.cloudflare.com:443/live/foobarbaz
view_url	string	HSL playback url for stream, for example https://customer-hgtvj8sb4d5bnsnl.cloudflarestream.com/66be4bf738797e01e1fca35a7bdecdcd/manifest/video.m3u8

Retrieve stream status

GET /api/pub/public/v1/orgs/<organization_id>/channels/<channel_id>/conference/stream_status

Retrieve current status of given live stream input.

Field	Type	Description
is_connected	boolean	Is streamer connected to input
is_watchable	boolean	Is stream live and watchable at given moment. It takes some time after streamer connection for stream to become watchable.
seconds_until_watchable	int	How many seconds client should wait until showing stream to visitor in order for the buffer to be generated.

Retrieve stream viewer count

GET /api/pub/public/v1/orgs/<organization_id>/channels/<channel_id>/conference/stream_viewer_count

This endpoint returns current viewer count for live stream.

Field	Type	Description
viewer_count	int	Current stream viewer count. This count of visitors ID's seen watching the stream in last 2 minutes.