> ## Documentation Index
> Fetch the complete documentation index at: https://docs.indigenius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets

> Embed a call button on any webpage and manage widget sessions.

## 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.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST https://api.indigenius.ai/v1/widgets \
    -H "X-API-Key: $INDIGENIUS_API_KEY"
  ```

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

  ```python Python theme={null}
  import requests, os

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

**`201 Created`**

```json theme={null}
{
  "status": true,
  "message": "Widget created",
  "data": {
    "id": "665e4a34c65bb95f2f2d72e1"
  }
}
```

**Common errors:** `403` missing `widgets:write` scope

***

## `GET /v1/widgets`

Lists all widgets for your organization.

<CodeGroup>
  ```bash Bash theme={null}
  curl https://api.indigenius.ai/v1/widgets \
    -H "X-API-Key: $INDIGENIUS_API_KEY"
  ```

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

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

## `GET /v1/widgets/{id}`

Returns a single widget by ID.

<CodeGroup>
  ```bash Bash theme={null}
  curl https://api.indigenius.ai/v1/widgets/WIDGET_ID \
    -H "X-API-Key: $INDIGENIUS_API_KEY"
  ```

  ```javascript Node theme={null}
  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());
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

## `PATCH /v1/widgets/{id}`

Updates a widget's appearance, assistant, and allowed origins.

<CodeGroup>
  ```bash Bash theme={null}
  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"]
    }'
  ```

  ```javascript Node theme={null}
  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'],
      }),
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  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"],
      },
      timeout=30,
  )
  print(response.json())
  ```
</CodeGroup>

**Common errors:** `400` validation error · `403` missing `widgets:write` scope · `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.

<CodeGroup>
  ```bash Bash theme={null}
  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"}'
  ```

  ```javascript Node theme={null}
  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());
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

**`201 Created`**

```json theme={null}
{
  "status": true,
  "message": "Call created",
  "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"
  }
}
```

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 · `403` missing `widgets:write` scope · `404` widget not found

***

## `DELETE /v1/widgets/{id}`

Permanently deletes a widget.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X DELETE https://api.indigenius.ai/v1/widgets/WIDGET_ID \
    -H "X-API-Key: $INDIGENIUS_API_KEY"
  ```

  ```javascript Node theme={null}
  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());
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

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