Smith.ai Chat API Documentation for Extended Data and Widget Visibility

Want to make changes to the way your widget functions or the metadata it collects on your web visitor (“guest”)? You can use our public-facing API to customize your chat conversations in various ways.

Although the possibilities are limitless, here are a couple of use case examples for this API:

  • Track marketing ROI using UTM parameters
  • Show the widget to new leads only
  • Attach timestamps and additional contact information to conversation histories

To get set up, modify and add the following scripts to your widget code.

Smith.ai Live Chat widget public API

Widget Initialized

Your chat widget is initialized when it loads and appears on the page.

onWidgetInitialized(callback: function)

window.SMITH = { };
window.SMITH.smithChatAccount = "<smith_chat_account_id>";
var script = document.createElement("script");
script.async = !0;
script.type = "text/javascript";
script.onload = onScriptLoad;
script.src = "https://app.smith.ai/chat/widget-latest.js";
document.getElementsByTagName("HEAD").item(0).appendChild(script);

function onScriptLoad () {
  // Example:
  // Add a custom event for Google Tag Manager.
  var chat = window.SMITH.chat;

  chat.onWidgetInitialized(function() {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: 'widget-initialized'
    });
  });
}

Conversation Started

A conversation has started when the guest engages the widget and sends their first message.

onConversationStarted(callback: function)

window.SMITH = { };
window.SMITH.smithChatAccount = "<smith_chat_account_id>";
var script = document.createElement("script");
script.async= !0;
script.type = "text/javascript";
script.onload = onScriptLoad;
script.src = "https://app.smith.ai/chat/widget-latest.js";
document.getElementsByTagName("HEAD").item(0).appendChild(script);

function onScriptLoad () {
  // Example:
  // Add a variable to GTM to track the guest's time to engagement.
  var chat = window.SMITH.chat;
  var timeLoaded = +(new Date());

  chat.onConversationStarted(function() {
    var timeEngaged = +(new Date());
    var engagementTime = (timeEngaged - timeLoaded) / 1000;
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      'guest-engaged-widget-in-seconds': engagementTime
    });
  })
}

Conversation Closed

The conversation is closed when our chat agents finish a conversation and mark it as “Relevant” or “Not Relevant.”

onConversationClosed(callback: function)

window.SMITH = { };
window.SMITH.smithChatAccount = "<smith_chat_account_id>";
var script = document.createElement("script");
script.async= !0;
script.type = "text/javascript";
script.onload = onScriptLoad;
script.src = "https://app.smith.ai/chat/widget-latest.js";
document.getElementsByTagName("HEAD").item(0).appendChild(script);

function onScriptLoad () {
  // Example:
  // Store the Smith conversation id in Google tag manager.
  var chat = window.SMITH.chat;  
  
  chat.onConversationClosed(function(smithConversationId) {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      'smith-conversation-id': smithConversationId     
    });
  })
}

Set Visibility

Toggles the visibility and open state of the widget. The widget is “visible” when either the button or the widget can be seen on the page and “open” when it expands to allow the guest to start a conversation.

This is useful if you need to hide the widget entirely after a form submission or in response to some event on the page.

setVisibility(widgetShow: Boolean, ?widgetOpen: Boolean)

var chat = window.SMITH.chat
chat.setVisibility(false); // Hide the widget
chat.setVisibility(true); // Show the widget in its closed state
chat.setVisibility(true, true); // Show the widget in its open state

Update Conversation Metadata

Attach additional dynamic metadata from the host page (UTM params, etc.) to the Smith.ai conversation object. This data can only be attached once the conversation has started, and is accessible in the Chat application's history view.

updateConversationMetadata(metadata: {})

window.SMITH = { };
window.SMITH.smithChatAccount = "<your_smith_chat_account_id>";
var script = document.createElement("script");
script.async = !0;
script.type = "text/javascript";
script.onload = onScriptLoad;
script.src = "https://app.smith.ai/chat/widget-latest.js";
document.getElementsByTagName("HEAD").item(0).appendChild(script);

function onScriptLoad () {
  // Example:
  // Store utm params as extra meta data.
  // Example url:
  // https://app.your-domain.com?utm_campaign=1&utm_medium=2&utm_source=3&utm_source=4,
  var chat = window.SMITH.chat;

  // Wait for the conversation to be created...
  chat.onConversationStarted(function(smithConversationId) {
    var queryString = window.location.search;
    var utmParams = new URLSearchParams(queryString);    
    
    // Then update its meta data. 
    chat.updateConversationMetadata({
      utm_campaign: utmParams.getAll('utm_campaign'),  // "1"
      utm_medium: utmParams.getAll('utm_medium'),  // "2"
      utm_source: utm.getAll('utm_source'),  // "[3,4]"
    });
  })
}

Your extra conversation data will appear in the "History" view of your Chat account like this:

Get Conversation Data

This function allows your page to directly call Smith's API with a known conversation UUID to fetch the data associated with this chat. You would normally do this at a later point in the page's life cycle once the conversation has been closed by the agent. This function will return the information associated with the conversation and the guest via en ES6 Promise (you may need a polyfill for some versions for Internet Explorer).

getConversationData(conversationId: string) -> Promise

window.SMITH = { };
window.SMITH.smithChatAccount="<your_smith_chat_account_id>";
var script = document.createElement("script");
script.async= !0;
script.type = "text/javascript";
script.onload = onScriptLoad;
script.src = "https://app.smith.ai/chat/widget-latest.js";
document.getElementsByTagName("HEAD").item(0).appendChild(script);

function onScriptLoad () {
  // Example:
  // Store smith conversation data on conversation close.
  var chat = window.SMITH.chat;

  // Wait for the conversation to close...
  chat.onConversationClosed(function(smithConversationId) {
    // Then request the conversation's data.
    chat
      .getConversationData(smithConversationId)
      .then(function(response) {
        // Once you have the data, save it via ajax (example requires jQuery)
        $.ajax({ url: 'your_api_url',
          type: 'POST',
          data: { 'smith-conversation-data': response.data },
        });
      })
      .catch(error => {
        console.log(error);
      });
  })
}

The response data contains many fields that may be useful. This includes, but is not limited to:

{
  guest: {
    city: "",
    company: "",
    country: "",
    current_url: "",
    email: "",
    first_name: "",
    guest_type: "",
    id: "",
    last_name: "",
    notes: "",
    phone: "",
    phone_formatted: "",
    state: "",
    street_address: "",
    zipcode: "",
  },
  time_closed: "",
  time_created: "",
  time_created_formatted: "",
  time_integrations_run: "",
  time_modified: "",
  time_modified_formatted: "",
  extra_data: { },
  ...
}

Questions? Contact us!

If you're already a Smith.ai client and need help, please email us at support@smith.ai or call us at (650) 727-6484 for assistance.

If you're not yet a Smith.ai client, please schedule a free consultation to get started with our live chat or email us at sales@smith.ai. We'll help you select the best plan to match your business’s growth goals and budget.

How did we do?

Outbound API Fields

Using the Outbound Call Request API

Contact