Skip to main content

Adapters

Adapters are the execution layer of the Voxtronics runtime.

While the assistant is responsible for understanding intent, adapters are responsible for performing actions; every external effect in the system, such as transferring a call, sending a webhook, or executing a workflow, is done through an adapter.

Adapters are defined under the [adapters] section and are referenced by name from routers and policies - this makes them reusable and composable across different call flows.

At runtime, the flow is:

  1. The assistant detects an intent
  2. The intent router selects an adapter
  3. The adapter executes the action

This separation keeps reasoning independent from execution.

Basic structure​

Each adapter is defined as a named block:

[adapters.<name>]
type = "<type>"

The type defines how the adapter behaves. The runtime supports four main types:

  • sip: executes SIP commands
  • webhook: performs HTTP requests
  • pipeline: executes a multi-step workflow

SIP adapters​

SIP adapters interact directly with the SIP session and they are used for updating session state.

Example:

[adapters.call_transfer]
command = "ua_session_update"
type = "sip"

[adapters.call_transfer.static_params]
extra_headers = "Refer-To: <sip:${destination}@mypbx.com>"
method = "REFER"

[adapters.hangup]
command = "ua_session_update"
static_params = { method = "BYE" }
type = "sip"

In this example:

  • call_transfer sends a REFER request using a dynamic destination
  • hangup sends a BYE request

Both reuse the same command but differ in parameters.

Webhook adapters​

Webhook adapters integrate the bot with external systems.

[adapters.hook01]
method = "POST"
raise_on_http_error = false
response_mode = "json"
retries = 2
retry_backoff_seconds = 0.5
retry_jitter_seconds = 0.3
retry_max_backoff_seconds = 5
timeout = 5
type = "webhook"
url = "https://mypbx.com/api"

The url is the destination. The method controls the HTTP verb. timeout is the request timeout in seconds. Retry fields control transient failure handling.

Authentication​

Webhook adapters support authentication.

[adapters.webhook_validate.auth]
header = "X-API-Key"
key = "deepgram"
type = "api_key"

Supported authentication types are:

  • bearer
  • basic
  • api_key

Headers and query parameters​

Headers and query parameters can use runtime variables.

[adapters.webhook_validate.headers]
Content-Type = "application/json"
X-Call-ID = "${call_id}"
X-Intent = "${intent}"
X-Tenant = "${tenant_id}"

[adapters.webhook_validate.query_params]
call_id = "${call_id}"
intent = "${intent}"
tenant = "${tenant_id}"

Pipeline adapters​

Pipeline adapters execute ordered steps.

[adapters.multi_webhook_workflow]
type = "pipeline"

[[adapters.multi_webhook_workflow.steps]]
id = "validate_request"
inputs = { payload = "${arguments}" }
outputs = { validation = "$.data" }
service = "validate"

[adapters.multi_webhook_workflow.steps.inputs]
payload = "${arguments}"
process_result = "${process_result}"
validation = "${validation}"

[adapters.multi_webhook_workflow.services]
audit = { adapter = "webhook_audit", type = "adapter" }
process = { adapter = "webhook_process", type = "adapter" }
validate = { adapter = "webhook_validate", type = "adapter" }

A pipeline step can:

  • read the original function arguments
  • call a service
  • extract values from the response
  • pass those values to later steps via variables

How adapters connect to policies​

Policies allow adapters.

[policies.default]
adapters = ["webhook_validate", "webhook_process", "webhook_audit", "multi_webhook_workflow", "call_transfer"]

An adapter must be both routed and allowed by the active policy.