Skip to main content
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
Only one widget per domain per organization is allowed. Attempting to create a second widget for the same domain returns a 400 error.

​
Headers

HeaderValue
AuthorizationBearer
Content-Typeapplication/json

​
Body

​
domain
string
required
The website domain this widget will be embedded on (e.g., acme.com).
​
name
string
default:"PingBack Support"
A display name for the widget, used internally to identify it.
​
welcome_heading
string
default:"Hi there!"
The main heading shown on the widget’s welcome screen.
​
welcome_tagline
string
A short tagline displayed below the welcome heading.
​
primary_color
string
default:"#7650FF"
Hex color code used for the widget’s primary UI elements and launcher button.
​
show_online_badge
boolean
default:"true"
Whether to show a live/offline availability badge on the widget launcher.
​
logo_url
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.
​
config
object
default:"{}"
Additional configuration options for the widget.

​
Response

​
id
string
required
UUID of the newly created widget.
​
business_id
string
required
UUID of the business that owns the widget.
​
name
string
required
Display name of the widget.
​
domain
string
required
The domain this widget is configured for.
​
welcome_heading
string
required
Welcome screen heading.
​
welcome_tagline
string
required
Welcome screen tagline.
​
primary_color
string
required
Primary hex color.
​
show_online_badge
boolean
required
Whether the online badge is enabled.
​
logo_url
string
Logo URL, or null if not set.
​
config
object
required
The widget’s configuration object.
​
created_at
string
required
ISO 8601 timestamp of creation.
​
updated_at
string
required
ISO 8601 timestamp of last update.

​
Example

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

​
Response example

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

​
widget_id
string
required
The UUID of the widget to update.

​
Body

Same fields as Create Widget: name, domain, welcome_heading, welcome_tagline, primary_color, show_online_badge, logo_url, config.

​
Example

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

​
Errors

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