Methods

JS API methods allow you to create custom ways to interact with a widget. For example, you can hide your widget based on specific conditions or trigger a sales tracker defined earlier in Text. Here’s the list of available methods:

Maximize
Minimize
Hide
Destroy
Hide greeting
Trigger sales tracker

Maximize

It maximizes the Chat Widget. Example

LiveChatWidget.call("maximize");

To maximize the Chat Widget and pre-fill the chat input field with a predefined message, you can use the optional messageDraft param.

LiveChatWidget.call("maximize", { messageDraft: "I need help!" });

This method maximizes the Chat Widget and automatically inserts “I need help!” into the chat input field. If a Pre-chat form is enabled, it instead creates a message draft that is sent when the form is submitted. The action will have no effect if the widget’s current state prevents message entry or if the user already has a message draft.

Minimize

It minimizes the Chat Widget. Example

LiveChatWidget.call("minimize");

Hide

It hides the Chat Widget on the site. You will need to use either ‘maximize’, or ‘minimize’ API calls to show it afterwards. Example

LiveChatWidget.call("hide");

Destroy

It destroys the Chat Widget. It won’t be available for further actions until the window is refreshed. Example

LiveChatWidget.call("destroy");

Hide greeting

It hides the currently displayed greeting. In order to hide particular greeting you can listen to new_event or greeting_hidden callbacks to know when greeting with specified id or uniqueId appears and disappears accordingly. Example

LiveChatWidget.call("hide_greeting");

Trigger sales tracker

It triggers a sales tracker created in Text and passes over data about a sale. The data is then visible in Text’s Reports and Archives. For more information about how Sales Tracker works and how to set it up on your website, check out our official Help Center article: How Sales Tracker works in practice. Example

LiveChatWidget.call("trigger_sales_tracker", {
  trackerId: "V9x4nEIlFPhblkHW9qIOGLakMXen5NS0",
  orderPrice: total_order_price,
  orderId: order_number,
});

Payload

param	type	Required	Description
trackerId	`string`	Yes	The sales tracker ID. Obtain this value by creating a sales tracker in Text.
orderPrice	`string`	No	The order price.
orderId	`string`	No	The order ID.

Ecommerce

Available ecommerce methods:

Track sales event

Track sales event

Sends an ecommerce event. Cart and order events appear in the agent’s Inbox in real time. Order events also feed the All Sales and AI Agent Sales reports. Data syncs once a day, so orders appear in the reports the following day. Example

LiveChatWidget.call("track_sales_event", {
  name: "store_order_was_created",
  data: {
    order: {
      id: "1042",
      order_number: "#1042",
      currency: "USD",
      total_price: 149.99,
      line_items: [
        {
          product_id: "123456789",
          title: "Merino Wool Crew Neck",
          quantity: 1,
          price: 149.99,
        },
      ],
    },
  },
});

Payload

param	type	Required	Description
name	`string`	Yes	The event name. Accepted values: `store_order_was_created`, `store_product_added_to_cart`, `store_product_removed_from_cart`.
data	`object`	Yes	The event payload. Shape depends on `name`.

`store_order_was_created`

Use on your order confirmation page after a purchase is completed. Example

LiveChatWidget.call("track_sales_event", {
  name: "store_order_was_created",
  data: {
    order: {
      id: "1042",
      order_number: "#1042",
      currency: "USD",
      total_price: 149.99,
      subtotal_price: 129.99,
      shipping_price: 15.0,
      tax_price: 5.0,
      status_page_url: "https://shop.example.com/orders/1042",
      sales_channel: {
        id: "online-store",
        name: "Online Store",
      },
      discounts: [{ code: "SUMMER10" }],
      line_items: [
        {
          product_id: "123456789",
          title: "Merino Wool Crew Neck",
          quantity: 1,
          price: 89.99,
          sku: "MWC-BLK-M",
          variant_id: "5674839201",
          variant_title: "Black / Medium",
          thumbnail_url: "https://shop.example.com/img/merino-crew-black.jpg",
        },
        {
          product_id: "987654321",
          title: "Organic Cotton T-Shirt",
          quantity: 2,
          price: 20.0,
          sku: "OCT-WHT-L",
          variant_id: "1029384756",
          variant_title: "White / Large",
          thumbnail_url: "https://shop.example.com/img/cotton-tee-white.jpg",
        },
      ],
    },
  },
});

