support

Embed
Preview of the card
<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>
GEThttps://api.gaiadesk.net/v1/support/sessionsScope support

The support sessions of the caller's account and team, newest first (the console's queue).

Open sessions by default (state=open: waiting for an agent, or being helped); state=all adds ended and expired ones. customer_present says whether the customer's tab holds its connection right now, and desk_id is then the id an agent's console dials with join_code. Not for publishable keys.

Parameters

statestringquery
open | all
limitintegerquery
At most this many (default 50, at most 200).

Code samples

cURL
curl -X GET "https://api.gaiadesk.net/v1/support/sessions" \
  -H "Authorization: Bearer $GAIADESK_API_KEY"
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 The sessions.
Example
{
  "sessions": [
    {
      "id": "string",
      "state": "waiting",
      "mode": "view",
      "customer": {},
      "customer_present": true,
      "customer_verified": true,
      "join_code": "string",
      "join_url": "string",
      "desk_id": "string",
      "origin": "string",
      "owner": "string",
      "created_at": 0,
      "expires_at": 0,
      "joined_at": 0,
      "joined_by": "string",
      "ended_at": 0,
      "end_reason": "string"
    }
  ]
}
Schema
sessionsApiSupportSession[]required
Show child parameters
idstringrequired
statestringrequired
waiting (no agent has joined yet), joined, ended (stopped by the customer, or their tab went away), expired.
waiting | joined | ended | expired
modestringrequired
view: the agent sees the shared tab. cobrowse: the agent may also point, highlight, click, scroll and type INSIDE the page (applied by the embed to its own DOM, never as OS input; the customer sees it and can stop it).
view | cobrowse
customerobjectrequired
Who the customer is, as the company knows them. At most 16 fields; names are 1 to 40 letters, digits, _, - or .; values are strings of at most 200 plain characters, numbers or booleans; at most 2 KB in all. Shown to the company's own agents and webhooks only, and never written to the audit trail (only the field names are).
customer_presentbooleanrequired
The customer's tab holds its connection right now.
customer_verifiedbooleanrequired
false when a publishable key (the page itself) created the session: its customer is what the page said.
join_codestringrequired
The nine digits an agent joins with (the tab checks it).
join_urlstringrequired
The console page that joins this session.
desk_idstring
While the customer is present, the id the console dials.
originstring
The page origin the embed must run on, if pinned.
ownerstringrequired
The account that created it; its own and its team's agents see it.
created_atintegerrequired
expires_atintegerrequired
joined_atinteger
joined_bystring
The last agent who joined.
ended_atinteger
end_reasonstring
stopped (the customer pressed Stop), disconnected (their tab went away), expired.
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
400 The request is malformed (usage).
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 & objectrequired
The CLI's error object plus this request's id.
Show child parameters
deskstring
The desk it concerned, when there was one.
kindstringrequired
The six kinds a program branches on. Stable: a new kind would be a breaking change, so match with a wildcard arm anyway.
messagestringrequired
reasonstring
The finer cause: offline, unknown_desk, not_online, network, not_signed_in, timeout, local, …
request_idstringrequired
statusinteger
Only in a held body (GaiaDesk-Held) — the HTTP status this failure would have had, had its 200 not been sent already.
e2eobject
An end-to-end encrypted operation's events; the last opens to the desk's real error (its message here is a placeholder).
Show child parameters
vintegerrequired
eventsApiE2eFrame[]required
Show child parameters
seqintegerrequired
noncestringrequired
ciphertextstringrequired
401 No credential, or one that does not verify (refused, unauthenticated).

Same as 400 · GET /support/sessions

403 The credential lacks the scope, or may not use this API (refused).

Same as 400 · GET /support/sessions

429 Over this key's rate limit (refused, rate_limited).

Same as 400 · GET /support/sessions

Headers
Retry-Afterinteger
Seconds to wait before trying again.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
POSThttps://api.gaiadesk.net/v1/support/sessionsScope support

