Teams API

Teams¶

A team object contains the following attributes.

Attribute	Type	Description
`id`	UUID	The unique identifier of this team.
`organization_id`	UUID	ID of the organization who owns this team.
`organization`	object	The organization who owns this team.
`name`	string	Name of the team. Must be a non-empty string.
`display_name`	string	Display name of the team. When a team is shared, this name is shown for the receiving organization.
`member_count`	integer	Number of members (team membership(s)) in this team. Available only to your own organization.
`present_member_count`	integer	Number of present both members (team membership(s)) in this team. Available only to your own organization.
`is_online`	boolean	Whether the team is currently online, i.e. any user member from the team is online. See user(s) for more information.
`is_humans_online`	boolean	Whether there is at least one non bot user online in the team. Useful for developing chatbots, that need to know if they can transfer chats to people.
`is_present`	boolean	Whether the team is currently present, i.e. any user member from the team is present. See user(s) for more information.
`created_by_user_id`	UUID	The ID of the user who created the team.
`created_by_user`	object	The user who created the team.
`updated_by_user_id`	UUID	The ID of the user who updated the team.
`updated_by_user`	object	The user who updated the team.
`created_at`	datetime	When the team resource was created.
`updated_at`	datetime	When the team resource was updated last time.
`group_chat_id`	UUID	Chat session id of the team's fixed group chat.
`is_connected_to_room`	boolean	Whether the team is connected to room.
`is_deleted`	boolean	Whether the team has been deleted.
`deleted_at`	datetime	When the team has been deleted. `null` if not deleted.

Get a collection of organization's teams¶

Return a paginated collection of all the Team resources of an organization (<organization_id>).

GET https://service.giosg.com/api/v6/orgs/<organization_id>/teams

Parameter	Type	Default	Description
`ordering`	ordering	`created_at`	Ordering of results with options `created_at` or `-created_at`
`is_deleted`	boolean	(none)	By default returns all teams. If `true`, returns only deleted teams. If `false`, returns only active teams.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization

Retrieve organization's team details¶

Get a single team object (<team_id>) of an organization (<organization_id>). This may be a team shared to the organization.

GET https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization

Get a collection of user's teams¶

Return a paginated collection of all the Team resources of a user (<user_id>).

GET https://service.giosg.com/api/v6/users/<user_id>/teams

Parameter	Type	Default	Description
`ordering`	ordering	`created_at`	Ordering of results with options `created_at` or `-created_at`.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user

Get a collection of organization's user teams¶

Return a paginated collection of all the Team resources of an organization's (<organization_id>) user (<user_id). This means teams to which the user belongs to.

GET https://service.giosg.com/api/v6/orgs/<organization_id>/users/<user_id>/teams

Parameter	Type	Default	Description
`ordering`	ordering	`created_at`	Ordering of results with options `created_at` or `-created_at`.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
404 if user was not found

Retrieve user's team details¶

Get a single team object (<team_id>) of a user (<user_id>).

GET https://service.giosg.com/api/v6/users/<user_id>/teams/<team_id>

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if team was not found

Create a team¶

Create a team for an organization (<organization_id>)

Example request payload

{
  "name": "Test team"
}

POST https://service.giosg.com/api/v6/orgs/<organization_id>/teams

Attribute	Required	Value
`name`	required	Must be a non-empty string

This endpoint returns:

201 if the request was successful
400 if required attributes are missing from the request
400 if the request payload is in wrong format
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have users permission
404 if user was not found

Update a team¶

You may update the name of a team (<team_id>) that belongs to an organization (<organization_id>). You may also restore a deleted team.

PUT https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>

PATCH https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>

Attribute	Required	Value
`name`	optional	Must be a non-empty string
`is_deleted`	optional	Set as `false` to restore a deleted team. `true` is not a valid value - use `DELETE` request to delete a team instead.

This endpoint returns:

200 if the request was successful
400 if required attributes are missing from the request
400 if the request payload is in wrong format
400 if trying to update is_deleted to true
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have users permission
404 if team was not found

Delete a team¶

Warning

Deleting a team will set the team and all its memberships as deleted. It will unshare the team from your partners!

You may delete one of your own teams by making a DELETE request.

DELETE https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>

This endpoint returns:

204 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have users permission
404 if team was not found

Team memberships¶

A team membership represents a user belonging to a specific team. Team memberships are only visible for teams of your own organization. A team membership resource has the following attributes.

Attribute	Type	Description
`team_id`	UUID	ID of the team to which this member belongs.
`team`	object	The Team to which this member belongs, with attributes `id`, `name`, `display_name`, and `organization_id`.
`user_id`	UUID	ID of the member user.
`user`	object	The member user resource, with attributes `id`, `first_name`, `last_name`, `full_name` and `organization_id`.
`created_by_user_id`	UUID	The ID of the user who created the membership.
`created_by_user`	object	The user who created the membership.
`created_at`	datetime	When the membership resource was created.
`is_deleted`	boolean	Whether the membership has been deleted.
`deleted_at`	datetime	When the membership has been deleted. `null` if not deleted.

Team memberships are readable by any member of the same organization. However, they can be created or deleted only by organization users with users permission. Otherwise, the endpoints will return a 403 Forbidden response.

Get a collection of team memberships¶

Return a paginated collection of all the team membership resources for a specific Team.

GET https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/memberships

Parameter	Type	Default	Description
`ordering`	ordering	`created_at`	Ordering of results with options `created_at` or `-created_at`
`is_deleted`	boolean	(none)	By default returns all memberships. If `true`, returns only deleted memberships. If `false`, returns only active memberships.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
404 if team was not found

Add a member to a team¶

You may add a user of your own organization to one of your teams by creating a team membership object.

Example request payload

{
  "user_id": "ab98bd97-872c-11e7-921d-60f81dcf1946"
}

POST https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/memberships

Attribute	Required	Value
`user_id`	required	UUID of the member user

This endpoint returns:

200 if the user was already member of team
201 if user was added to the team
400 if required attributes are missing from the request
400 if the request payload is in wrong format
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have users permission
404 if team was not found

Restore deleted member¶

You may restore a deleted membership to a team.

PUT https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

PATCH https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

Attribute	Required	Value
`is_deleted`	required	Set as `false` to restore a deleted membership. `true` is not a valid value - use `DELETE` request to delete a membership instead.

This endpoint returns:

200 if the membership was successfully restored
400 if required attributes are missing from the request
400 if the request payload is in wrong format
400 if trying to update is_deleted to true
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have users permission
404 if team was not found

Remove a member from a team¶

You may remove a user from a team by deleting her membership.

DELETE https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

This endpoint returns:

204 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have users permission
404 if team was not found
404 if user was not found

Retrieve team membership details¶

You may get the a user membership resource in a team:

GET https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
404 if team was not found
404 if user was not found

Team users¶

A team user represents a user belonging to a specific team. Team users are only visible for teams of your own organization. Team users are readable by any member of the same organization.

Get a collection of team users¶

Return a paginated collection of all the team user resources of an organization.

GET https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/users

Parameter	Type	Default	Description
`ordering`	ordering	`created_at`	Ordering of results with options `created_at` or `-created_at`

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
404 if team was not found

Teamless users¶

A teamless user represents a user that is not a member of any team.

Get a collection of teamless users¶

Return a paginated collection of all the teamless user resources of an organization.

GET https://service.giosg.com/api/v6/orgs/<organization_id>/teamless_users

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization