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

# Web Widget

> Embed PingBack's live chat widget on your website to capture customer conversations in real time.

The web widget lets you embed a live chat launcher on any webpage. Once embedded, customers can open a chat window and start a conversation that flows directly into your PingBack inbox.

<Note>The web widget is available on all plans, including Free.</Note>

## Setup

<Steps>
  <Step title="Create a widget">
    Send a `POST` request to `/api/v1/widget/create` with your widget configuration.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.pingback.live/api/v1/widget/create \
        -H "Authorization: Bearer <your_token>" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Support Widget",
          "domain": "https://example.com",
          "welcome_heading": "Hi there!",
          "welcome_tagline": "Ask us anything — we are here to help.",
          "primary_color": "#7650FF",
          "show_online_badge": true,
          "logo_url": "https://example.com/logo.png"
        }'
      ```

      ```json response theme={null}
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Support Widget",
        "domain": "https://example.com",
        "welcome_heading": "Hi there!",
        "welcome_tagline": "Ask us anything — we are here to help.",
        "primary_color": "#7650FF",
        "show_online_badge": true,
        "logo_url": "https://example.com/logo.png"
      }
      ```
    </CodeGroup>

    The response includes a `id` field — this is your `widget_id` (a UUID). Save it for the next step.

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

  <Step title="Embed the widget on your site">
    Use the `widget_id` from the previous step to load your widget configuration. When your page loads, the widget script calls:

    ```
    GET https://api.pingback.live/api/v1/widget/{widget_id}
    ```

    This fetches your widget's appearance settings and initializes the chat launcher. Add the following snippet before the closing `</body>` tag of your HTML, replacing `YOUR_WIDGET_ID` with the UUID returned in step 1:

    ```html html theme={null}
    <script>
      window.PingBackWidgetId = "YOUR_WIDGET_ID";
    </script>
    <script src="https://cdn.pingback.live/widget.js" async></script>
    ```

    The widget uses **Socket.IO** for real-time messaging. See the [Socket.IO integration guide](/realtime/socketio) for details on events and connection handling.
  </Step>

  <Step title="Customize the widget appearance">
    The following fields control how the widget looks and behaves:

    | Field               | Default                                   | Description                                                  |
    | ------------------- | ----------------------------------------- | ------------------------------------------------------------ |
    | `primary_color`     | `#7650FF`                                 | Hex color for the launcher button and chat header.           |
    | `welcome_heading`   | `Hi there!`                               | Heading shown on the welcome screen.                         |
    | `welcome_tagline`   | `We make it simple to connect with us...` | Subtext shown below the heading.                             |
    | `show_online_badge` | `true`                                    | Displays a green dot on the launcher when agents are online. |
    | `logo_url`          | —                                         | URL of your brand logo shown in the widget header.           |
  </Step>

  <Step title="Update widget settings">
    To change your widget configuration after creation, send a `PUT` request to `/api/v1/widget/update/{widget_id}`.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X PUT https://api.pingback.live/api/v1/widget/update/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
        -H "Authorization: Bearer <your_token>" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Support Widget",
          "domain": "https://example.com",
          "welcome_heading": "How can we help?",
          "welcome_tagline": "Our team usually replies in minutes.",
          "primary_color": "#5B3FCC",
          "show_online_badge": false,
          "logo_url": "https://example.com/new-logo.png"
        }'
      ```
    </CodeGroup>

    Any fields you omit retain their current values.
  </Step>
</Steps>