Web Widget

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.

The web widget is available on all plans, including Free.

Setup

Create a widget

Send a POST request to /api/v1/widget/create with your widget configuration.

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"
  }'

{
  "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"
}

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

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

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

<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 for details on events and connection handling.

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.

Update widget settings

To change your widget configuration after creation, send a PUT request to /api/v1/widget/update/{widget_id}.

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"
  }'

Any fields you omit retain their current values.

Get Started

Core Concepts

Channels

AI Assistant

Realtime & Webhooks

Plans & Billing

Setup

​Setup

Setup