Assistant API

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

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

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

# ── 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:

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

Getting Started

Dashboard (UI)

Web API

Integration API

Endpoint API

Document API

Assistant API — Configuration

Configuration File

Required Variables

Service Identity

PostgreSQL

Redis

OpenSearch (Optional — Knowledge Base Only)

Asset Storage

Telemetry (Optional)

OTLP HTTP

OTLP gRPC

Datadog

AWS X-Ray

Google Trace

Azure Monitor

OpenSearch / Logging

Asterisk AudioSocket

SIP Server

Full Environment File

Local Development Overrides

Next Steps

STT / TTS Providers

Telephony

​Configuration File

​Required Variables

​Service Identity

​PostgreSQL

​Redis

​OpenSearch (Optional — Knowledge Base Only)

​Asset Storage

​Telemetry (Optional)

​OTLP HTTP

​OTLP gRPC

​Datadog

​AWS X-Ray

​Google Trace

​Azure Monitor

​OpenSearch / Logging

​Asterisk AudioSocket

​SIP Server

​Full Environment File

​Local Development Overrides

​Next Steps

STT / TTS Providers

Telephony

Configuration File

Required Variables

Service Identity

PostgreSQL

Redis

OpenSearch (Optional — Knowledge Base Only)

Asset Storage

Telemetry (Optional)

OTLP HTTP

OTLP gRPC

Datadog

AWS X-Ray

Google Trace

Azure Monitor

OpenSearch / Logging

Asterisk AudioSocket

SIP Server

Full Environment File

Local Development Overrides

Next Steps