JavaScript API

Global methods and properties on window.sparrowDesk to control the SparrowDesk chat widget

When the chat widget script has loaded, the host page can control and customize the widget through the global window.sparrowDesk object.

openWidget()

Opens the chat widget.

window.sparrowDesk.openWidget();

closeWidget()

Closes the chat widget.

window.sparrowDesk.closeWidget();

onOpen(callback)

Registers a function that runs when the widget opens.

Parameter	Type	Description
`callback`	`() => void`	Called each time the widget opens.

window.sparrowDesk.onOpen(() => {
  console.log("Widget opened");
});

onClose(callback)

Registers a function that runs when the widget closes.

Parameter	Type	Description
`callback`	`() => void`	Called each time the widget closes.

window.sparrowDesk.onClose(() => {
  console.log("Widget closed");
});

setTags(tags)

Stores tags for the current session — useful for user segments or identifiers.

Parameter	Type	Description
`tags`	`string[]`	Array of tag strings to attach to the session.

window.sparrowDesk.setTags(["vip", "returning-user"]);

hideWidget()

Hides both the launcher button and the widget panel.

window.sparrowDesk.hideWidget();

status

Read-only string indicating the current state of the widget.

Type: "open" | "closed"

console.log(window.sparrowDesk.status); // "open" or "closed"

Sets conversation field values by default when a conversation starts. Use each field’s internal name as defined in SparrowDesk. Invalid internal names are ignored; values that fail type validation are skipped. Dropdown values may be matched case-insensitively.

This method applies to flows that create a conversation via the createMessage chat API.

Parameter	Type	Description
`fields`	`Record<string, string>`	Key–value pairs of field internal names to values.

Built-in fields like priority and status are available by default. You can also pass any custom conversation fields you have configured in SparrowDesk.

window.sparrowDesk.setConversationFields({
  priority: "med",
  status: "todo",
  request_type: "ENQUIRY",
  support_email: "[email protected]",
});

If a key does not match a real internal name (for example a typo), that field is not set.

setContactFields(fields)

Sets contact field values when a conversation is started with contact registration. Same rules as setConversationFields: use internal names, respect field types, and dropdown options are matched case-insensitively.

This method applies to the registerParticipant chat API flow.

Parameter	Type	Description
`fields`	`Record<string, string>`	Key–value pairs of contact field internal names to values.

Default system fields and your custom contact fields can be set when valid. Email is excluded depending on your setup.

window.sparrowDesk.setContactFields({
  full_name: "Alex",
  phone: "+15551234567",
  nick_name: "Alex",
});

Values that fail validation (wrong email format, phone rules, dropdown value not in the list, etc.) are skipped for those fields only.

Installation reference

For copying the embed snippet, placement, verification, and domain allowlisting, see Overview and the Help Center: Installing Chat Widget.