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.

[!NOTE] 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

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"
}