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

# Create Widget

> Create a new support widget for a website domain.

Creates a new embeddable support widget for a specific domain. Creating a widget also automatically provisions a default `widget` channel for your business so visitor conversations can be received immediately.

**Method**: `POST`  **URL**: `/api/v1/widget/create`

<Warning>
  Only one widget per domain per organization is allowed. Attempting to create a second widget for the same domain returns a `400` error.
</Warning>

### Headers

| Header        | Value            |
| ------------- | ---------------- |
| Authorization | Bearer {token}   |
| Content-Type  | application/json |

### Body

<ParamField body="domain" type="string" required>
  The website domain this widget will be embedded on (e.g., `acme.com`).
</ParamField>

<ParamField body="name" type="string" default="PingBack Support">
  A display name for the widget, used internally to identify it.
</ParamField>

<ParamField body="welcome_heading" type="string" default="Hi there!">
  The main heading shown on the widget's welcome screen.
</ParamField>

<ParamField body="welcome_tagline" type="string" default="We make it simple to connect with us. Ask us anything, or share your feedback.">
  A short tagline displayed below the welcome heading.
</ParamField>

<ParamField body="primary_color" type="string" default="#7650FF">
  Hex color code used for the widget's primary UI elements and launcher button.
</ParamField>

<ParamField body="show_online_badge" type="boolean" default="true">
  Whether to show a live/offline availability badge on the widget launcher.
</ParamField>

<ParamField body="logo_url" type="string">
  URL to a logo image displayed inside the widget. Host the image on any publicly accessible CDN or image host, then pass the URL here.
</ParamField>

<ParamField body="config" type="object" default="{}">
  Additional configuration options for the widget.
</ParamField>

### Response

<ResponseField name="id" type="string" required>
  UUID of the newly created widget.
</ResponseField>

<ResponseField name="business_id" type="string" required>
  UUID of the business that owns the widget.
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name of the widget.
</ResponseField>

<ResponseField name="domain" type="string" required>
  The domain this widget is configured for.
</ResponseField>

<ResponseField name="welcome_heading" type="string" required>
  Welcome screen heading.
</ResponseField>

<ResponseField name="welcome_tagline" type="string" required>
  Welcome screen tagline.
</ResponseField>

<ResponseField name="primary_color" type="string" required>
  Primary hex color.
</ResponseField>

<ResponseField name="show_online_badge" type="boolean" required>
  Whether the online badge is enabled.
</ResponseField>

<ResponseField name="logo_url" type="string">
  Logo URL, or `null` if not set.
</ResponseField>

<ResponseField name="config" type="object" required>
  The widget's configuration object.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of creation.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 timestamp of last update.
</ResponseField>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.pingback.live/api/v1/widget/create \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "domain": "acme.com",
      "name": "Acme Support",
      "welcome_heading": "Welcome to Acme!",
      "welcome_tagline": "How can we help you today?",
      "primary_color": "#E63946",
      "show_online_badge": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.pingback.live/api/v1/widget/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer {token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      domain: 'acme.com',
      name: 'Acme Support',
      welcome_heading: 'Welcome to Acme!',
      welcome_tagline: 'How can we help you today?',
      primary_color: '#E63946',
      show_online_badge: true
    })
  });

  const widget = await response.json();
  ```
</CodeGroup>

### Response example

```json theme={null}
{
  "id": "9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a",
  "business_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Acme Support",
  "domain": "acme.com",
  "welcome_heading": "Welcome to Acme!",
  "welcome_tagline": "How can we help you today?",
  "primary_color": "#E63946",
  "show_online_badge": true,
  "logo_url": null,
  "config": {},
  "created_at": "2024-01-20T12:00:00Z",
  "updated_at": "2024-01-20T12:00:00Z"
}
```

***

## Update a widget

**Method**: `PUT`  **URL**: `/api/v1/widget/update/{widget_id}`

Updates an existing widget's configuration. Only the owner of the business can update a widget. Any field you omit retains its current value.

### Path parameters

<ParamField path="widget_id" type="string" required>
  The UUID of the widget to update.
</ParamField>

### Body

Same fields as [Create Widget](#body): `name`, `domain`, `welcome_heading`, `welcome_tagline`, `primary_color`, `show_online_badge`, `logo_url`, `config`.

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl --request PUT \
    --url https://api.pingback.live/api/v1/widget/update/9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "primary_color": "#2B9348",
      "show_online_badge": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.pingback.live/api/v1/widget/update/9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer {token}',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        primary_color: '#2B9348',
        show_online_badge: false
      })
    }
  );

  const updated = await response.json();
  ```
</CodeGroup>

### Errors

| Status | Meaning                                                            |
| ------ | ------------------------------------------------------------------ |
| 400    | A widget for this domain already exists, or organization not found |
| 401    | Unauthorized — missing or invalid token                            |
| 403    | Forbidden — you are not the owner of this business                 |
| 404    | Widget not found                                                   |