Skip to main content
A session connects one computer to your org. You create it with POST /v1/sessions, send its invite_url to the customer, and once their computer is connected you run tasks on it. Think of it as a call: it has one other party, a status, and a history of what happened.

​
Codes

Each session has a pairing code such as K7QM-24XP: two groups of four characters from A–Z and 2–9. The code is the session’s id: session_id and code are the same value, and it goes in URL paths like /v1/sessions/K7QM-24XP. Codes are not case-sensitive, and the dash is optional. A code is a short-lived invitation, not a secret credential for your API: everything in /v1 still needs your API key. Treat the invite link like any support link you send a customer.

​
Statuses

expires_at is when the code will expire if nothing else happens. It is null while the computer is connected, and moves forward with each use (last_active_at). paired_at is when a computer first connected. To know when the computer connects, poll GET /v1/sessions/{session_id} or subscribe to the session.connected and session.disconnected webhooks.

​
One computer per code

The first computer that connects with a code owns it. Another computer trying the same code is refused with “This code is already paired with another device.” The same computer can reconnect as often as it needs to, for example after a restart. To help a second computer, create a second session. When connected, device describes the computer:
os is mac, windows, linux or unknown. The desktop app runs on macOS and Windows.

​
What the customer sees

  1. The invite page. Your agent’s greeting, then a guided download and install for their operating system. The page knows when the app on their computer has the code filled in.
  2. Permissions (macOS only). macOS needs Accessibility and Screen Recording for GuidingHand. The app shows exactly which switches to turn on in System Settings. Windows needs no extra permissions.
  3. Connect. The invite link can fill in the code, but connecting always takes the customer’s own click.
  4. While a task runs. An always-on-top banner with a Stop button, and the agent’s own red pointer moving on their screen so they can see what it is doing. Unless the agent turns them off, the banner also shows the agent’s thoughts and steps as it works, and its questions and approval requests, which the customer can answer or decide right there. See what the customer sees and answers.
The customer can stop the agent at any time:
  • the Stop button on the banner, or
  • the shortcut ⌘ ⇧ Esc on macOS, Ctrl Alt Shift S on Windows.
The task then ends with status stopped and a stopped event whose message is “Stopped by the person at the computer.” Plan for this: the customer is always in control, and a stopped task is a normal outcome, not an error. The customer never needs a GuidingHand account.

​
Metadata

metadata is your own key-value data (for example a ticket or customer id), returned as given on the session and in webhooks. Up to 50 keys; keys up to 40 characters; values must be strings up to 500 characters.

​
Listing and deleting

  • GET /v1/sessions lists sessions newest first, optionally filtered by agent_id. Each has task_count and latest_task_id. See pagination.
  • DELETE /v1/sessions/{session_id} disconnects the computer, stops a running task, and deletes the session’s tasks, events and recordings for good. It needs the admin role or an API key.
Deleting a session can’t be undone. Its tasks, events and recordings are gone, including their replays in the console.