Skip to main content
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

1

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

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

Customize the widget appearance

The following fields control how the widget looks and behaves:
FieldDefaultDescription
primary_color#7650FFHex color for the launcher button and chat header.
welcome_headingHi there!Heading shown on the welcome screen.
welcome_taglineWe make it simple to connect with us...Subtext shown below the heading.
show_online_badgetrueDisplays a green dot on the launcher when agents are online.
logo_url—URL of your brand logo shown in the widget header.
4

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.