Data

param	type	Required	Description
`order.id`	`string`	Yes	The order ID from your platform.
`order.order_number`	`string`	Yes	A human-readable order number shown to agents.
`order.currency`	`string`	Yes	The currency code in ISO 4217 format (e.g. `"USD"`, `"EUR"`, `"GBP"`).
`order.total_price`	`number`	Yes	The final amount charged, after discounts, tax, and shipping.
`order.subtotal_price`	`number`	No	The order total before shipping and tax.
`order.shipping_price`	`number`	No	The shipping cost.
`order.tax_price`	`number`	No	The total tax amount.
`order.status_page_url`	`string`	No	The customer-facing URL for the order status page.
`order.sales_channel.id`	`string`	No	The sales channel identifier (e.g. `"online-store"`, `"instagram"`).
`order.sales_channel.name`	`string`	No	The sales channel display name.
`order.discounts[].code`	`string`	No	The promo code applied to the order.
`order.line_items[]`	`array`	Yes	The order’s line items. At least one entry is required.
`order.line_items[].product_id`	`string`	Yes	The product ID from your platform.
`order.line_items[].title`	`string`	Yes	The product name shown to agents.
`order.line_items[].quantity`	`number`	Yes	The quantity ordered. Must be ≥ 1.
`order.line_items[].price`	`number`	Yes	The unit price, not the line total.
`order.line_items[].sku`	`string`	No	The SKU.
`order.line_items[].variant_id`	`string`	No	The variant identifier from your platform.
`order.line_items[].variant_title`	`string`	No	A human-readable variant description (e.g. `"Black / Medium"`).
`order.line_items[].thumbnail_url`	`string`	No	The product image URL. A placeholder is used when omitted.

`store_product_added_to_cart`

Use when a customer adds an item to the cart. Example

LiveChatWidget.call("track_sales_event", {
  name: "store_product_added_to_cart",
  data: {
    cart_lines: [
      {
        total_price: 89.99,
        currency: "USD",
        quantity: 1,
        product: {
          id: "123456789",
          title: "Merino Wool Crew Neck",
          price: 89.99,
          sku: "MWC-BLK-M",
          variant_id: "5674839201",
          thumbnail_url: "https://shop.example.com/img/merino-crew-black.jpg",
        },
      },
    ],
  },
});

Data

param	type	Required	Description
`cart_lines[]`	`array`	Yes	The cart items. At least one entry is required.
`cart_lines[].total_price`	`number`	Yes	The line total (quantity × unit price).
`cart_lines[].currency`	`string`	Yes	The currency code in ISO 4217 format.
`cart_lines[].quantity`	`number`	Yes	The quantity. Must be ≥ 1.
`cart_lines[].product.id`	`string`	Yes	The product ID from your platform.
`cart_lines[].product.title`	`string`	Yes	The product name shown to agents.
`cart_lines[].product.price`	`number`	No	The unit price.
`cart_lines[].product.sku`	`string`	No	The SKU.
`cart_lines[].product.variant_id`	`string`	No	The variant identifier.
`cart_lines[].product.thumbnail_url`	`string`	No	The product image URL.

`store_product_removed_from_cart`

Use when a customer removes an item from the cart. Example

LiveChatWidget.call("track_sales_event", {
  name: "store_product_removed_from_cart",
  data: {
    cart_lines: [
      {
        total_price: 89.99,
        currency: "USD",
        quantity: 1,
        product: {
          id: "123456789",
          title: "Merino Wool Crew Neck",
          price: 89.99,
          sku: "MWC-BLK-M",
          variant_id: "5674839201",
          thumbnail_url: "https://shop.example.com/img/merino-crew-black.jpg",
        },
      },
    ],
  },
});

Data

param	type	Required	Description
`cart_lines[]`	`array`	Yes	The cart items. At least one entry is required.
`cart_lines[].total_price`	`number`	Yes	The line total (quantity × unit price).
`cart_lines[].currency`	`string`	Yes	The currency code in ISO 4217 format.
`cart_lines[].quantity`	`number`	Yes	The quantity. Must be ≥ 1.
`cart_lines[].product.id`	`string`	Yes	The product ID from your platform.
`cart_lines[].product.title`	`string`	Yes	The product name shown to agents.
`cart_lines[].product.price`	`number`	No	The unit price.
`cart_lines[].product.sku`	`string`	No	The SKU.
`cart_lines[].product.variant_id`	`string`	No	The variant identifier.
`cart_lines[].product.thumbnail_url`	`string`	No	The product image URL.

