Widgets

Overview

A widget is an embeddable voice call entry point. You create a widget, configure its appearance and linked assistant, then embed it in your product. When a user clicks the call button, your frontend calls POST /v1/widgets/create-call to get a WebSocket URL and starts the audio session. Required scopes: widgets:read (read), widgets:write (create/update/delete/call)

`POST /v1/widgets`

Creates a new widget for your organization. Pass assistantId to attach an existing agent at creation time — if a widget already exists for that agent, the existing widget is returned instead of creating a duplicate. Omit it to create an unattached widget you configure later via PATCH /v1/widgets/{id}.

Announcer agents (see Agents → Announcer agents) can’t be attached to a widget — they’re one-way broadcast agents with no conversational voice engine. Passing an announcer agent’s id as assistantId here (or in PATCH /v1/widgets/{id}) returns a 400.

curl -X POST https://api.indigenius.ai/v1/widgets \
  -H "X-API-Key: $INDIGENIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assistantId": "665e4a34c65bb95f2f2d72e2"}'

const response = await fetch('https://api.indigenius.ai/v1/widgets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.INDIGENIUS_API_KEY,
  },
  body: JSON.stringify({ assistantId: '665e4a34c65bb95f2f2d72e2' }),
});
console.log(await response.json());

import requests, os