Create a support session for the web embed SDK; returns its join code, join URL and embed token.

The company's backend (an API key with support), a signed-in person, or the embed itself with a PUBLISHABLE key creates a session. The answer's embed_token (gdemb_…, shown once) is what the customer's page hands GaiaDeskEmbed.start({ embedToken }); the page then shares its tab and waits. The company's support team (the owner's account and team) sees it in the console (GET /support/sessions) and joins with join_code.

A publishable key may call this operation and nothing else, only from one of the page origins registered on it (Origin), and its answer is readable by that origin alone. Its session is pinned to that origin, lives at most an hour, and its customer is marked unverified (customer_verified: false): the page, not the company, said who it is. A publishable key holds at most 25 open sessions and creates at most 10 a minute.

Parameters

Idempotency-Keystringheader
Up to 255 printable ASCII characters. A retry with the same key and the same request within 24 hours gets the first answer again (Idempotent-Replayed: true); the same key with a different request is refused (usage, idempotency_key_reused).

Request body

application/json
modestring
view: the agent sees the shared tab. cobrowse: the agent may also point, highlight, click, scroll and type INSIDE the page (applied by the embed to its own DOM, never as OS input; the customer sees it and can stop it).
view | cobrowse
customerobject
Who the customer is, as the company knows them. At most 16 fields; names are 1 to 40 letters, digits, _, - or .; values are strings of at most 200 plain characters, numbers or booleans; at most 2 KB in all. Shown to the company's own agents and webhooks only, and never written to the audit trail (only the field names are).
expires_ininteger
Seconds until the session ends (default 3600; at most 86400, or 3600 from a publishable key). A session still running then is ended.
originstring
The page origin the embed will run on (https://app.example.com; http:// only for localhost). When given, the embed's connection must come from it. Not with a publishable key, whose session is pinned to the page that created it.
{
  "mode": "view",
  "customer": {},
  "expires_in": 0,
  "origin": "string"
}

Code samples

cURL
curl -X POST "https://api.gaiadesk.net/v1/support/sessions" \
  -H "Authorization: Bearer $GAIADESK_API_KEY" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/json" \
  -d '{"mode":"view","customer":{},"expires_in":0,"origin":"string"}'
TypeScript
Python
Go
PHP
Ruby
Java

Responses

201 Created. Keep embed_token for the page; it is never shown again.
Example
{
  "id": "string",
  "state": "waiting",
  "mode": "view",
  "customer": {},
  "customer_present": true,
  "customer_verified": true,
  "join_code": "string",
  "join_url": "string",
  "desk_id": "string",
  "origin": "string",
  "owner": "string",
  "created_at": 0,
  "expires_at": 0,
  "joined_at": 0,
  "joined_by": "string",
  "ended_at": 0,
  "end_reason": "string",
  "embed_token": "string"
}
Schema
idstringrequired
statestringrequired
waiting (no agent has joined yet), joined, ended (stopped by the customer, or their tab went away), expired.
waiting | joined | ended | expired
modestringrequired
view: the agent sees the shared tab. cobrowse: the agent may also point, highlight, click, scroll and type INSIDE the page (applied by the embed to its own DOM, never as OS input; the customer sees it and can stop it).
view | cobrowse
customerobjectrequired
Who the customer is, as the company knows them. At most 16 fields; names are 1 to 40 letters, digits, _, - or .; values are strings of at most 200 plain characters, numbers or booleans; at most 2 KB in all. Shown to the company's own agents and webhooks only, and never written to the audit trail (only the field names are).
customer_presentbooleanrequired
The customer's tab holds its connection right now.
customer_verifiedbooleanrequired
false when a publishable key (the page itself) created the session: its customer is what the page said.
join_codestringrequired
The nine digits an agent joins with (the tab checks it).
join_urlstringrequired
The console page that joins this session.
desk_idstring
While the customer is present, the id the console dials.
originstring
The page origin the embed must run on, if pinned.
ownerstringrequired
The account that created it; its own and its team's agents see it.
created_atintegerrequired
expires_atintegerrequired
joined_atinteger
joined_bystring
The last agent who joined.
ended_atinteger
end_reasonstring
stopped (the customer pressed Stop), disconnected (their tab went away), expired.
embed_tokenstringrequired
The page's one credential for this session (GaiaDeskEmbed.start({ embedToken })). Shown once; good only for this session, until it ends.
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
Idempotent-Replayedstring
true when this answer is a stored one, replayed for a repeated Idempotency-Key.
400 The request is malformed (usage).

Same as 400 · GET /support/sessions

401 No credential, or one that does not verify (refused, unauthenticated).

Same as 400 · GET /support/sessions

403 The credential lacks the scope, or may not use this API (refused).

Same as 400 · GET /support/sessions

429 Over this key's rate limit (refused, rate_limited).

Same as 400 · GET /support/sessions

Headers
Retry-Afterinteger
Seconds to wait before trying again.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
GEThttps://api.gaiadesk.net/v1/support/sessions/{session_id}Scope support

A support session's state.

A session owned by the caller's account or a team mate's; any other id answers 404 unknown_support_session. Not for publishable keys.

Parameters

session_idstringpathrequired

Code samples

cURL
curl -X GET "https://api.gaiadesk.net/v1/support/sessions/{session_id}" \
  -H "Authorization: Bearer $GAIADESK_API_KEY"
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 The session.
Example
{
  "id": "string",
  "state": "waiting",
  "mode": "view",
  "customer": {},
  "customer_present": true,
  "customer_verified": true,
  "join_code": "string",
  "join_url": "string",
  "desk_id": "string",
  "origin": "string",
  "owner": "string",
  "created_at": 0,
  "expires_at": 0,
  "joined_at": 0,
  "joined_by": "string",
  "ended_at": 0,
  "end_reason": "string"
}
Schema
idstringrequired
statestringrequired
waiting (no agent has joined yet), joined, ended (stopped by the customer, or their tab went away), expired.
waiting | joined | ended | expired
modestringrequired
view: the agent sees the shared tab. cobrowse: the agent may also point, highlight, click, scroll and type INSIDE the page (applied by the embed to its own DOM, never as OS input; the customer sees it and can stop it).
view | cobrowse
customerobjectrequired
Who the customer is, as the company knows them. At most 16 fields; names are 1 to 40 letters, digits, _, - or .; values are strings of at most 200 plain characters, numbers or booleans; at most 2 KB in all. Shown to the company's own agents and webhooks only, and never written to the audit trail (only the field names are).
customer_presentbooleanrequired
The customer's tab holds its connection right now.
customer_verifiedbooleanrequired
false when a publishable key (the page itself) created the session: its customer is what the page said.
join_codestringrequired
The nine digits an agent joins with (the tab checks it).
join_urlstringrequired
The console page that joins this session.
desk_idstring
While the customer is present, the id the console dials.
originstring
The page origin the embed must run on, if pinned.
ownerstringrequired
The account that created it; its own and its team's agents see it.
created_atintegerrequired
expires_atintegerrequired
joined_atinteger
joined_bystring
The last agent who joined.
ended_atinteger
end_reasonstring
stopped (the customer pressed Stop), disconnected (their tab went away), expired.
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
401 No credential, or one that does not verify (refused, unauthenticated).

Same as 400 · GET /support/sessions

403 The credential lacks the scope, or may not use this API (refused).

Same as 400 · GET /support/sessions

404 No such desk or resource visible to the caller (unreachable, unknown_desk).

Same as 400 · GET /support/sessions

429 Over this key's rate limit (refused, rate_limited).

Same as 400 · GET /support/sessions

Headers
Retry-Afterinteger
Seconds to wait before trying again.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.

Updated