Getters

You can use getters to fetch the data from the Chat Widget. Available getters:

Get state
Get customer data
Get chat data

Get state

It returns the Chat Widget state. This includes Widget visibility and license availability. Example

LiveChatWidget.get("state");

Response

param	type	Required	Description
availability	`'online'` \| `'offline'`	Yes	The group’s availability.
visibility	`'maximized'` \| `'minimized'` \| `'hidden'`	Yes	The Chat Widget visibility.

Get customer data

It returns a filtered list of customer data. Example

LiveChatWidget.get("customer_data");

Response

param	type	Required	Description
id	`string`	Yes	The unique customer ID.
name	`string`	Yes	The customer name, as provided.
email	`string`	Yes	The customer email address, as provided.
isReturning	`boolean`	Yes	Whether this customer has visited before.
status	`'queued'` \| `'chatting'` \| `'browsing'` \| `'invited'`	Yes	The customer’s status.
sessionVariables	`Record<string, string>`	Yes	Additional free-form session information.

Get chat data

It returns chat data which contains current chat and thread ids. Example

LiveChatWidget.get("chat_data");

Response

param	type	Required	Description
chatId	`string`	Yes	The unique chat ID.
threadId	`string`	Yes	The unique current thread ID.

Setters

Various data can be sent over to the Text integration so that your agents can use it. For more information, you can read these articles in our Help Center: https://www.text.com/help/custom-variables-configuration/. Available setters:

Set session variables
Update session variables
Set customer name
Set customer email

Set session variables

Creates new session variables, or replaces the ones set previously.

LiveChatWidget.call("set_session_variables", {
  username: "john.doe",
  cart_value: "450",
  "order date": "05/21/2019",
});

Update session variables

It changes the values of your session variables. Note that existing variables won’t be replaced. The new session variables will be included together with the ones set previously. Example

LiveChatWidget.call("update_session_variables", {
  username: "j.doe",
  cart_value: "400",
  "order date": "06/15/2019",
});

Set customer name

It sets the customer’s name. Example

LiveChatWidget.call("set_customer_name", "John Doe");

Set customer email

It sets the customer’s email address. Example

LiveChatWidget.call("set_customer_email", "john@example.com");

Callbacks

Callbacks allow you to react to the events triggered by the Chat Widget. You can use them to add custom behaviors when certain events happen. This can be accomplished by subscribing a callback with the API. Available callbacks:

On ready
On availability changed
On visibility changed
On customer status changed
On new event
On form submitted
On rating submitted
On greeting displayed
On greeting hidden
On rich message button clicked

On ready

The Chat Widget has finished loading. If the Chat Widget is already loaded the provided handler function will be called immediately. With this callback, you will receive the Chat Widget state and customer data as if requested by their getters. Payload

param	type	Required	Description
state	WidgetState	Yes	The Chat Widget state.
customerData	CustomerData	Yes	The customer data.

function onReady(initialData) {
  // Chat Widget is ready

  var state = initialData.state;
  var customerData = initialData.customerData;
}

LiveChatWidget.on("ready", onReady);
// LiveChatWidget.off('ready', onReady)

On availability changed

Availability has changed for the current group. Payload

param	type	Required	Description
availability	`"online"` \| `"offline"`	Yes	The group’s availability.

function onAvailabilityChanged(data) {
  if (data.availability === "online") {
    // we're available to chat!
  } else {
    // sadly, no agents are available at the moment.
  }
}

LiveChatWidget.on("availability_changed", onAvailabilityChanged);
// LiveChatWidget.off('availability_changed', onAvailabilityChanged)

On visibility changed

It is called once the visibility of the Chat Widget has changed. This applies to both user actions like maximizing or minimizing the window as well as hiding or showing the Chat Widget through the use of this API. Payload

param	type	Required	Description
visibility	`"maximized"` \| `"minimized"` \| `"hidden"`	Yes	The Chat Widget visibility.

function onVisibilityChanged(data) {
  switch (data.visibility) {
    case "maximized":
      break;
    case "minimized":
      break;
    case "hidden":
      break;
  }
}

LiveChatWidget.on("visibility_changed", onVisibilityChanged);
// LiveChatWidget.off('visibility_changed', onVisibilityChanged)

On customer status changed

It is called once the status of your customer has changed. This can be used to track the following info:

If and when Customers are being invited to chat
If Customers are already chatting
If they are waiting for an agent to become available in the queue

Payload

param	type	Required	Description
status	`'queued'` \| `'chatting'` \| `'invited'` \| `'browsing'`	Yes	The customer’s status.

function onCustomerStatusChanged(data) {
  switch (data.status) {
    case "queued":
      // customer is in queue
      break;
    case "chatting":
      // customer is currently chatting
      break;
    case "invited":
      // customer received an invitation but didn't start the chat
      break;
    case "browsing":
      // customer is in idle state, not queued, not chatting, and didn't receive an invitation
      break;
  }
}

LiveChatWidget.on("customer_status_changed", onCustomerStatusChanged);
// LiveChatWidget.off('customer_status_changed', onCustomerStatusChanged)

On new event

It is called for both incoming and outgoing events. Payload

General
Greeting

param	type	Required	Description
timestamp	`number`	Yes	The event’s send timestamp.
type	`'message'` \| `'emoji'` \| `'rich_message'` \| `'file'` \| `'custom'`	Yes	The event’s type.
author.id	`string`	Yes	The event’s author ID.
author.type	`'customer'` \| `'agent'`	Yes	The event’s author type.
author.name	`string`	No	The event’s author name. Present only if provided.
author.avatar	`string`	No	The event’s author avatar URL. Present only if provided.
customId	`string`	No	A custom identifier for the event. Present only if the event type is `custom`.
content	`object`	No	The custom event’s payload. Present only if the event type is `custom`.

If the event is a greeting, the payload includes all the fields from General, plus:

param	type	Required	Description
greeting.id	`number`	Yes	The greeting’s campaign ID.
greeting.uniqueId	`string`	Yes	The greeting’s event unique ID.
greeting.title	`string`	No	The greeting’s title text. Present only if the greeting has a title.
greeting.subtitle	`string`	No	The greeting’s subtitle text. Present only if the greeting has a subtitle.
greeting.image	`object`	No	The greeting’s image. Present only if the greeting has an image.
greeting.image.url	`string`	Yes	The image URL.
greeting.image.name	`string`	No	The image file name.
greeting.image.alternativeText	`string`	No	The image alt text.
greeting.buttons[]	`array`	No	The greeting’s buttons. Present only if the greeting has buttons.
greeting.buttons[].type	`string`	No	The button type (for example, `message` or `url`).
greeting.buttons[].text	`string`	Yes	The button label.
greeting.buttons[].postbackId	`string`	Yes	The button’s postback ID.
greeting.buttons[].value	`string`	No	The button value.
greeting.buttons[].role	`string`	No	The button role (for example, `default`, `primary`, or `danger`).
greeting.subtype	`string`	No	The greeting’s subtype. Present only if the greeting has a subtype.
greeting.addon	`string`	No	The greeting’s addon identifier. Present only if the greeting has an addon.
greeting.isExitIntent	`boolean`	No	Whether the greeting was triggered by exit intent.

function onNewEvent(event) {
  var authorId = event.author.id;
  var authorType = event.author.type; // 'agent' or 'customer'
  var authorName = event.author.name; // present only if provided
  var authorAvatar = event.author.avatar; // present only if provided

  switch (event.type) {
    case "message":
      // handle new message event
      break;

    case "emoji":
      // handle new emoji event
      break;

    case "rich_message":
      // handle new rich_message event
      break;

    case "file":
      // handle new file event
      break;

    case "custom":
      // handle new custom event
      // event.customId, event.content
      break;

    default:
      break;
  }

  if (event.greeting) {
    // new event is a greeting
    // greeting properties are available
    var id = event.greeting.id;
    var uniqueId = event.greeting.uniqueId;
    var title = event.greeting.title;
    var subtitle = event.greeting.subtitle;
    var image = event.greeting.image;
    var buttons = event.greeting.buttons;
    var subtype = event.greeting.subtype;
    var isExitIntent = event.greeting.isExitIntent;
  }
}

