You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/osa/api-reference.md
+24-1Lines changed: 24 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -75,12 +75,35 @@ Response:
75
75
"suggested_questions": [
76
76
"What is HED and how is it used?",
77
77
"How do I annotate an event with HED tags?"
78
-
]
78
+
],
79
+
"logo_url": "/hed/logo",
80
+
"theme_color": "#1a365d"
81
+
},
82
+
"links": {
83
+
"homepage": "https://www.hedtags.org",
84
+
"documentation": "https://www.hed-resources.org",
85
+
"repository": "https://github.com/hed-standard"
79
86
}
80
87
}
81
88
]
82
89
```
83
90
91
+
The `logo_url` field is auto-populated when a `logo.*` file exists in the community folder, or can be set explicitly in the YAML config. The `theme_color` field is only present when configured. The `links` field is `null` when no links are configured.
92
+
93
+
This endpoint is public (no authentication required).
94
+
95
+
### Community Logo
96
+
97
+
Serve the community's logo image file.
98
+
99
+
```
100
+
GET /{community}/logo
101
+
```
102
+
103
+
Returns the logo file with appropriate `Content-Type` header. Supported formats: SVG, PNG, JPG, JPEG, WEBP. SVG files include a `Content-Security-Policy` header (`default-src 'none'; style-src 'unsafe-inline'`) to prevent XSS. Responses are cached for 24 hours (`Cache-Control: public, max-age=86400`).
104
+
105
+
Returns `404` if no logo file exists for the community.
106
+
84
107
This endpoint is public (no authentication required).
Copy file name to clipboardExpand all lines: docs/osa/deployment/widget.md
+8-3Lines changed: 8 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ The widget appears as a chat bubble in the bottom-right corner of the page.
21
21
22
22
Widget configuration uses a two-layer approach:
23
23
24
-
1.**YAML defaults** (community-level): Title, greeting, placeholder, and suggested questions are defined in each community's `config.yaml` under the `widget` section. These are served by the `GET /communities` API endpoint.
24
+
1.**YAML defaults** (community-level): Title, greeting, placeholder, suggested questions, theme color, and logo are defined in each community's `config.yaml` under the `widget` section. These are served by the `GET /communities` API endpoint.
25
25
2.**JavaScript overrides** (page-level): Embedders can override any field via `setConfig()`. Any value set in JavaScript takes precedence over the YAML defaults.
26
26
27
27
This means most embedders only need to set `communityId`; the widget fetches its display configuration from the API automatically.
@@ -39,6 +39,8 @@ These fields are typically configured in the community's `config.yaml` and loade
39
39
|`initialMessage`| string | From YAML | First message shown to user |
40
40
|`placeholder`| string | From YAML or `'Ask a question...'`| Input placeholder text |
41
41
|`suggestedQuestions`| string[]| From YAML | Clickable suggestion buttons |
42
+
|`logo`| string | Auto-detected or from YAML | Logo URL for widget header avatar |
43
+
|`themeColor`| string | From YAML or `'#2563eb'`| Primary theme color (hex `#RRGGBB`) |
42
44
43
45
### Behavior Options
44
46
@@ -94,6 +96,8 @@ This is useful when the same community assistant is embedded across multiple pag
94
96
OSAChatWidget.setConfig({
95
97
communityId:'hed',
96
98
title:'HED Assistant',
99
+
logo:'https://example.com/hed-logo.png',
100
+
themeColor:'#1a365d',
97
101
initialMessage:'Hi! I can help with HED annotations. What would you like to know?',
98
102
placeholder:'Ask about HED...',
99
103
suggestedQuestions: [
@@ -184,9 +188,10 @@ The widget communicates with the following backend endpoints:
184
188
|----------|--------|-------------|
185
189
|`/communities`| GET | Fetch available communities and widget config |
186
190
|`/{communityId}/ask`| POST | Send a question, get a response |
191
+
|`/{communityId}/logo`| GET | Serve community logo image (if available) |
187
192
|`/health`| GET | Check backend status |
188
193
189
-
On load, the widget fetches `/communities` to get display configuration (title, greeting, placeholder, suggested questions) for all available communities. This eliminates the need to hardcode these values in JavaScript.
194
+
On load, the widget fetches `/communities` to get display configuration (title, greeting, placeholder, suggested questions, logo, theme color) for all available communities. This eliminates the need to hardcode these values in JavaScript.
190
195
191
196
### Request Format
192
197
@@ -236,7 +241,7 @@ To host the widget yourself:
236
241
The demo page at [osa-demo.pages.dev](https://osa-demo.pages.dev) dynamically loads all available communities from the `/communities` API and showcases them with URL-based routing:
237
242
238
243
-`/` - Landing page with community cards (populated from API)
Each community page auto-configures the widget using the YAML-defined defaults. New communities added to the registry appear on the demo page automatically without frontend changes.
| `theme_color` | string | No | `null` | Primary theme color as hex `#RRGGBB` (e.g., `#008a79`) |
455
+
| `logo_url` | string | No | `null` | URL for custom logo/icon image |
456
+
457
+
### `theme_color`
458
+
459
+
Primary color applied to the widget button, header background, and accent elements. Must be a 6-digit hex color code.
460
+
461
+
```yaml
462
+
widget:
463
+
theme_color: "#008a79" # Teal
464
+
```
465
+
466
+
When not set, the widget uses the platform default blue (`#2563eb`). The widget JS also accepts `themeColor` via `setConfig()` for per-page overrides.
467
+
468
+
### `logo_url`
469
+
470
+
URL to a custom logo or icon image displayed in the widget header avatar (replacing the default brain icon).
471
+
472
+
- Must use `http://`, `https://`, or start with `/` (relative path)
473
+
- Max 500 characters
474
+
475
+
```yaml
476
+
widget:
477
+
logo_url: https://example.com/my-logo.png
478
+
```
479
+
480
+
**Convention-based detection**: If `logo_url` is not set in the YAML, the API automatically checks for a `logo.*` file in the community's folder (`src/assistants/{id}/`). Supported formats: SVG, PNG, JPG, JPEG, WEBP. SVG is preferred over other formats when multiple exist. The file is served via the `GET /{community_id}/logo` endpoint.
2. YAML `widget.logo_url` -- community maintainer sets explicit URL
486
+
3. Convention file -- `logo.png` or `logo.svg` in `src/assistants/{id}/`
487
+
4. Default brain icon (built into the widget)
488
+
489
+
### Example
454
490
455
491
```yaml
456
492
widget:
457
493
title: HED Assistant
494
+
theme_color: "#1a365d"
458
495
initial_message: "Hi! I'm the HED Assistant. I can help with HED annotation, validation, and related tools."
459
496
placeholder: Ask about HED...
460
497
suggested_questions:
@@ -466,14 +503,35 @@ widget:
466
503
467
504
When the widget is embedded on a page, it fetches community defaults from `GET /communities` and applies them automatically. Embedders can still override any field via `setConfig()` in JavaScript; see the [Widget Deployment Guide](../deployment/widget.md).
468
505
469
-
If `widget` is omitted, the widget falls back to generic defaults (title = community name, placeholder = "Ask a question...").
506
+
If `widget` is omitted, the widget falls back to generic defaults (title = community name, placeholder = "Ask a question...", platform blue theme, brain icon).
470
507
471
508
## `enable_page_context`
472
509
473
510
When `true` (default), the assistant includes a `fetch_current_page` tool that retrieves content from the web page where the widget is embedded. This allows the assistant to provide contextually relevant answers based on what the user is currently reading.
474
511
475
512
Set to `false` if the assistant will only be used via CLI or API (not embedded in a web page).
476
513
514
+
## `links`
515
+
516
+
External links for the community, exposed via the `/communities` API endpoint. Only populated links are included in the response.
517
+
518
+
| Field | Type | Required | Default | Description |
0 commit comments