> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryopencomputer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed an agent on your website

> Configure a public embed token or use the authenticated text-chat API.

Athena has two ways to add text interaction to a site: the generated public widget uses an embed token, while a server-side integration can create text-chat sessions with an API key. Both can start model work and create runs. A token or successful HTTP response does not prove the full browser conversation works, so test the complete flow on a controlled page.

## Configure the public widget

Create and test the agent first. Open its embed settings and create a token with the narrowest allowed website domains that fit your deployment. The token settings can also include widget settings, a usage limit, and an expiration period. A workflow has one active embed token; creating or updating that token changes its public embed configuration.

The current widget integration uses `dograh-widget.js` and `data-dograh-context`; preserve those attribute and script names because they are part of the integration contract. Check the script URL before installing the generated snippet.

> [!WARNING]
>
> The hosted API can currently generate a snippet whose script host is `http://127.0.0.1:3002`. That address only reaches the visitor's own computer, so the widget will not load for your visitors. In the snippet's `js.src` value, replace that origin with `https://athena.tryopencomputer.com`, keeping `/embed/dograh-widget.js`, the token, and the other query parameters. The `apiEndpoint` value must also point to `https://athena.tryopencomputer.com`. This correction has been exercised with the text chat widget; browser voice requires its own microphone and audio check.

**1. Set allowed domains**

Enter the origins where the widget should load. Include the real scheme and host used by your deployed page, and avoid broad wildcards unless you need them.

**2. Install the generated snippet**

Copy the snippet into the page or site template that should show the widget. Do not put an organization API key in browser code.

**3. Test both origin cases**

Open the page on an allowed origin and confirm the widget can initialize. Test a disallowed origin as well to confirm it is rejected.

**4. Exercise a full session**

Send a synthetic message, verify the response, and end the session. For voice, also check microphone permission and two-way audio in the target browser.

The embed-token management API supports `allowed_domains`, `settings`, `usage_limit`, and `expires_in_days`. Deactivate the token when removing access. Rotating or updating it can affect the existing widget configuration, so update the installed snippet or settings as needed.

## Pass visitor context

The widget can send initial context through `data-dograh-context`. Keep the supplied keys aligned with the workflow's prompt and templates. Treat every browser-provided value as untrusted input: do not include secrets or use visitor context as authorization. See [Context and variables](/guides/context.md).

## Use server-managed text sessions

For an integration you control on the server, use the authenticated text-chat API with your numeric `workflow_id`. Send the organization API key only from your backend. The [Text chat sessions and streaming guide](/guides/text-chat.md) covers session creation and recovery, revision checks, POST-based SSE, rewind, and end behavior.

## Public widget streams

The public embed API initializes a session using the embed token, then uses the short-lived session token for visitor messages. Its message stream is designed for the visitor-facing response; do not expect it to expose private tool output or internal workflow errors. Keep any backend-only processing behind your own authenticated service.

For a custom text client that uses the public embed token, the route sequence is:

| Action | Path |
| - | - |
| Read widget configuration | `GET /api/v1/public/embed/config/{token}` |
| Create a session | `POST /api/v1/public/embed/init` or `POST /api/v1/public/embed/init/stream` |
| Read the session | `GET /api/v1/public/embed/chat/{session_token}` |
| Send a message | `POST /api/v1/public/embed/chat/{session_token}/messages` or `POST /api/v1/public/embed/chat/{session_token}/messages/stream` |
| End the session | `POST /api/v1/public/embed/chat/{session_token}/end` |

The public token and session token are for the public embed flow and are not a substitute for a backend API key. Keep their allowed origin restrictions configured, and test the token's actual session path before launch.

Before launch, test token initialization, allowed-origin behavior, a complete chat or voice conversation, and session completion in the browsers your visitors use. After revoking a token, confirm the installed widget can no longer start a session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.