Widget config

Use these endpoints when you build your own chat or voice UI instead of the VoisX widget. They tell you how the widget is styled and which agents a visitor can talk to.

Get the widget config

GET/widget/v1/config

Returns the widget settings for the key's project and the list of active agents in it. Agents that are not active are left out.

Requires the widget:read permission.

Headers

X-API-Keystringrequired

Your project API key.

Response fields

project_idintegeroptional

The project the key belongs to.

project_namestringoptional

The project name.

widget_configobjectoptional

Widget settings, in four groups: designTokens (colours, font, radius), branding, copy (button and status text) and features (on/off switches). You set these in the console. Unset values fall back to defaults.

agentsarrayoptional

Active agents in the project.

agents[].idintegeroptional

The agent ID. Use it to start a session.

agents[].namestringoptional

The agent name.

agents[].descriptionstring or nulloptional

The agent description.

agents[].initial_messagestring or nulloptional

The first thing the agent says.

agents[].providerstringoptional

The voice provider the agent uses, for example openai, gemini or elevenlabs.

agents[].elevenlabs_convai_agent_idstring or nulloptional

Set when the agent runs on ElevenLabs Conversational AI. See Get an ElevenLabs signed URL.

Responses

200

The config and agents.

401

The key is invalid, revoked, lacks widget:read, or is not allowed from this domain.

404

The project was not found.

429

The key's rate limit was reached.

cURL

curl https://in.api.voisx.ai/widget/v1/config \
  -H "X-API-Key: $VOISX_API_KEY"

Node.js

const res = await fetch("https://in.api.voisx.ai/widget/v1/config", {
  headers: { "X-API-Key": process.env.VOISX_API_KEY },
});
const { agents, widget_config } = await res.json();

Python

import os
import requests

res = requests.get(
    "https://in.api.voisx.ai/widget/v1/config",
    headers={"X-API-Key": os.environ["VOISX_API_KEY"]},
)
data = res.json()

200 OK

{
  "project_id": 1042,
  "project_name": "Front desk",
  "widget_config": {
    "designTokens": {
      "headerBackground": "#1e1e4c",
      "fontFamily": "Inter, sans-serif",
      "borderRadius": "1rem"
    },
    "branding": {
      "name": "Example Clinic",
      "url": "https://www.example.com",
      "poweredByText": "Powered by",
      "logoUrl": null
    },
    "copy": {
      "connectText": "Connect",
      "disconnectText": "Disconnect"
    },
    "features": {
      "showBranding": true,
      "enableTranscript": true,
      "autoConnect": false
    }
  },
  "agents": [
    {
      "id": 2210,
      "name": "Reception",
      "description": "Answers questions and books visits",
      "initial_message": "Hi, how can I help?",
      "provider": "openai",
      "elevenlabs_convai_agent_id": null
    }
  ]
}

The example shortens widget_config. The real response includes every setting.

Get the project context

GET/widget/v1/context

Returns the IDs and names of the key's project and organization. Use it when your page or your tools need to know which project they are running in.

Requires the widget:read permission.

Headers

X-API-Keystringrequired

Your project API key.

Response fields

project_idintegeroptional

The project ID.

project_namestringoptional

The project name.

org_idinteger or nulloptional

The organization ID.

org_namestring or nulloptional

The organization name.

Responses

200

The project context.

401

The key is invalid, revoked, lacks widget:read, or is not allowed from this domain.

404

The project was not found.

429

The key's rate limit was reached.

cURL

curl https://in.api.voisx.ai/widget/v1/context \
  -H "X-API-Key: $VOISX_API_KEY"

Node.js

const res = await fetch("https://in.api.voisx.ai/widget/v1/context", {
  headers: { "X-API-Key": process.env.VOISX_API_KEY },
});
const context = await res.json();

Python

import os
import requests

res = requests.get(
    "https://in.api.voisx.ai/widget/v1/context",
    headers={"X-API-Key": os.environ["VOISX_API_KEY"]},
)
context = res.json()

200 OK

{
  "project_id": 1042,
  "project_name": "Front desk",
  "org_id": 87,
  "org_name": "Example Clinic"
}