Live chat

The live chat widget is a chat window on your website. A visitor clicks the chat bubble, types a message, and the conversation shows in your inbox like any other conversation. In the product, the channel card for the widget is Website. An inbox of this type is a website inbox. You add 1 script to your pages, and the widget loads from your Hams domain.

In this page, {account_id} is the number of your account in the dashboard URL.

Before you start

You need these items:

• Edit access to the pages of your website, or a developer who has it.
• The domain of your website, for example example.com.
• Optional: a developer who can add code to the back end of your website. Identity validation needs it.

Add the inbox

The Next button stays off until Website Name and Website Domain have a value. If the system cannot create the inbox, it shows We were not able to create a website channel, please try again.

Put the script on your website

The script loads the widget. Copy it from the last step of the wizard. To find it again, open the inbox settings and click the Script tab above the preview.

The script has this shape. The values of BASE_URL and websiteToken are specific to your inbox.

<script>
  (function(d,t) {
    var BASE_URL="https://<your Hams domain>";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.hamsSDK.run({
        websiteToken: '<your website token>',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>

Paste the script into the HTML of your pages, inside the <body> tag. The widget shows on each page that has the script. If you use a site builder, paste the script in the section for custom code in the footer.

The Script tab also adds a window.hamsSettings line to the script. This line holds the values of Position:, Type:, and Launcher Title that you set in the builder. See Settings of the widget.

Settings of the widget

To open the settings, open Settings > Inboxes. Click Settings on the website inbox. The Settings tab shows the builder. A live view shows below the builder. The Preview tab of the live view shows the widget. The Script tab shows the script. Click Update to save your changes.

The generic tabs Collaborators, Business Hours, CSAT, and Bot Configuration work as in Inboxes and channels. A website inbox also has the tabs Pre Chat Form and Configuration.

Basic fields

Widget features

The Features check boxes are:

• Display file picker on the widget: shows the attachment button in the widget.
• Display emoji picker on the widget: shows the emoji button in the widget.
• Allow users to end conversation from the widget: the Hams widget has no button to end a conversation. Thus, this check box does not change the widget.
• Use inbox name and avatar for the bot: shows the inbox name and avatar on bot messages.

The file picker and the emoji picker are on in a new inbox. The header of the widget shows the heading, the tagline, and a close button. A line at the bottom of the widget shows Powered by HAMS.AI, with a link to the Hams website.

Channel preferences

The Enable conversation continuity via email toggle shows only when Hams support turns on Inbound Emails for your account.

Options in the script

You can set more options in the page code. Put a window.hamsSettings object before the script. The options are optional.

<script>
  window.hamsSettings = {
    position: 'left',
    type: 'expanded_bubble',
    launcherTitle: 'Chat with us',
    locale: 'en',
    darkMode: 'auto'
  };
</script>

Control the widget from your page

After the widget loads, the object window.$hams gives you these methods. The widget also sends the browser event hams:ready on window when it is ready. Run your calls after that event.

Example. This code sets the visitor after the widget is ready.

window.addEventListener('hams:ready', function () {
  window.$hams.setUser('user-1042', {
    name: 'Sara Ali',
    email: 'sara@example.com',
  });
  window.$hams.setCustomAttributes({ plan: 'pro' });
});

Custom attributes show on the contact or on the conversation in the dashboard.

Allowed domains and mobile apps

Open the Configuration tab of the inbox.

• Allowed Domains: enter the sites that can show the widget. Separate them with commas. Example: example.com, www.example.com. Click Update. If the field is empty, any site can show the widget. Add your domains for a production site.
• Enable widget in mobile apps: turn this on if you put the widget in an iOS or Android app. Mobile apps do not send a domain. Without this option, a domain restriction blocks them.

Identity validation

Identity validation makes sure that a visitor is who your website says. Without it, a person can call setUser with the identifier of another user in the browser console. Then that person sees the conversations of the other user.

To turn it on, you add a hash that your server makes for each user. The widget sends the hash with setUser, and the system checks it.

Example of the hash in Node.js:

const crypto = require('crypto');
const identifierHash = crypto
  .createHmac('sha256', process.env.HAMS_SECRET_KEY)
  .update(String(userId))
  .digest('hex');

If Require identity validation for all conversations is off, the system checks a hash only when the call has one. The system always rejects a wrong hash. The error is HMAC failed: Invalid Identifier Hash Provided.

Pre-chat form

A pre-chat form asks the visitor for details before the conversation starts. Open the Pre Chat Form tab of the inbox.

1. Turn on Enable pre chat form.
2. Enter a Pre chat message. The visitor sees it above the form.
3. In the field table, turn on each field that you want. Drag a row to change the order.
4. For each turned-on field, you can check Required. You can also change the Label and the Placeholder.
5. Click Update Pre Chat Form Settings.

The table lists 3 standard fields and all custom attributes of your account, for contacts and for conversations.

The widget does not show the form to a first-time visitor. The first message of the visitor starts the conversation directly. If the form is on and at least 1 field is on, the form shows in 2 cases:

• The visitor clicks Start a new conversation after an agent resolves the last conversation.
• The visitor clicks a campaign message.

The visitor must fill in the fields that you marked Required.

The form does not ask for details that the widget already has. If the contact has an email address, the form hides emailAddress. If the contact has a phone number, the form hides phoneNumber. If the contact has an email address, a phone number, or an identifier, the form hides fullName.

Business hours and reply time

Open the Business Hours tab of the inbox.

1. Turn on Enable business availability for this inbox.
2. Enter the Unavailable message for visitors.
3. Select the timezone in Select timezone.
4. For each day, turn on Enable availability for this day. Enter the hours, or select All-Day.
5. Click Update business hours settings.

When a visitor sends a message outside the hours, the system replies with the unavailable message. It does not send the message if an agent replied in the last 5 minutes. The system sends it 1 time each day for each conversation.

The Set Reply time field on the Settings tab is separate. It is the typical reply time of the inbox. The preview of the builder uses it.

Collect an email address

If Enable email collect box is on, the system asks each new visitor for an email address. The visitor sends a first message. Then the widget shows Give the team a way to reach you. It also shows Get notified by email with an email input. The system asks 1 time for each conversation. It does not ask when the contact has an email address.

The system saves the email address on the contact. Agents see it in the contact details.

Continue by email

If Enable conversation continuity via email is on and the contact has an email address, the conversation can continue over email. The reply of an agent goes to the email address of the visitor. The reply of the visitor to that email goes back into the same conversation.

The email address can come from the email collect box, the pre-chat form, or setUser. The name in the email header depends on Sender name. If you set a business name, the email shows it.

Attachments and emoji

If the file picker is on, a visitor can click the attachment button. The visitor can also paste a file from the clipboard into the message box.

• The default limit is 40 MB for each file. The administrator of the Hams installation can change the limit. If a file is too large, the widget shows File exceeds the {limit} attachment limit, where {limit} is the maximum size.
• The file picker accepts images, audio, video, PDF, plain text, CSV, JSON, XML, and RTF files. It also accepts Word, Excel, PowerPoint, and OpenDocument text files, and ZIP, 7z, RAR, and TAR archives.

The attachment button hides when the visitor has typed text in the message box. The emoji picker adds an emoji to the message.

What agents see

A website conversation shows in the conversation list with the name of the inbox. An agent replies from the usual reply box. Replies show in the widget in real time.

In the contact panel, the Conversation Details section shows data about the visit:

• Initiated from: the page where the visitor started the conversation.
• Initiated at: the date and time that the conversation started.
• Browser, Operating System, Browser Language, and IP Address.

The contact card shows the name, email, and phone from the pre-chat form or setUser. It also shows the custom attributes, the conversation custom attributes, and the labels that your page code set.

After an agent resolves the conversation, the visitor sees Start a new conversation. If the contact has an email address, the widget also shows Request a conversation transcript. The system emails the transcript to the visitor. To let the visitor write in the same conversation, turn on Allow messages after conversation resolved.

If the conversation uses CSAT, the visitor sees Rate your conversation. See Inboxes and channels.

What the widget does not do

• The widget does not show the reply time or the online status of the team. The header shows only the heading, the tagline, and the close button.

Related

• Inboxes and channels
• Conversation cycles
• Overview