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

# Assistant API — Configuration

> Complete environment variable reference for the assistant-api service.

## Configuration File

Edit `docker/assistant-api/.assistant.env` before starting the service.

For local development (without Docker), export the variables and override the Docker hostnames shown in the table below.

***

## Required Variables

| Variable | Default | Description |
| - | - | - |
| `SECRET` | `rpd_pks` | JWT signing secret — must be identical across all services |
| `POSTGRES__HOST` | `postgres` | PostgreSQL host |
| `POSTGRES__DB_NAME` | `assistant_db` | Database name |
| `POSTGRES__AUTH__USER` | `rapida_user` | Database user |
| `POSTGRES__AUTH__PASSWORD` | `rapida_db_password` | Database password |
| `REDIS__HOST` | `redis` | Redis host |
| `OPENSEARCH__HOST` | *(empty)* | OpenSearch host — **optional**, leave empty to disable knowledge base |
| `INTEGRATION_HOST` | `integration-api:9004` | integration-api gRPC address |
| `ENDPOINT_HOST` | `endpoint-api:9005` | endpoint-api gRPC address |
| `WEB_HOST` | `web-api:9001` | web-api gRPC address |
| `DOCUMENT_HOST` | *(empty)* | document-api HTTP address — **optional**, only needed for knowledge base |
| `PUBLIC_ASSISTANT_HOST` | — | **Publicly reachable hostname** for telephony callbacks and WebSocket media |

> [!WARNING]
>
> `PUBLIC_ASSISTANT_HOST` must resolve from the public internet. Twilio, Vonage, and Exotel connect WebSocket media streams to `wss://PUBLIC_ASSISTANT_HOST/v1/talk/{provider}/ctx/{contextId}`. For local testing, use an ngrok tunnel and set this to your ngrok hostname (e.g. `abc123.ngrok.io`).

***

## Service Identity

| Variable | Default | Description |
| - | - | - |
| `SERVICE_NAME` | `workflow-api` | Internal service name label |
| `HOST` | `0.0.0.0` | Bind address |
| `PORT` | `9007` | HTTP / gRPC / WebSocket port (cmux) |
| `LOG_LEVEL` | `debug` | `debug` · `info` · `warn` · `error` |
| `ENV` | `development` | `development` · `staging` · `production` |

***

## PostgreSQL

| Variable | Default | Description |
| - | - | - |
| `POSTGRES__HOST` | `postgres` | Host (`localhost` for local dev) |
| `POSTGRES__PORT` | `5432` | Port |
| `POSTGRES__DB_NAME` | `assistant_db` | Database name |
| `POSTGRES__AUTH__USER` | `rapida_user` | User |
| `POSTGRES__AUTH__PASSWORD` | `rapida_db_password` | Password |
| `POSTGRES__MAX_OPEN_CONNECTION` | `50` | Connection pool size |
| `POSTGRES__MAX_IDEAL_CONNECTION` | `25` | Idle connections |
| `POSTGRES__SSL_MODE` | `disable` | `disable` · `require` · `verify-full` |
| `POSTGRES__SLC_CACHE__HOST` | `redis` | Redis host for second-level GORM cache |
| `POSTGRES__SLC_CACHE__PORT` | `6379` | Redis port for GORM cache |
| `POSTGRES__SLC_CACHE__DB` | `1` | Redis DB index for GORM cache |
| `POSTGRES__SLC_CACHE__MAX_CONNECTION` | `10` | Redis pool size |

***

## Redis

| Variable | Default | Description |
| - | - | - |
| `REDIS__HOST` | `redis` | Redis host (`localhost` for local dev) |
| `REDIS__PORT` | `6379` | Redis port |
| `REDIS__MAX_CONNECTION` | `10` | Connection pool size |
| `REDIS__MAX_DB` | `0` | Redis DB index |

***

## OpenSearch (Optional — Knowledge Base Only)

OpenSearch is only needed for knowledge base / RAG features. If `OPENSEARCH__HOST` is left empty (the default), the assistant-api starts without knowledge base support and skips the OpenSearch connection entirely.

| Variable | Default | Description |
| - | - | - |
| `OPENSEARCH__SCHEMA` | `http` | `http` · `https` |
| `OPENSEARCH__HOST` | *(empty)* | OpenSearch host — leave empty to disable knowledge base |
| `OPENSEARCH__PORT` | `9200` | OpenSearch port |
| `OPENSEARCH__MAX_RETRIES` | `3` | Request retry count |
| `OPENSEARCH__MAX_CONNECTION` | `10` | Connection pool size |

***

## Asset Storage

| Variable | Default | Description |
| - | - | - |
| `ASSET_STORE__STORAGE_TYPE` | `local` | `local` · `s3` · `azure` |
| `ASSET_STORE__STORAGE_PATH_PREFIX` | `/app/rapida-data/assets/workflow` | Path for local storage |
| `ASSET_STORE__PUBLIC_URL_PREFIX` | `http://localhost:8080/rapida-data/assets/workflow` | Public URL for serving stored assets |

***

## Telemetry (Optional)

`assistant-api` supports an optional environment-configured default telemetry exporter.

Set exporter type:

| Variable | Default | Description |
| - | - | - |
| `TELEMETRY__TYPE` | *(empty)* | `otlp_http` · `otlp_grpc` · `xray` · `google_trace` · `azure_monitor` · `datadog` · `opensearch` · `logging` |

Provider-specific keys:

### OTLP HTTP

| Variable | Description |
| - | - |
| `TELEMETRY__OTLP_HTTP__ENDPOINT` | OTLP endpoint |
| `TELEMETRY__OTLP_HTTP__PROTOCOL` | `http/protobuf` or `grpc` |
| `TELEMETRY__OTLP_HTTP__HEADERS` | Comma-separated headers (`A=B, C=D`) |
| `TELEMETRY__OTLP_HTTP__INSECURE` | `true`/`false` |

### OTLP gRPC

| Variable | Description |
| - | - |
| `TELEMETRY__OTLP_GRPC__ENDPOINT` | OTLP endpoint |
| `TELEMETRY__OTLP_GRPC__PROTOCOL` | Usually `grpc` |
| `TELEMETRY__OTLP_GRPC__HEADERS` | Comma-separated headers |
| `TELEMETRY__OTLP_GRPC__INSECURE` | `true`/`false` |

### Datadog

| Variable | Description |
| - | - |
| `TELEMETRY__DATADOG__ENDPOINT` | Datadog OTLP/agent endpoint |
| `TELEMETRY__DATADOG__PROTOCOL` | Protocol override |
| `TELEMETRY__DATADOG__HEADERS` | Additional headers |
| `TELEMETRY__DATADOG__API_KEY` | Datadog API key |
| `TELEMETRY__DATADOG__INSECURE` | `true`/`false` |

### AWS X-Ray

| Variable | Description |
| - | - |
| `TELEMETRY__XRAY__ENDPOINT` | ADOT/OTLP endpoint |
| `TELEMETRY__XRAY__PROTOCOL` | Protocol override |
| `TELEMETRY__XRAY__REGION` | AWS region |
| `TELEMETRY__XRAY__INSECURE` | `true`/`false` |

### Google Trace

| Variable | Description |
| - | - |
| `TELEMETRY__GOOGLE_TRACE__ENDPOINT` | Trace endpoint |
| `TELEMETRY__GOOGLE_TRACE__HEADERS` | Additional headers |
| `TELEMETRY__GOOGLE_TRACE__API_KEY` | API key |
| `TELEMETRY__GOOGLE_TRACE__ACCESS_TOKEN` | OAuth bearer token |
| `TELEMETRY__GOOGLE_TRACE__INSECURE` | `true`/`false` |

### Azure Monitor

| Variable | Description |
| - | - |
| `TELEMETRY__AZURE_MONITOR__ENDPOINT` | Azure Monitor endpoint |
| `TELEMETRY__AZURE_MONITOR__HEADERS` | Additional headers |
| `TELEMETRY__AZURE_MONITOR__API_KEY` | API key/instrumentation key |
| `TELEMETRY__AZURE_MONITOR__INSECURE` | `true`/`false` |

### OpenSearch / Logging

| Variable | Description |
| - | - |
| `TELEMETRY__OPENSEARCH__INDEX_PREFIX` | Optional index prefix |
| `TELEMETRY__LOGGING__*` | No options required |

***

## Asterisk AudioSocket

The AudioSocket server binds on a separate TCP port. Asterisk dials into this port directly.

| Variable | Default | Description |
| - | - | - |
| `AUDIOSOCKET__HOST` | `0.0.0.0` | Bind address for the AudioSocket TCP server |
| `AUDIOSOCKET__PORT` | `4573` | TCP port for AudioSocket connections |

**Asterisk dialplan usage:**

```
same = n,AudioSocket(${RAPIDA_CONTEXT_ID},assistant-api-host:4573)
```

***

## SIP Server

The built-in SIP server handles direct SIP INVITE connections and Asterisk SIP trunk connections.

