Skip to main content

App Links

App Links let you drop a single link into your own app, dashboard, portal, or email that — when someone clicks it — opens or starts a Gravity Rail chat with a specific target: an AI agent or a live person, in a specific workspace.

The link works whether or not the recipient has the Gravity Rail desktop app: if the app is installed it can take over, otherwise the chat opens in the browser.

App Links never contain patient data. A link only carries the workspace, a member reference, and a few short options — never a name, a phone number, or any message text. See Security below.

Every App Link has the same shape:

https://app.gravityrail.com/link/v1/w/<workspace_uuid>/chat?<options>
  • <workspace_uuid> — the workspace the chat belongs to.
  • <options> — any combination of the four optional parameters below.

Options​

OptionValuesDefaultWhat it does
witha member id or member handle (uuid)—Who to reach: an agent (AI) or an operator/person (human). Leave it off to reach the workspace's AI manager.
modeai or humaninferred from with; otherwise aiReach the AI, or a live human operator.
actionopen or startsmart (resume the most recent matching chat, else start a new one)Force resuming an existing chat, or always start a fresh one.
channelweb or web-voicewebOpen a text chat, or start a browser voice conversation.

Tip — use the handle, not the number. Prefer a member's uuid handle in links you embed publicly (e.g. ?with=6f2c…). It's stable and non-guessable, so you never expose sequential member id numbers.

Examples​

# Start an AI chat with the workspace's manager agent
https://app.gravityrail.com/link/v1/w/748b5a92-.../chat?mode=ai

# Open (or start) a chat with a specific agent, by handle
https://app.gravityrail.com/link/v1/w/748b5a92-.../chat?with=6f2c1e04-...

# Reach a live human operator
https://app.gravityrail.com/link/v1/w/748b5a92-.../chat?mode=human

# Start a browser-voice chat with a specific operator
https://app.gravityrail.com/link/v1/w/748b5a92-.../chat?with=42&channel=web-voice&action=start

What happens when someone clicks​

  1. Sign-in. If they aren't signed in to Gravity Rail, they're taken to the login page and returned to the link afterward. A link never grants access on its own — the person still needs their own Gravity Rail account and permission in that workspace.
  2. The chat opens. Gravity Rail finds the right conversation (or starts a new one) and opens it.
  3. Desktop app (optional). If they have the desktop app installed, an "Open in the desktop app" option lets it take over. If not, everything happens in the browser — no install required.

Security​

App Links are designed for healthcare use and follow strict rules:

  • No PHI in links. A link only ever contains the workspace id, a member id/handle, and the short options above. Never a name, phone number, email, or message text. (For this reason, App Links can't pre-fill a message.)
  • A link is a bookmark, not a key. Clicking a link never grants access. Gravity Rail re-checks the signed-in person's permission in that workspace every time a link is opened.
  • Workspace isolation. A link only resolves members that belong to its named workspace. A member reference from another workspace simply won't be found.

Limitations (v1)​

  • Text chat and browser voice only — App Links don't place phone calls, SMS, or email in this version.
  • with accepts a member id or uuid handle today; friendly, human-readable handles (e.g. with=intake-bot) are coming later.