> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Add team members
> Administrator only. **Additive and idempotent — it never removes a member left out of the payload.** There is no endpoint to remove one through this API. Refused with 403 on a `system_managed` team.
Any `user_ids` entry that is not a member of the account — including a hidden admin's id, indistinguishable from an unknown one — fails the whole call with 404; nothing is added.
export const CloudChatYourValues = () => {
const STORAGE_KEY = "cloudchat-api-selected-account";
const CREDENTIALS_HREF = "/api-reference/cloudchat/credentials";
const [saved, setSaved] = useState(null);
const [ready, setReady] = useState(false);
useEffect(() => {
let value = null;
try {
const raw = window.localStorage.getItem(STORAGE_KEY);
if (raw) {
const parsed = JSON.parse(raw);
if (parsed && parsed.instance && parsed.account) {
value = {
instance: String(parsed.instance),
account: String(parsed.account),
name: typeof parsed.name === "string" && parsed.name ? parsed.name : null
};
}
}
} catch (error) {
value = null;
}
setSaved(value);
setReady(true);
}, []);
const shell = "not-prose rounded-xl border border-gray-200 dark:border-white/10 bg-gray-50 dark:bg-white/5 px-4 py-3 mb-6";
if (!ready || !saved) {
return
Every request below needs your cloudchat-instance header and your account
id.{" "}
Paste your token
{" "}
and they will show up here, ready to copy.
;
};
## OpenAPI
````yaml api-reference/specs/cloudchat/v1.json POST /v1/accounts/{accountId}/teams/{teamId}/members
openapi: 3.0.1
info:
title: Cloud Chat API
version: v1
description: >-
The curated public surface of Cloud Chat. Every call needs two things: the
Bearer token from `POST /auth/v1/signin`, and the `cloudchat-instance`
header that says which Cloud Chat instance your company lives on.
If you don't know your instance value, the [Find your
credentials](/api-reference/cloudchat/credentials) page reads it out of your
own token in the browser.
servers:
- url: https://api.cloudhumans.com/cloudchat
description: Production
security:
- bearerAuth: []
tags:
- name: Canned Responses
description: >-
Canned responses — the shortcuts agents expand while replying. Each one
belongs to a single account and is identified by its short code.
- name: Conversations
description: >-
Read-only access to the conversations of an account. What you can see
follows the same rule as the dashboard: an administrator token sees every
inbox, an agent token only the inboxes it is a member of.
- name: Help Center
description: >-
Portals, categories and articles of the help center — the public FAQ your
customers read.
- name: Uploads
description: Store the images help center articles embed.
- name: Labels
description: >-
Read-only access to the labels an account has defined. A label is a tag
conversations and contacts carry; this endpoint only lists the label
definitions themselves.
- name: Inboxes
description: >-
Read-only access to the inboxes a token can see — every inbox of the
account for an administrator, only its memberships for an agent. Never
includes the channel's credentials.
- name: Agents
description: >-
Read-only access to the human and AI agents of an account. A hidden admin
(the platform's own support user) never appears, on the list or by id.
- name: Teams
description: >-
Teams group agents for assignment. Listing and reading are open to any
member; creating and updating a team, and managing its membership, require
an administrator token. A system-managed team (provisioned by the
platform) can be read like any other but never updated.
- name: Macros
description: >-
Macros bundle a sequence of actions an agent runs against a conversation
from the dashboard. This surface lets you list, read and write macro
definitions — running one is not part of the v1 contract. A macro is
either `global` (visible to the whole account) or `personal` (visible only
to its author); an agent token can only create personal macros.
- name: Automation Rules
description: >-
Read-only access to the account's automation rules — administrator only.
An agent token gets a 403 on every operation in this group.
- name: Availability Reasons
description: >-
The reasons an agent can go `busy` for, configured per account. Listing is
open to any member; creating, updating and deleting require an
administrator token. Deleting is a soft delete — the reason disappears
from listings but agents' past availability history keeps referencing it.
paths:
/v1/accounts/{accountId}/teams/{teamId}/members:
parameters:
- $ref: '#/components/parameters/CloudChatInstance'
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/TeamId'
post:
tags:
- Teams
summary: Add team members
description: >-
Administrator only. **Additive and idempotent — it never removes a
member left out of the payload.** There is no endpoint to remove one
through this API. Refused with 403 on a `system_managed` team.
Any `user_ids` entry that is not a member of the account — including a
hidden admin's id, indistinguishable from an unknown one — fails the
whole call with 404; nothing is added.
operationId: addTeamMembers
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddTeamMembersRequest'
responses:
'201':
description: >-
The team's full member roster after the addition, not just the ids
that were sent.
content:
application/json:
schema:
$ref: '#/components/schemas/TeamMembersResult'
'400':
description: Malformed request, or a payload with no `user_ids`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: bad_request
message: The request is malformed.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: >-
Three situations answer with this code: the account is suspended,
your token is not an administrator, or the team is `system_managed`
— the platform provisions it and it cannot be modified through this
API. The `system_managed` case answers `"This team is managed by the
platform and cannot be modified."` instead of the generic message
shown here.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: forbidden
message: You are not allowed to perform this action.
'404':
description: >-
The team does not exist on this account, or one of the ids in
`user_ids` does not resolve to a member of the account (an unknown
id and a hidden admin's id look identical here). Nothing is added
when this happens.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: not_found
message: Resource could not be found.
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
CloudChatInstance:
name: cloudchat-instance
in: header
required: true
description: >-
Your Cloud Chat instance ID — an integer, fixed for your company, told
at onboarding. [The API
overview](/api-reference/cloudchat/overview#two-headers-every-call)
explains how instances work, how to find yours, and the errors a wrong
or missing value produces.
schema:
type: integer
example: 1
AccountId:
name: accountId
in: path
required: true
description: >-
Your Cloud Chat account. It has to be an account your token grants
membership on, and it has to live on the instance in the
`cloudchat-instance` header — the two travel together. Account numbers
are only unique **within** an instance, so the same number is a
different company on another instance. Usually a mismatched pair fails
closed with a 401, because your user does not exist on the other
instance — but if your identity happens to exist on both, the call
succeeds against the other company's data, silently. Read it and you are
looking at the wrong help center; write it and you have stored into the
wrong account. Send the two values that were given to you together, and
never try a number to see what answers.
schema:
type: integer
example: 1
TeamId:
name: teamId
in: path
required: true
description: The `id` returned when the team was created or listed.
schema:
type: integer
example: 5
schemas:
AddTeamMembersRequest:
type: object
description: >-
The user ids to add, as agent user ids (not emails). Administrator only,
and refused with 403 on a `system_managed` team.
**This call is additive and idempotent — it never removes a member.** An
id already on the team is a no-op for that id; there is no endpoint to
remove a member through this API. Any id that does not resolve to a
member of the account, including a hidden admin's id (the two are
indistinguishable), fails the whole call with 404 — nothing is added.
required:
- user_ids
properties:
user_ids:
type: array
items:
type: integer
example:
- 7
- 12
TeamMembersResult:
type: object
description: >-
The team's full member roster after the call — not just the ids that
were sent.
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/TeamMember'
Error:
type: object
description: The error envelope every Cloud Chat API response uses.
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: >-
The stable, machine-readable reason. Branch on this, never on
`message`.
enum:
- unauthorized
- forbidden
- not_found
- validation_failed
- bad_request
- internal_error
example: not_found
message:
type: string
description: >-
The reason in words, localized to your account's language
(English, Spanish or Brazilian Portuguese; English when the
account is set to anything else). Wording changes with the
account and between releases, so never match on it.
Two cases stay in English whatever the account is set to:
`unauthorized`, decided before any account is known, and the
account-level `not_found`, which must not reveal the account's
language.
example: Resource could not be found.
details:
type: array
description: >-
Present on some rejections — a 400 for a refused query parameter
or upload mode, for example. One entry per offending field,
localized to the account's language like `message` — match on
`code` and `field`, never on the text.
items:
type: object
required:
- field
- code
- message
properties:
field:
type: string
description: Which request field the rule was about.
code:
type: string
description: Stable, machine-readable reason.
message:
type: string
description: The rule in words.
TeamMember:
type: object
description: An agent that belongs to the team. A hidden admin never appears here.
required:
- id
- name
- email
properties:
id:
type: integer
example: 7
name:
type: string
example: Jane Doe
email:
type: string
example: jane@acme.com
GatewayError:
type: object
description: >-
Rejected by the gateway before Cloud Chat saw it, so it does not use the
`error` envelope.
required:
- message
properties:
message:
type: string
example: API rate limit exceeded
request_id:
type: string
description: Gateway request id. Quote it when reporting a problem.
example: f3f7567638d4b65a8003057d0c77d275
responses:
Unauthorized:
description: >-
No Bearer token, or one that is expired, malformed, or not a Cognito
token. Sign in again for a fresh `id_token`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unauthorized
message: >-
Authentication is required. Send a valid Bearer token in the
Authorization header.
TooManyRequests:
description: >-
Rate limited per source IP. Note the envelope: this one is `{ "message":
... }`, because the request never reached the API.
Don't hardcode the limit — read it from the response. `Retry-After` says
how many seconds to wait, and every response (not just this one) carries
`ratelimit-limit`, `ratelimit-remaining` and `ratelimit-reset`, the last
in seconds.
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayError'
example:
message: API rate limit exceeded
InternalError:
description: >-
Something failed on our side. The response never carries the underlying
error, but it is reported to our monitoring automatically — no need to
file anything for a one-off.
Retrying is reasonable, with one caveat on `POST`: a 500 does not prove
the write did not happen, so a retry can come back `422` with
`short_code` already taken. That 422 means the first attempt succeeded —
list the account and confirm before treating it as a failure.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: internal_error
message: An unexpected error occurred. Please try again later.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
The `id_token` from `POST /auth/v1/signin`, sent as `Authorization:
Bearer `. Not the `access_token` — that one does not carry the
identity Cloud Chat authorizes on.
````