support
Embed
<a href="https://gaiadesk.net/docs/ref-support"><img src="https://gaiadesk.net/docs/_api/public/orgs/89a5df38-be2c-4963-8823-21d4bd40a2ab/spaces/57b99ea0-d45a-4986-8aa6-6b0683c9fe1d/pages/50f2923d-e159-49b2-9e64-9e49c59e7c7c/social-card.svg?v=3e7ae33eec8b" alt="support" width="600" height="315"></a>https://api.gaiadesk.net/v1 /support/seats Scope supportWho on the caller's team holds a support seat, and how many seats the plan grants.
Support is billed per seat: only a team member holding a support seat may join (take) the team's support sessions as an agent in the console; any other member's join is refused (support_seat_required). How many seats a team has is its plan's support_seats (-1 = unlimited; free and pro 1, team and enterprise unlimited, unless the team's entitlement says otherwise). Creating sessions needs no seat.
The team's owner always holds a seat (owner_seat; it counts toward the limit and is never removed). The first time a team's seats are used, members who joined one of its support sessions as an agent in the last 30 days are given seats, most recent first, up to the limit (audited support_seat.auto_assigned), so the upgrade locks nobody out.
Every team member may read this. you.seated says whether the caller may join now. A team over its limit (a downgrade) keeps its oldest assignments working (seated); the newer ones wait (assigned but not seated). An account with no team (team: false) is its own one agent. Not for publishable keys.
Code samples
cURL
curl -X GET "https://api.gaiadesk.net/v1/support/seats" \
-H "Authorization: Bearer $GAIADESK_API_KEY"TypeScript
Python
Go
PHP
Ruby
Java
Responses
Example
{
"team": true,
"limit": 0,
"used": 0,
"you": {
"user_id": 0,
"seated": true,
"admin": true
},
"members": [
{
"user_id": 0,
"email": "string",
"name": "string",
"role": "string",
"assigned": true,
"seated": true,
"owner_seat": true,
"assigned_at": 0,
"assigned_by": "string"
}
]
}Schema
teambooleanrequiredfalse: the account is in no team, and is its own one agent.limitintegerrequiredsupport_seats; -1 = unlimited).usedintegerrequiredyouobjectrequiredShow child parameters
user_idintegerrequiredseatedbooleanrequiredadminbooleanrequiredmembersApiSupportSeat[]requiredShow child parameters
user_idintegerrequiredemailstringrequirednamestringrequiredrolestringrequiredowner, admin, member).assignedbooleanrequiredseatedbooleanrequiredowner_seatbooleanrequiredassigned_atintegerrequiredassigned_bystringrequiredowner for the owner's seat; system:support-seats when it was given automatically at set-up.X-Request-Idstringreq_…), also in every error body. Quote it to support.refused, unauthenticated).Example
{
"error": {
"desk": "string",
"kind": "string",
"message": "string",
"reason": "string",
"request_id": "string",
"status": 0
},
"e2e": {
"v": 0,
"events": [
{
"seq": 0,
"nonce": "string",
"ciphertext": "string"
}
]
}
}Schema
errorError & objectrequiredShow child parameters
deskstringkindstringrequiredmessagestringrequiredreasonstringoffline, unknown_desk, not_online, network, not_signed_in, timeout, local, …request_idstringrequiredstatusintegerGaiaDesk-Held) — the HTTP status this failure would have had, had its 200 not been sent already.e2eobjectmessage here is a placeholder).Show child parameters
vintegerrequiredeventsApiE2eFrame[]requiredShow child parameters
seqintegerrequirednoncestringrequiredciphertextstringrequiredrefused).Same as 401 · GET /support/seats
refused, rate_limited).Same as 401 · GET /support/seats
Retry-AfterintegerRateLimit-LimitintegerRateLimit-RemainingintegerRateLimit-Resetintegerhttps://api.gaiadesk.net/v1 /support/seats/{user_id} Scope supportGive a team member a support seat (team owners and admins).
Idempotent. Refused beyond the plan's seats (409 support_seats_exhausted), for a caller who is not the team's owner or an admin (403 not_a_team_admin), outside a team (403 no_team), and for anyone not on the team (404 unknown_member). Audited (support_seat.assigned, support_seat.refused).
Parameters
user_idstringpathrequiredmembers[].user_id).Code samples
cURL
curl -X PUT "https://api.gaiadesk.net/v1/support/seats/{user_id}" \
-H "Authorization: Bearer $GAIADESK_API_KEY"TypeScript
Python
Go
PHP
Ruby
Java
Responses
Example
{
"user_id": 0,
"email": "string",
"name": "string",
"role": "string",
"assigned": true,
"seated": true,
"owner_seat": true,
"assigned_at": 0,
"assigned_by": "string"
}Schema
user_idintegerrequiredemailstringrequirednamestringrequiredrolestringrequiredowner, admin, member).assignedbooleanrequiredseatedbooleanrequiredowner_seatbooleanrequiredassigned_atintegerrequiredassigned_bystringrequiredowner for the owner's seat; system:support-seats when it was given automatically at set-up.X-Request-Idstringreq_…), also in every error body. Quote it to support.refused, unauthenticated).Same as 401 · GET /support/seats
refused).Same as 401 · GET /support/seats
unreachable, unknown_desk).Same as 401 · GET /support/seats
refused, support_seats_exhausted).Same as 401 · GET /support/seats
refused, rate_limited).Same as 401 · GET /support/seats
Retry-AfterintegerRateLimit-LimitintegerRateLimit-RemainingintegerRateLimit-Resetintegerhttps://api.gaiadesk.net/v1 /support/seats/{user_id} Scope supportTake a team member's support seat back (team owners and admins).
Idempotent. A support session the member is in now runs on; their next join is refused. The owner's seat is never removed (403 owner_seat). Audited (support_seat.removed).
Parameters
user_idstringpathrequiredmembers[].user_id).Code samples
cURL
curl -X DELETE "https://api.gaiadesk.net/v1/support/seats/{user_id}" \
-H "Authorization: Bearer $GAIADESK_API_KEY"TypeScript
Python
Go
PHP
Ruby
Java
Responses
Same as 200 · PUT /support/seats/{user_id}
X-Request-Idstringreq_…), also in every error body. Quote it to support.refused, unauthenticated).Same as 401 · GET /support/seats
refused).Same as 401 · GET /support/seats
unreachable, unknown_desk).Same as 401 · GET /support/seats
refused, rate_limited).Same as 401 · GET /support/seats
Retry-AfterintegerRateLimit-LimitintegerRateLimit-RemainingintegerRateLimit-Resetinteger