response = requests.post(
    "https://api.indigenius.ai/v1/widgets",
    headers={
        "X-API-Key": os.environ["INDIGENIUS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"assistantId": "665e4a34c65bb95f2f2d72e2"},
    timeout=30,
)
print(response.json())

201 Created

{
  "success": true,
  "message": "Widget created successfully",
  "data": {
    "created": true,
    "widget_id": "665e4a34c65bb95f2f2d72e1"
  },
  "meta": {
    "requestId": "f3c9b29a-9f4d-4b71-8b3b-2cb77f4e9cf1",
    "timestamp": "2026-06-02T10:30:45.123Z",
    "version": "v1"
  }
}

Common errors: 400 assistantId belongs to an announcer agent · 403 missing widgets:write scope

`GET /v1/widgets`

Lists all widgets for your organization.

curl https://api.indigenius.ai/v1/widgets \
  -H "X-API-Key: $INDIGENIUS_API_KEY"

const response = await fetch('https://api.indigenius.ai/v1/widgets', {
  headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
});
console.log(await response.json());

import requests, os

response = requests.get(
    "https://api.indigenius.ai/v1/widgets",
    headers={"X-API-Key": os.environ["INDIGENIUS_API_KEY"]},
    timeout=30,
)
print(response.json())

`200 OK`

{
  "success": true,
  "message": "User widgets fetched",
  "data": [
    {
      "id": "665e4a34c65bb95f2f2d72e1",
      "assistantId": "665e4a34c65bb95f2f2d72e2",
      "background_color": "#FFFFFF",
      "allowed_origins": [
        "https://app.example.com"
      ],
      "Assistant": {
        "id": "665e4a34c65bb95f2f2d72e2",
        "name": "Sales Agent"
      }
    }
  ],
  "meta": {
    "requestId": "f3c9b29a-9f4d-4b71-8b3b-2cb77f4e9cf1",
    "timestamp": "2026-06-02T10:30:45.123Z",
    "version": "v1"
  }
}

Common status codes

200 success
403 missing widgets:read
500 server error

`GET /v1/widgets/{id}`

Returns a single widget by ID.

curl https://api.indigenius.ai/v1/widgets/WIDGET_ID \
  -H "X-API-Key: $INDIGENIUS_API_KEY"

const response = await fetch('https://api.indigenius.ai/v1/widgets/WIDGET_ID', {
  headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
});
console.log(await response.json());

import requests, os

response = requests.get(
    "https://api.indigenius.ai/v1/widgets/WIDGET_ID",
    headers={"X-API-Key": os.environ["INDIGENIUS_API_KEY"]},
    timeout=30,
)
print(response.json())

`200 OK`

{
  "success": true,
  "message": "Widget details fetched",
  "data": {
    "id": "665e4a34c65bb95f2f2d72e1",
    "assistantId": "665e4a34c65bb95f2f2d72e2",
    "background_color": "#FFFFFF",
    "text_color": "#000000",
    "button_color": "#F79320",
    "allowed_origins": [
      "https://app.example.com"
    ],
    "water_mark_enabled": true,
    "Assistant": {
      "id": "665e4a34c65bb95f2f2d72e2",
      "name": "Sales Agent"
    }
  },
  "meta": {
    "requestId": "f3c9b29a-9f4d-4b71-8b3b-2cb77f4e9cf1",
    "timestamp": "2026-06-02T10:30:45.123Z",
    "version": "v1"
  }
}

Common status codes

200 success
403 missing widgets:read
404 widget not found (including a widget that belongs to a different organization)
500 server error

`PATCH /v1/widgets/{id}`

Updates a widget’s appearance, assistant, and allowed origins. This is a full replace, not a partial patch — every field below is required on every call, even to change just one of them. Unrecognized fields in the payload are ignored rather than causing an error. Setting water_mark_enabled to false requires an active paid subscription on the organization — this returns 403 for organizations on the Free plan or with no active subscription. Most fields are plain CSS-style values (hex colors, pixel radii, button labels) and are self-explanatory from the example below. Two worth calling out:

allowed_origins — an array of origins (scheme + host, e.g. https://app.example.com) permitted to embed and call this widget from the browser. Requests from any other origin are rejected.
terms_and_condition_content — free text shown when terms_and_condition is true. It isn’t validated server-side, so an empty or missing value is accepted even when terms_and_condition is true — it’s on you to supply real copy in that case.

curl -X PATCH https://api.indigenius.ai/v1/widgets/WIDGET_ID \
  -H "X-API-Key: $INDIGENIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "665e4a34c65bb95f2f2d72e2",
    "background_color": "#FFFFFF",
    "text_color": "#111827",
    "button_color": "#0EA5E9",
    "button_text_color": "#FFFFFF",
    "border_color": "#E5E7EB",
    "focus_outline_color": "#38BDF8",
    "card_radius": 12,
    "button_radius": 8,
    "start_call_button": "Start call",
    "end_call_button": "End call",
    "call_to_action": "Talk to Sales",
    "terms_and_condition": true,
    "terms_and_condition_content": "By continuing, you agree to recording terms.",
    "allowed_origins": ["https://app.example.com"],
    "water_mark_enabled": true,
    "logo_only_enabled": false
  }'

const widgetId = 'WIDGET_ID';
const response = await fetch(
  `https://api.indigenius.ai/v1/widgets/${widgetId}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.INDIGENIUS_API_KEY,
    },
    body: JSON.stringify({
      assistantId: '665e4a34c65bb95f2f2d72e2',
      background_color: '#FFFFFF',
      text_color: '#111827',
      button_color: '#0EA5E9',
      button_text_color: '#FFFFFF',
      border_color: '#E5E7EB',
      focus_outline_color: '#38BDF8',
      card_radius: 12,
      button_radius: 8,
      start_call_button: 'Start call',
      end_call_button: 'End call',
      call_to_action: 'Talk to Sales',
      terms_and_condition: true,
      terms_and_condition_content:
        'By continuing, you agree to recording terms.',
      allowed_origins: ['https://app.example.com'],
      water_mark_enabled: true,
      logo_only_enabled: false,
    }),
  },
);
console.log(await response.json());

import requests, os

widget_id = "WIDGET_ID"
response = requests.patch(
    f"https://api.indigenius.ai/v1/widgets/{widget_id}",
    headers={
        "X-API-Key": os.environ["INDIGENIUS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "assistantId": "665e4a34c65bb95f2f2d72e2",
        "background_color": "#FFFFFF",
        "text_color": "#111827",
        "button_color": "#0EA5E9",
        "button_text_color": "#FFFFFF",
        "border_color": "#E5E7EB",
        "focus_outline_color": "#38BDF8",
        "card_radius": 12,
        "button_radius": 8,
        "start_call_button": "Start call",
        "end_call_button": "End call",
        "call_to_action": "Talk to Sales",
        "terms_and_condition": True,
        "terms_and_condition_content": "By continuing, you agree to recording terms.",
        "allowed_origins": ["https://app.example.com"],
        "water_mark_enabled": True,
        "logo_only_enabled": False,
    },
    timeout=30,
)
print(response.json())

Common errors: 400 validation error · 403 missing widgets:write scope, or organization is not on a paid plan (when disabling water_mark_enabled) · 404 widget not found

`POST /v1/widgets/create-call`

Creates a call session for a widget. Call this from your server when a user clicks the call button in your UI.

The widget’s allowed_origins (set via PATCH /v1/widgets/{id}) is checked against this request’s Origin header, not the end user’s browser origin. A typical server-side HTTP call doesn’t send an Origin header at all, which fails this check — so when calling this endpoint from your backend, explicitly set an Origin header matching one of the widget’s allowed_origins, or the request is rejected with 400 Domain is not supported.

curl -X POST https://api.indigenius.ai/v1/widgets/create-call \
  -H "X-API-Key: $INDIGENIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"widget_id": "665e4a34c65bb95f2f2d72e1"}'

const response = await fetch(
  'https://api.indigenius.ai/v1/widgets/create-call',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.INDIGENIUS_API_KEY,
    },
    body: JSON.stringify({ widget_id: '665e4a34c65bb95f2f2d72e1' }),
  },
);
console.log(await response.json());

import requests, os

response = requests.post(
    "https://api.indigenius.ai/v1/widgets/create-call",
    headers={
        "X-API-Key": os.environ["INDIGENIUS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"widget_id": "665e4a34c65bb95f2f2d72e1"},
    timeout=30,
)
print(response.json())

201 Created

{
  "success": true,
  "message": "Call created",
  "data": {
    "call_id": "665e4a34c65bb95f2f2d72e9",
    "assistant_id": "665e4a34c65bb95f2f2d72e2",
    "gateway": {
      "transport": "websocket",
      "path": "/new-web-call/connection",
      "url": "wss://api.indigenius.ai/new-web-call/connection?assistant_id=665e4a34c65bb95f2f2d72e2&call_id=665e4a34c65bb95f2f2d72e9"
    }
  },
  "meta": {
    "requestId": "f3c9b29a-9f4d-4b71-8b3b-2cb77f4e9cf1",
    "timestamp": "2026-06-02T10:30:45.123Z",
    "version": "v1"
  }
}

Pass gateway.url to your browser client to open the WebSocket connection. The call_id can be used later to retrieve the transcript via GET /v1/calls/{id}/transcripts. Common errors: 400 invalid payload; widget has no assistant attached (attach one via PATCH /v1/widgets/{id} first); or the Origin header doesn’t match the widget’s allowed_origins · 403 missing widgets:write scope · 404 widget not found

`DELETE /v1/widgets/{id}`

Permanently deletes a widget.

curl -X DELETE https://api.indigenius.ai/v1/widgets/WIDGET_ID \
  -H "X-API-Key: $INDIGENIUS_API_KEY"

const response = await fetch('https://api.indigenius.ai/v1/widgets/WIDGET_ID', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
});
console.log(await response.json());

import requests, os

response = requests.delete(
    "https://api.indigenius.ai/v1/widgets/WIDGET_ID",
    headers={"X-API-Key": os.environ["INDIGENIUS_API_KEY"]},
    timeout=30,
)
print(response.json())

Common errors: 403 missing widgets:write scope · 404 widget not found

Getting Started

Core APIs

Platform APIs

Overview

`POST /v1/widgets`

`GET /v1/widgets`

`200 OK`

Common status codes

`GET /v1/widgets/{id}`

`200 OK`

Common status codes

`PATCH /v1/widgets/{id}`

`POST /v1/widgets/create-call`

`DELETE /v1/widgets/{id}`

​Overview

​POST /v1/widgets

​GET /v1/widgets

​200 OK

​Common status codes

​GET /v1/widgets/{id}

​200 OK

​Common status codes

​PATCH /v1/widgets/{id}

​POST /v1/widgets/create-call

​DELETE /v1/widgets/{id}

Overview

`POST /v1/widgets`

`GET /v1/widgets`

`200 OK`

Common status codes

`GET /v1/widgets/{id}`

`200 OK`

Common status codes

`PATCH /v1/widgets/{id}`

`POST /v1/widgets/create-call`

`DELETE /v1/widgets/{id}`