mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-07 07:55:16 +02:00
docs: add developer and api reference tabs (#190)
* docs: add developer and api reference tabs * fix: remove duplicate image
This commit is contained in:
Sabiha Khan
GitHub
parent
1b03191cf8
commit
f075bcb623
57 changed files with 1609 additions and 57 deletions
144
docs/developer/environment-variables.mdx
Normal file
144
docs/developer/environment-variables.mdx
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
---
|
||||
title: "Environment Variables"
|
||||
description: "Complete reference for all environment variables used by the Dograh backend"
|
||||
---
|
||||
|
||||
Core environment variables are centralized in `api/constants.py`. Variables marked **Required** in the description must be explicitly set — the application will either fail to boot or behave insecurely without them.
|
||||
|
||||
## Deployment Modes
|
||||
|
||||
Dograh supports two deployment modes, set via `DEPLOYMENT_MODE`:
|
||||
|
||||
- **OSS**: The default mode. Designed for self-hosted deployments using [Docker Compose](/deployment/docker) — the fastest way to get Dograh running. Uses local JWT authentication and MinIO for storage.
|
||||
- **SaaS**: Intended for customised deployments outside of Docker. Authentication and API key management are handled through Dograh Managed Platform Services (MPS), allowing greater flexibility in how the platform is hosted and integrated.
|
||||
|
||||
The relevant required variables for each mode are noted in the descriptions below.
|
||||
|
||||
---
|
||||
|
||||
## Application
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `ENVIRONMENT` | `local` | Runtime environment. Affects logging and behaviour. One of `local`, `production`, `test` |
|
||||
| `DEPLOYMENT_MODE` | `oss` | Deployment mode. Use `oss` for self-hosted |
|
||||
| `AUTH_PROVIDER` | `local` | Authentication provider. Use `local` for OSS |
|
||||
| `ENABLE_TRACING` | `false` | Enable distributed tracing via [Langfuse](/configurations/tracing) |
|
||||
|
||||
---
|
||||
|
||||
## Database
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `DATABASE_URL` | N/A | **Required.** PostgreSQL connection string. e.g. `postgresql+asyncpg://user:pass@host:5432/dbname` |
|
||||
| `REDIS_URL` | N/A | **Required.** Redis connection string. e.g. `redis://localhost:6379` |
|
||||
|
||||
---
|
||||
|
||||
## Authentication (OSS)
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `OSS_JWT_SECRET` | N/A | **Required for OSS deployments.** Secret used to sign JWT tokens. Must be set to a strong random value in production |
|
||||
| `OSS_JWT_EXPIRY_HOURS` | `720` | JWT token lifetime in hours (default: 30 days) |
|
||||
|
||||
<Warning>
|
||||
Never use the placeholder `OSS_JWT_SECRET` in a production deployment. Generate a strong random secret and store it securely.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## URLs
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `BACKEND_API_ENDPOINT` | `http://localhost:8000` | Internal URL of the backend API |
|
||||
| `UI_APP_URL` | `http://localhost:3010` | URL of the frontend application |
|
||||
| `MPS_API_URL` | `https://services.dograh.com` | Dograh Managed Platform Services URL |
|
||||
| `DOGRAH_MPS_SECRET_KEY` | `null` | **Required for non-OSS deployments.** Secret key for authenticating with MPS |
|
||||
|
||||
---
|
||||
|
||||
## Storage
|
||||
|
||||
Dograh uses **MinIO by default**, which is bundled with the self-hosted deployment and requires no external setup. Set `ENABLE_AWS_S3=true` to switch to AWS S3 — typically used for cloud or managed deployments where S3 is already part of the infrastructure.
|
||||
|
||||
### MinIO (OSS default)
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `MINIO_ENDPOINT` | `localhost:9000` | MinIO server host and port |
|
||||
| `MINIO_PUBLIC_ENDPOINT` | `null` | Publicly accessible MinIO URL (for download links) |
|
||||
| `MINIO_ACCESS_KEY` | N/A | **Required for OSS deployments.** MinIO access key. Must be set to a secure value in production |
|
||||
| `MINIO_SECRET_KEY` | N/A | **Required for OSS deployments.** MinIO secret key. Must be set to a secure value in production |
|
||||
| `MINIO_BUCKET` | `voice-audio` | Bucket name for audio files |
|
||||
| `MINIO_SECURE` | `false` | Use HTTPS for MinIO connections |
|
||||
|
||||
### AWS S3 (alternative)
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `ENABLE_AWS_S3` | `false` | Set to `true` to use AWS S3 instead of MinIO |
|
||||
| `S3_BUCKET` | `null` | S3 bucket name |
|
||||
| `S3_REGION` | `us-east-1` | AWS region |
|
||||
|
||||
---
|
||||
|
||||
## WebRTC
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `TURN_HOST` | `localhost` | TURN server hostname for WebRTC NAT traversal |
|
||||
| `TURN_PORT` | `3478` | TURN server port |
|
||||
| `TURN_TLS_PORT` | `5349` | TURN server TLS port |
|
||||
| `TURN_SECRET` | `null` | **Required for WebRTC.** Shared secret for TURN credential generation |
|
||||
| `TURN_CREDENTIAL_TTL` | `86400` | TURN credential validity in seconds (default: 24h) |
|
||||
|
||||
---
|
||||
|
||||
## Tracing (Langfuse)
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `LANGFUSE_HOST` | `null` | Langfuse server URL |
|
||||
| `LANGFUSE_PUBLIC_KEY` | `null` | Langfuse public key |
|
||||
| `LANGFUSE_SECRET_KEY` | `null` | Langfuse secret key |
|
||||
|
||||
Set `ENABLE_TRACING=true` alongside these to activate LLM call tracing. See the [Tracing guide](/configurations/tracing) for setup instructions.
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `SENTRY_DSN` | `null` | Sentry DSN for error tracking |
|
||||
| `ENABLE_TELEMETRY` | `false` | Enable anonymous telemetry collection |
|
||||
|
||||
---
|
||||
|
||||
## Logging
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `LOG_LEVEL` | `DEBUG` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
|
||||
| `LOG_FILE_PATH` | `null` | Write logs to this file path (in addition to stdout) |
|
||||
| `LOG_ROTATION_SIZE` | `100 MB` | Rotate log file when it reaches this size |
|
||||
| `LOG_RETENTION` | `7 days` | How long to keep rotated log files |
|
||||
| `LOG_COMPRESSION` | `gz` | Compression format for rotated logs |
|
||||
| `SERIALIZE_LOG_OUTPUT` | `false` | Output logs as JSON (useful for log aggregation) |
|
||||
|
||||
---
|
||||
|
||||
## Campaigns
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `DEFAULT_ORG_CONCURRENCY_LIMIT` | `2` | Maximum concurrent outbound calls per organization |
|
||||
|
||||
---
|
||||
|
||||
## Further Customisation
|
||||
|
||||
The variables documented here cover the standard configuration surface. For advanced customisation — such as integrating additional services or tuning internal behaviour — consult the relevant module alongside `api/constants.py` to understand how each variable is consumed.
|
||||
110
docs/developer/webhooks.mdx
Normal file
110
docs/developer/webhooks.mdx
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
title: "Webhook Payloads"
|
||||
description: "Context variables available in webhook nodes and the data Dograh sends after a call"
|
||||
---
|
||||
|
||||
Dograh executes **webhook nodes** asynchronously after a workflow run completes. You configure the target URL, HTTP method, headers, and payload template directly in the workflow definition.
|
||||
|
||||
---
|
||||
|
||||
## How webhooks work
|
||||
|
||||
1. A call completes (or a run finishes)
|
||||
2. Dograh executes any `webhook` nodes in the workflow asynchronously
|
||||
3. The payload template is rendered with the run's context and sent as a JSON `POST` (or your configured method) to your endpoint
|
||||
4. Non-200 responses are logged but do not block or retry by default (configure `retry_config` to change this)
|
||||
|
||||
---
|
||||
|
||||
## Payload context variables
|
||||
|
||||
The following variables are available in your `payload_template` using double-brace syntax (e.g. `{{workflow_run_id}}`):
|
||||
|
||||
| Variable | Type | Description |
|
||||
|---|---|---|
|
||||
| `workflow_run_id` | integer | ID of the completed run |
|
||||
| `workflow_run_name` | string | Name of the run |
|
||||
| `workflow_id` | integer | ID of the workflow |
|
||||
| `workflow_name` | string | Name of the workflow |
|
||||
| `initial_context` | object | Context passed when the call was initiated |
|
||||
| `gathered_context` | object | Data extracted during the call by agent nodes |
|
||||
| `cost_info` | object | Call cost breakdown |
|
||||
| `annotations` | object | QA analysis results (if a `qa` node is configured) |
|
||||
| `recording_url` | string \| null | Public download URL for the call recording |
|
||||
| `transcript_url` | string \| null | Public download URL for the call transcript |
|
||||
|
||||
### Example payload template
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "{{workflow_run_id}}",
|
||||
"customer": "{{initial_context.customer_name}}",
|
||||
"outcome": "{{gathered_context.resolution}}",
|
||||
"recording": "{{recording_url}}"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
Webhook requests support the following authentication methods, configured via a stored credential:
|
||||
|
||||
| Type | Description |
|
||||
|---|---|
|
||||
| `NONE` | No authentication |
|
||||
| `API_KEY` | Sends the key in a custom header (e.g. `X-API-Key`) |
|
||||
| `BEARER_TOKEN` | Sends `Authorization: Bearer <token>` |
|
||||
| `BASIC_AUTH` | HTTP Basic authentication (username + password) |
|
||||
| `CUSTOM_HEADER` | Any custom header key-value pair |
|
||||
|
||||
---
|
||||
|
||||
## Receiving webhooks
|
||||
|
||||
Your endpoint should:
|
||||
|
||||
- Accept `POST` requests with `Content-Type: application/json`
|
||||
- Respond with a `2xx` status code promptly (within 30 seconds)
|
||||
- Handle duplicate deliveries idempotently (retries may deliver the same payload more than once)
|
||||
|
||||
### Minimal example receiver (Python)
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI, Request
|
||||
|
||||
app = FastAPI()
|
||||
|
||||
@app.post("/webhook/dograh")
|
||||
async def handle_dograh_webhook(request: Request):
|
||||
payload = await request.json()
|
||||
run_id = payload.get("run_id")
|
||||
outcome = payload.get("outcome")
|
||||
# process the call result...
|
||||
return {"status": "ok"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Webhook node in a workflow definition
|
||||
|
||||
See [Workflow Definition Schema](/developer/workflow-schema#webhook-node) for the full configuration reference.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "webhook-1",
|
||||
"type": "webhook",
|
||||
"position": { "x": 600, "y": 0 },
|
||||
"data": {
|
||||
"name": "Notify CRM",
|
||||
"enabled": true,
|
||||
"http_method": "POST",
|
||||
"endpoint_url": "https://your-service.com/webhook/dograh",
|
||||
"payload_template": {
|
||||
"run_id": "{{workflow_run_id}}",
|
||||
"customer": "{{initial_context.customer_name}}",
|
||||
"outcome": "{{gathered_context.resolution}}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
197
docs/developer/workflow-schema.mdx
Normal file
197
docs/developer/workflow-schema.mdx
Normal file
|
|
@ -0,0 +1,197 @@
|
|||
---
|
||||
title: "Workflow Definition Schema"
|
||||
description: "Schema reference for the workflow_definition object used in the Agents API"
|
||||
---
|
||||
|
||||
The `workflow_definition` object passed to [Create from Definition](/api-reference/agents/create-from-definition) and [Update Agent](/api-reference/agents/update) defines the full conversation graph. It is the same structure the dashboard's visual workflow builder reads and writes — building an agent in the UI produces a `workflow_definition` under the hood, and anything you can configure visually can equally be expressed here as JSON.
|
||||
|
||||
```json
|
||||
{
|
||||
"nodes": [...],
|
||||
"edges": [...]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Nodes
|
||||
|
||||
Each node represents a step in the conversation.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid-string",
|
||||
"type": "agentNode",
|
||||
"position": { "x": 100, "y": 200 },
|
||||
"data": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `id` | string | Unique node ID (UUID recommended) |
|
||||
| `type` | string | One of the node types below |
|
||||
| `position` | object | Visual coordinates in the workflow builder |
|
||||
| `data` | object | Node configuration — fields vary by type |
|
||||
|
||||
### Node types
|
||||
|
||||
| Type | Description |
|
||||
|---|---|
|
||||
| `startCall` | Entry point for telephony calls |
|
||||
| `endCall` | Terminates the call |
|
||||
| `agentNode` | LLM-powered conversation step |
|
||||
| `globalNode` | Global configuration applied across all agent nodes |
|
||||
| `trigger` | Entry point for API-triggered (non-telephony) runs |
|
||||
| `webhook` | Sends an HTTP request when reached |
|
||||
| `qa` | Runs quality analysis on the completed call |
|
||||
|
||||
---
|
||||
|
||||
## Node data fields
|
||||
|
||||
### Common fields (all node types)
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `name` | string | required | Display name for the node |
|
||||
| `prompt` | string | required* | LLM system prompt. *Not required for `trigger`, `webhook`, `qa` nodes |
|
||||
| `allow_interrupt` | boolean | `false` | Allow the caller to interrupt the agent mid-speech |
|
||||
| `wait_for_user_response` | boolean | `false` | Pause and wait for caller input before continuing |
|
||||
| `wait_for_user_response_timeout` | number | `null` | Seconds to wait for input before timing out |
|
||||
| `detect_voicemail` | boolean | `false` | Detect and handle voicemail on outbound calls |
|
||||
| `delayed_start` | boolean | `false` | Delay execution of this node |
|
||||
| `delayed_start_duration` | number | `null` | Delay in seconds |
|
||||
| `add_global_prompt` | boolean | `true` | Merge the `globalNode` prompt into this node's prompt |
|
||||
|
||||
### agentNode — data extraction
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `extraction_enabled` | boolean | `false` | Extract structured data from the conversation |
|
||||
| `extraction_prompt` | string | `null` | Custom prompt to guide extraction |
|
||||
| `extraction_variables` | array | `[]` | Variables to extract (see below) |
|
||||
|
||||
**Extraction variable schema:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "customer_intent",
|
||||
"type": "string",
|
||||
"prompt": "What did the customer want to achieve?"
|
||||
}
|
||||
```
|
||||
|
||||
`type` is one of `string`, `number`, or `boolean`.
|
||||
|
||||
### agentNode — tools
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `tool_uuids` | string[] | IDs of tools (HTTP API, call transfer, etc.) to attach to this node |
|
||||
| `document_uuids` | string[] | IDs of knowledge base documents available to this node |
|
||||
|
||||
### trigger node
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `trigger_path` | string | Unique UUID that becomes the API trigger endpoint path |
|
||||
|
||||
### webhook node
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `enabled` | boolean | `true` | Whether this webhook fires when reached |
|
||||
| `http_method` | string | — | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` |
|
||||
| `endpoint_url` | string | — | Target URL |
|
||||
| `credential_uuid` | string | `null` | UUID of a stored auth credential |
|
||||
| `custom_headers` | array | `[]` | Additional request headers `[{"key": "...", "value": "..."}]` |
|
||||
| `payload_template` | object | `null` | Request body template (supports context variables) |
|
||||
|
||||
### qa node
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `qa_enabled` | boolean | `true` | Enable QA analysis |
|
||||
| `qa_system_prompt` | string | `null` | Custom evaluation prompt |
|
||||
| `qa_model` | string | `null` | LLM model to use for evaluation |
|
||||
| `qa_min_call_duration` | integer | `15` | Minimum call duration in seconds to run QA |
|
||||
| `qa_voicemail_calls` | boolean | `false` | Include voicemail calls in QA |
|
||||
| `qa_sample_rate` | integer | `100` | Percentage of calls to analyse (1–100) |
|
||||
|
||||
---
|
||||
|
||||
## Edges
|
||||
|
||||
Each edge connects two nodes and defines when the transition fires.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "edge-uuid",
|
||||
"source": "node-uuid-a",
|
||||
"target": "node-uuid-b",
|
||||
"data": {
|
||||
"label": "Customer confirms",
|
||||
"condition": "The customer has confirmed their appointment",
|
||||
"transition_speech": "Great, I've got that noted."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `id` | string | Unique edge ID |
|
||||
| `source` | string | ID of the originating node |
|
||||
| `target` | string | ID of the destination node |
|
||||
| `data.label` | string | Short label shown in the workflow builder |
|
||||
| `data.condition` | string | Natural language condition the LLM evaluates to trigger this edge |
|
||||
| `data.transition_speech` | string | Optional speech the agent says before transitioning |
|
||||
|
||||
---
|
||||
|
||||
## Validation rules
|
||||
|
||||
- All `source` and `target` IDs in edges must reference existing node IDs
|
||||
- All nodes except `trigger`, `webhook`, and `qa` must have a non-empty `prompt`
|
||||
- Node IDs must be unique within the workflow
|
||||
- Each workflow must have exactly one `startCall` or `trigger` node as the entry point
|
||||
|
||||
---
|
||||
|
||||
## Minimal example
|
||||
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"id": "start-1",
|
||||
"type": "startCall",
|
||||
"position": { "x": 0, "y": 0 },
|
||||
"data": {
|
||||
"name": "Start",
|
||||
"prompt": "You are a friendly assistant. Greet the caller and ask how you can help."
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "end-1",
|
||||
"type": "endCall",
|
||||
"position": { "x": 400, "y": 0 },
|
||||
"data": {
|
||||
"name": "End",
|
||||
"prompt": "Thank the caller and say goodbye."
|
||||
}
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"id": "edge-1",
|
||||
"source": "start-1",
|
||||
"target": "end-1",
|
||||
"data": {
|
||||
"label": "Done",
|
||||
"condition": "The caller's question has been answered and they want to end the call"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue