Embedding and Configuring the SparrowDesk Chat Widget

The SparrowDesk Chat Widget allows you to embed live chat support directly into your website or web application.

This guide shows you how to:

• Embed the widget on your site.
• Control the widget via JavaScript.
• Pass ticket (conversation) details and contact details before chat starts.

Embedding the Widget

Add the following script to your website’s HTML before the closing </body> tag:

<script src="<https://cdn.sparrowdesk.com/widget.js>" async></script>

This script loads the SparrowDesk chat widget and exposes a global window.sparrowDesk object that you can use to control and customize the widget.

Widget API Methods

openWidget()

Opens the chat widget.

window.sparrowDesk.openWidget();

closeWidget()

Closes the chat widget.

window.sparrowDesk.closeWidget();

onOpen(callback)

Registers a function to be called when the widget opens.

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

onClose(callback)

Registers a function to be called when the widget closes.

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

setTags(tags)

Stores tags (e.g., user info or identifiers) for the current session.

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

hideWidget()

Hides both the launcher and the chat canvas.

window.sparrowDesk.hideWidget();

status

Returns the current widget status: "open" or "closed".

console.log(window.sparrowDesk.status);

3. Passing Ticket (Conversation) Details

Use setConversationFields to pre-fill ticket fields before a conversation starts.

Works with the createMessage chat API flow.

window.sparrowDesk.setConversationFields({
  priority: "med",
  status: "todo",
  request_type: "Enquiry"
});

Supported Fields

• Default fields: priority, status
• Custom fields: Any custom conversation fields you’ve created

Validation Rules

• Field keys must match the internal name exactly.
• Dropdown values are case-insensitive.
• Values failing type validation are skipped.
• Invalid internal names are ignored.

Passing Contact Details

Use setContactFields to pre-fill customer profile details before chat starts.

Works with the registerParticipant chat API flow.

window.sparrowDesk.setContactFields({
  full_name: "Jane Doe",
  phone: "+15551234567",
  gender: "Female",
  nick_name: "JD"
});

Supported Fields

• Default fields: All contact fields except email
• Custom fields: Any custom contact fields you’ve created

Validation Rules

• Field keys must match the internal name exactly.
• Dropdown values are case-insensitive.
• Values failing type validation are skipped.

Troubleshooting

Widget doesn’t appear

• Check if the script URL is correct and accessible.
• Ensure window.sparrowDesk is available before calling methods.

Field values not saved

• Verify the internal name matches exactly.
• Ensure values meet type requirements (e.g., valid email, valid dropdown).

Widget methods not working

• Make sure calls are made after the widget script is loaded.