| Variable | Default | Description |
| - | - | - |
| `SIP__SERVER` | `0.0.0.0` | Bind address for SIP |
| `SIP__EXTERNAL_IP` | `0.0.0.0` | **Public IP** advertised in SDP and SIP Contact headers — must be your server's public IP |
| `SIP__PORT` | `5090` | SIP signalling port (UDP) |
| `SIP__TRANSPORT` | `udp` | `udp` · `tcp` |
| `SIP__RTP_PORT_RANGE_START` | `10000` | RTP media port range start |
| `SIP__RTP_PORT_RANGE_END` | `20000` | RTP media port range end |

> [!WARNING]
>
> Set `SIP__EXTERNAL_IP` to your server's public IP address. If this is set to `0.0.0.0`, SDP answers will advertise the wrong address and media will not flow for callers outside the local network.

**SIP connection string:**

```
sip:agent-{assistantID}@{SIP__EXTERNAL_IP}:{SIP__PORT}
sip:did-{did}@{SIP__EXTERNAL_IP}:{SIP__PORT}
sip:{did}@{SIP__EXTERNAL_IP}:{SIP__PORT}
```

***

## Full Environment File

```env theme={null}
# ── Service identity ──────────────────────────────────────────────
SERVICE_NAME=workflow-api
HOST=0.0.0.0
PORT=9007
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

# ── Asset storage ─────────────────────────────────────────────────
ASSET_STORE__STORAGE_TYPE=local
ASSET_STORE__STORAGE_PATH_PREFIX=/app/rapida-data/assets/workflow
ASSET_STORE__PUBLIC_URL_PREFIX=http://localhost:8080/rapida-data/assets/workflow

# ── PostgreSQL ────────────────────────────────────────────────────
POSTGRES__HOST=postgres
POSTGRES__DB_NAME=assistant_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__PORT=5432
POSTGRES__MAX_OPEN_CONNECTION=50
POSTGRES__MAX_IDEAL_CONNECTION=25
POSTGRES__SSL_MODE=disable
POSTGRES__SLC_CACHE__HOST=redis
POSTGRES__SLC_CACHE__PORT=6379
POSTGRES__SLC_CACHE__MAX_CONNECTION=10
POSTGRES__SLC_CACHE__DB=1

# ── Redis ─────────────────────────────────────────────────────────
REDIS__HOST=redis
REDIS__PORT=6379
REDIS__MAX_CONNECTION=10
REDIS__MAX_DB=0

# ── OpenSearch (optional — remove or leave empty to disable knowledge base) ──
# OPENSEARCH__SCHEMA=http
# OPENSEARCH__HOST=opensearch
# OPENSEARCH__PORT=9200
# OPENSEARCH__MAX_RETRIES=3
# OPENSEARCH__MAX_CONNECTION=10

# ── Internal service addresses ────────────────────────────────────
INTEGRATION_HOST=integration-api:9004
ENDPOINT_HOST=endpoint-api:9005
ASSISTANT_HOST=assistant-api:9007
WEB_HOST=web-api:9001
# DOCUMENT_HOST=http://document-api:9010   # optional — only needed for knowledge base
UI_HOST=https://localhost:3000

# ── Public hostname (required for telephony) ──────────────────────
PUBLIC_ASSISTANT_HOST=your-public-hostname.example.com

# ── Asterisk AudioSocket ──────────────────────────────────────────
AUDIOSOCKET__HOST=0.0.0.0
AUDIOSOCKET__PORT=4573

# ── SIP Server ────────────────────────────────────────────────────
SIP__SERVER=0.0.0.0
SIP__EXTERNAL_IP=0.0.0.0
SIP__PORT=5090
SIP__TRANSPORT=udp
SIP__RTP_PORT_RANGE_START=10000
SIP__RTP_PORT_RANGE_END=20000
```

***

## Local Development Overrides

When running from source, override Docker hostnames:

```bash theme={null}
export $(grep -v '^#' docker/assistant-api/.assistant.env | xargs)
export POSTGRES__HOST=localhost
export REDIS__HOST=localhost
export INTEGRATION_HOST=localhost:9004
export ENDPOINT_HOST=localhost:9005
export WEB_HOST=localhost:9001

# Optional: only needed for knowledge base features
# export OPENSEARCH__HOST=localhost
# export DOCUMENT_HOST=http://localhost:9010

go run cmd/assistant/assistant.go
```

***

## Next Steps

> [card] [STT / TTS Providers](https://doc.rapida.ai/opensource/services/assistant-api/stt-tts)
>
> Configure and add speech recognition and synthesis providers.

> [card] [Telephony](https://doc.rapida.ai/opensource/services/assistant-api/telephony)
>
> Twilio, Asterisk, SIP, and other telephony provider setup.


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