Apply a Self-Hosted state transition | Dial — Communication Stack for AI Agents

curl -X POST https://api.getdial.ai/api/v1/self-hosted \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "action": "save",
  "config": {
    "type": "llm",
    "wsUrl": "string"
  }
}'

{
  "enabled": true,
  "access": "none",
  "activeMode": "llm",
  "accessRequest": {
    "useCase": "string",
    "status": "pending",
    "submittedAt": "2024-01-15T09:30:00Z",
    "companyUrl": "string",
    "reviewedAt": "2024-01-15T09:30:00Z",
    "reviewNote": "string"
  },
  "llm": {
    "type": "llm",
    "wsUrl": "string",
    "urlKey": "string",
    "secretMasked": "string"
  },
  "audio": {
    "type": "audio",
    "wsUrl": "string",
    "secretMasked": "string",
    "audioInboundFormat": "mulaw_8000",
    "audioOutboundFormat": "mulaw_8000"
  }
}

Applies one Self-Hosted state transition, discriminated by action: save a mode’s config (no on/off or active-mode change), activate a mode (enable Self-Hosted and route calls through it — enable or switch), disable, or request_access. Each mode (llm/audio) has its own independent config.

save and activate require access: "granted" and return 403 otherwise; disable and request_access never do, so an account whose access was withdrawn can still switch Self-Hosted off.

The signing secret for a mode is minted the first time you save a wsUrl for it. Retrieve it from GET /api/v1/self-hosted/secret?mode=… and set up your server’s X-Dial-Signature verification before you activate (activating routes your calls at the server immediately). Returns the full configuration after the change.

Applies **one** Self-Hosted state transition, discriminated by `action`: `save` a mode's config (no on/off or active-mode change), `activate` a mode (enable Self-Hosted and route calls through it — enable or switch), `disable`, or `request_access`. Each mode (`llm`/`audio`) has its own independent config. `save` and `activate` require `access: "granted"` and return **403** otherwise; `disable` and `request_access` never do, so an account whose access was withdrawn can still switch Self-Hosted off. The signing secret for a mode is minted the first time you `save` a `wsUrl` for it. Retrieve it from `GET /api/v1/self-hosted/secret?mode=…` and set up your server's `X-Dial-Signature` verification *before* you `activate` (activating routes your calls at the server immediately). Returns the full configuration after the change.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Request

This endpoint expects an object.

saveobjectRequired

Persist a mode’s config. Does not change which mode is active or whether Self-Hosted is on. The signing secret (and, for llm, the urlKey) is minted the first time a mode is saved.

activateobjectRequired

A save (same config body) that also enables Self-Hosted and routes calls through config.type — enable, or switch from the other mode. Affects new calls only.

disableobjectRequired

Turn Self-Hosted off. Both modes’ configs are kept.

request_accessobjectRequired

Ask for approval to use Self-Hosted mode. Valid only while access is none or denied — a pending request must be reviewed first, and a granted account has nothing to ask for. Returns the configuration with access moved to pending.

Response

The full configuration after the change.

enabledboolean

Whether Self-Hosted mode is currently driving the account’s calls.

accessenum

Whether this account may configure Self-Hosted mode. Self-Hosted lets a third-party server drive live calls, so accounts are approved before they can point calls at one.

none — no access and no request on file; submit one with the request_access action. pending — a request is awaiting review. granted — you may save and activate freely. denied — the request was reviewed and turned down; accessRequest.reviewNote says why.

Accounts that already had Self-Hosted before approval was introduced are granted — nothing changed for them.

activeModeenum

Which mode drives calls when enabled: "llm" (Dial runs voice; your server drives the conversation in text) or "audio" (Dial pipes the raw call audio to your server, full duplex).

accessRequestobject or nullOptional

Your most recent access request, or null if you have never submitted one (including accounts that already have access without asking).

llmobject or nullOptional

The LLM-mode config, or null until that mode is configured.

audioobject or nullOptional

The audio-mode config, or null until that mode is configured.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

save and activate require access: "granted" and return 403 otherwise; disable and request_access never do, so an account whose access was withdrawn can still switch Self-Hosted off.