LiveChatWidget.on("new_event", onNewEvent);
// LiveChatWidget.off('new_event', onNewEvent)

On form submitted

It is called after a form has been submitted in the chat. Payload

param	type	Required	Description
type	`"prechat"` \| `"postchat"` \| `"ticket"`	Yes	The form type.

function onFormSubmitted(data) {
  switch (data.type) {
    case "prechat":
      // prechat submitted
      break;

    case "postchat":
      // postchat submitted
      break;

    case "ticket":
      // ticket submitted
      break;

    default:
      break;
  }
}

LiveChatWidget.on("form_submitted", onFormSubmitted);
// LiveChatWidget.off('form_submitted', onFormSubmitted)

On rating submitted

It is called after the customer has rated the chat, or cancelled the previous rating. Payload

param	type	Required	Description
value	`"good"` \| `"bad"` \| `"none"`	Yes	The customer’s rating value.

function onRatingSubmitted(value) {
  // do something
}

LiveChatWidget.on("rating_submitted", onRatingSubmitted);
// LiveChatWidget.off('rating_submitted', onRatingSubmitted)

On greeting displayed

It is called after the greeting has been displayed to the customer. Payload

param	type	Required	Description
id	`number`	Yes	The greeting’s template ID.
uniqueId	`string`	Yes	The greeting’s event unique ID.

function onGreetingDisplayed(greeting) {
  // greeting has been displayed
  var id = greeting.id;
  var uniqueId = greeting.uniqueId;
}

LiveChatWidget.on("greeting_displayed", onGreetingDisplayed);
// LiveChatWidget.off('greeting_displayed', onGreetingDisplayed)

On greeting hidden

It is called after the greeting has been cancelled by the customer or hide_greeting method. Payload

param	type	Required	Description
id	`number`	Yes	The greeting’s template ID.
uniqueId	`string`	Yes	The greeting’s event unique ID.

function onGreetingHidden(greeting) {
  // greeting has been hidden
  var id = greeting.id;
  var uniqueId = greeting.uniqueId;
}

LiveChatWidget.on("greeting_hidden", onGreetingHidden);
// LiveChatWidget.off('greeting_hidden', onGreetingHidden)

On rich message button clicked

It is called after the rich message button has been clicked by the customer. Payload

param	type	Required	Description
eventId	`string`	Yes	The button’s owner event ID.
postbackId	`string`	Yes	The clicked button’s postback ID.
greeting.id	`number`	No	The greeting’s template ID. Present only if the button belongs to a greeting.
greeting.uniqueId	`string`	No	The greeting’s event unique ID. Present only if the button belongs to a greeting.

function onRichMessageButtonClicked(data) {
  // rich message button clicked
  var eventId = data.eventId;
  var postbackId = data.postbackId;

  if (data.greeting) {
    // clicked button belongs to greeting event
    var greetingId = data.greeting.id;
    var greetingUniqueId = data.greeting.uniqueId;
  }
}

LiveChatWidget.on("rich_message_button_clicked", onRichMessageButtonClicked);
// LiveChatWidget.off('rich_message_button_clicked', onRichMessageButtonClicked)

​Methods

​Maximize

​Minimize

​Hide

​Destroy

​Hide greeting

​Trigger sales tracker

​Ecommerce

​Track sales event

​store_order_was_created

​store_product_added_to_cart

​store_product_removed_from_cart

​Getters

​Get state

​Get customer data

​Get chat data

​Setters

​Set session variables

​Update session variables

​Set customer name

​Set customer email

​Callbacks

​On ready

​On availability changed

​On visibility changed

​On customer status changed

​On new event

​On form submitted

​On rating submitted

​On greeting displayed

​On greeting hidden

​On rich message button clicked

Methods

Maximize

Minimize

Hide

Destroy

Hide greeting

Trigger sales tracker

Ecommerce

Track sales event

`store_order_was_created`

`store_product_added_to_cart`

`store_product_removed_from_cart`

Getters

Get state

Get customer data

Get chat data

Setters

Set session variables

Update session variables

Set customer name

Set customer email

Callbacks

On ready

On availability changed

On visibility changed

On customer status changed

On new event

On form submitted

On rating submitted

On greeting displayed

On greeting hidden

On rich message button clicked