Create Widget

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

Header	Value
Authorization	Bearer
Content-Type	application/json

Body

string

required

The website domain this widget will be embedded on (e.g., acme.com).

string

default:"PingBack Support"

A display name for the widget, used internally to identify it.

string

default:"Hi there!"

The main heading shown on the widget’s welcome screen.

string

A short tagline displayed below the welcome heading.

string

default:"#7650FF"

Hex color code used for the widget’s primary UI elements and launcher button.

boolean

default:"true"

Whether to show a live/offline availability badge on the widget launcher.

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.

object

default:"{}"

Additional configuration options for the widget.

Response

string

required

UUID of the newly created widget.

string

required

UUID of the business that owns the widget.

string

required

Display name of the widget.

string

required

The domain this widget is configured for.

string

required

Welcome screen heading.

string

required

Welcome screen tagline.

string

required

Primary hex color.

boolean

required

Whether the online badge is enabled.

string

Logo URL, or null if not set.

object

required

The widget’s configuration object.

string

required

ISO 8601 timestamp of creation.

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

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

Authentication

Conversations

Channels & Widget

Team

Knowledge Base

Analytics

Headers

Body

Response

Example

Response example

Update a widget

Path parameters

Body

Example

Errors

​Headers

​Body

​Response

​Example

​Response example

​Update a widget

​Path parameters

​Body

​Example

​Errors

Headers

Body

Response

Example

Response example

Update a widget

Path parameters

Body

Example

Errors