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.
| Header | Value |
|---|
| Authorization | Bearer |
| Content-Type | application/json |
Body
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.
A short tagline displayed below the welcome heading.
Hex color code used for the widget’s primary UI elements and launcher button.
Whether to show a live/offline availability badge on the widget launcher.
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.
Additional configuration options for the widget.
Response
UUID of the newly created widget.
UUID of the business that owns the widget.
Display name of the widget.
The domain this widget is configured for.
Whether the online badge is enabled.
Logo URL, or null if not set.
The widget’s configuration object.
ISO 8601 timestamp of creation.
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
}'
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();
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"
}
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
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
}'
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();
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 |