Setup

Install the Missive chat widget on your website.

Missive Live Chat works on top of Twilio’s Conversations API. Before creating your chat account, you first need to sign up for a Twilio account to get your Twilio credentials.

Once it's done, head over to your Accounts settings on Missive and add a Missive Live Chat account.

Get your Twilio credentials

Both your Account SID and Auth Token are available in your Twilio dashboard page:

Locate your SID and Auth Token on Twilio dashboard

Install on your website

To install the chat on your website, select the Setup page where you can copy the HTML code snippet that you need to paste into your website.

Missive Live Chat setup

Customization

Configuration

Here’s an example of all the available options and their default value. Most of them can be set from the Setup page of your Missive Live Chat account settings and will be instantly applied to all your chat widget instances.

If an option is set both from your Setup page and in your HTML, the HTML one will be used.

missive-chat-config.html

<!-- Missive Chat -->
<script>
  (function(d, w) {
    w.MissiveChatConfig = {
      id: '[MISSIVE-CHAT-ACCOUNT-ID]',
      chat: {
        position: 'bottom-right',
        hidden: false, // When true, Missive Live Chat can be opened with JS API only
        name: "", // Defaults to your Missive Live Chat account username on Missive
        avatarUrl: "", // Defaults to your Missive Live Chat account avatar on Missive
        hideWhenOffline: false,
        hideBranding: false, // Only works on Productive and Business plans
        showOnlineStatus: true,
        showAvatars: true,
        showNames: true,
        rememberOpenState: true, // Automatically open the chat widget if it was open when the user last visited the page
        variables: {
          'background-color': '#fff',
          'badge-background-color': '#f23131',
          'badge-border-radius': '100%',
          'badge-box-shadow': '0 1px 2px rgba(0,0,0, .2)',
          'badge-color': '#fff',
          'badge-size': '24px',
          'border-color': 'rgba(0,0,0, .05)',
          'border': 'solid 1px rgba(0,0,0, .06)',
          'box-shadow': '0 5px 30px rgba(0,0,0, .1)',
          'bubble-dark-color': 'var(--main-color)',
          'bubble-light-color': '#f5f5f5',
          'button-border-radius': '10em',
          'close-button-color': '#fff',
          'closed-border-radius': '30px',
          'font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"',
          'font-size': '15px',
          'header-opened-background-color': 'var(--main-color)',
          'header-subtitle-text-color': 'rgba(255,255,255, .65)',
          'header-title-text-color': '#fff',
          'height': '600px',
          'light-text-color': '#7b7c7f',
          'main-color': '#2866D1',
          'margin': '20px',
          'max-height': 'calc(100% - 40px)',
          'max-width': 'calc(100% - 40px)',
          'opened-border-radius': '10px',
          'status-connecting-color': '#fdd157',
          'status-offline-color': '#f23131',
          'status-online-color': '#00b351',
          'text-color': '#34363a',
          'transition-duration': '225ms',
          'transition-easing': 'cubic-bezier(.4, .0, .2, 1)',
          'width': '350px',
        },
      },

      // Upon connection issues, visitors are invited to contact you through these channels.
      // It will be added after the `messages.error` message.
      support: {
        email: "",
        phone: "",
      },

      // See “Identify and verify users” section in your Missive Live Chat account Setup page.
      user: {
        email: "",
        name: "",
        digest: "",
        avatarUrl: "",
      },

      visitor: {
        askName: true,
        requireName: false,
        askEmail: true,
        requireEmail: true,
        requireConsent: false,
      },

      // Attach custom data to messages
      meta: {},

      messages: {
        // Chat messages (string or array of strings)
        //
        // - Each string will appear in its own chat bubble
        // - URLs are clickable (i.e. 'On our website: https://missiveapp.com')
        // - Links can be formatted (i.e. 'On our {{ link:https://missiveapp.com website }}')
        welcome: "Hi there! 👋\n\nThe team will reply as soon as possible.",
        help: "How can we help?",
        identify: "First, identify yourself.",
        error: "Sorry, there is an issue connecting to our chat. Please check your Internet connection and try again.",

        // UI messages (string only)
        title: "Chat with us",
        online: "We’re online",
        offline: "We’re offline",
        connecting: "Connecting…",
        chat: "Message…",
        newMessage: "New message!",
        newMessages: "New messages!",
        internet: "Can’t send messages offline.",
        identifyName: "Name",
        identifyEmail: "Email",
        identifySubmit: "Submit",
        identifySkip: "Skip",
        identifyRequired: "Required field",
        identifyThanks: "Thanks",
        identifyConsent: "I accept this website privacy policy and terms of use.",
      },
    };

    var s = d.createElement('script');
    s.async = true;
    s.src = 'https://webchat.missiveapp.com/' + w.MissiveChatConfig.id + '/missive.js';
    if (d.head) d.head.appendChild(s);
  })(document, window);
</script>
<!-- /Missive Chat -->

JavaScript API

Missive Live Chat provides a JS API to let you programatically interact with the widget on your website.

It is required to wrap any usage of window.MissiveChat inside or after the onReady callback that you can define on your configuration object.

missive-chat-api.html

<!-- Missive Chat -->
<script>
  (function(d, w) {
    w.MissiveChatConfig = {
      id: '[MISSIVE-CHAT-ACCOUNT-ID]',
      onReady: function() {
        // Automatically opens the chat widget
        w.MissiveChat.open()
      },
      onVisitorIdentified: function({ name, email }) {},
      onChatStarted: function({ name, email }) {},
      onNewMessage: function(body) {},
      onOpen: function() {},
      onClose: function() {},
    };

    var s = d.createElement('script');
    s.async = true;
    s.src = 'https://webchat.missiveapp.com/' + w.MissiveChatConfig.id + '/missive.js';
    if (d.head) d.head.appendChild(s);
  })(document, window);
</script>
<!-- /Missive Chat -->

Method	Description
open()	Opens the chat widget popup window.
close()	Closes the chat widget popup window.
showButton()	Shows the chat widget button. This doesn’t open the chat widget popup window, it only applies to the chat button.
hideButton()	Hides the chat widget button. This doesn’t close the chat widget popup window, it only applies to the chat button. Set chat: { hidden: true } in config to hide by default.
setUser({ name, email, digest })	Identify a logged in user. See “Identify and verify logged-in users” documentation below.
setMeta({})	Attach custom data to messages. Overwrites meta with the given object. language, platform and browser are always included and cannot be removed.
addMeta({})	Add custom data to your messages. Adds given object to the meta object without overwriting already set values.
setVariables({})	Update the styling variables.

Attach data to messages

Missive Live Chat messages include data to provide information about the person currently chatting with you. This data is displayed in the Contacts sidebar and will use the last message data.

Defaults

By default, each message will include language, platform and browser.

Default data attached to messages

Custom

Custom data can be provided by setting a meta object on the w.MissiveChatConfig object or via the JavaScript API (see above). A simple key/value object is expected.

set-meta.js

MissiveChat.setMeta({
  paid_user: 'true',
  member_since: '2018',
})

Custom data attached to messages

Identify and verify logged-in users

Identify

To identify your logged-in users, you must define a user key on the w.MissiveChatConfig object. The user object must have an email and optionally a name property.

identify-example.js

w.MissiveChatConfig = {
  "id": "c3a1b3de-5e3f-4283-baaa-8e1d63fea126",
  "user": {
    "name": "Jane Doe",
    "email": "[e-mail]"
  }
}

Just like visitors entering a name/email themselves, these messages will be marked as [Unverified] on Missive. That is so you’re aware that anyone could provide fake info.

Verify

You can verify your users by adding a digest property to the user object. The digest must be generated from the Secret key available in your Missive chat settings using the user’s email address as the encrypted content.

Get your secret key in your chat account settings:

Get your secret key in your chat account settings

Here’s how to encrypt with Ruby, Node.js and PHP. Other languages have equivalent functions.

ruby-hmac.rb

# Ruby
digest = OpenSSL::HMAC.hexdigest(
  'sha256',
  'e72bvc5171hf23982d05j610514gfe2m',
  '[e-mail]'
)

node-hmac.js

// Node.js
digest = crypto.createHmac(
  'sha256',
  'e72bvc5171hf23982d05j610514gfe2m'
).update('[e-mail]').digest('hex')

php-hmac.php

// PHP
digest = hash_hmac(
  'sha256',
  '[e-mail]',
  'e72bvc5171hf23982d05j610514gfe2m'
);

You must then define this computed digest in the user object of the w.MissiveChatConfig object.

verified-user-config.js

// digest == 'd78c55fe6579a12831b5e0cdc5765ff7d110fefb2e386a43067accb51ce242f2'
w.MissiveChatConfig = {
  "id": "c3a1b3de-5e3f-4283-baaa-8e1d63fea126",
  "user": {
    "name": "Jane Doe",
    "email": "[e-mail]",
    "digest": "d78c55fe6579a12831b5e0cdc5765ff7d110fefb2e386a43067accb51ce242f2"
  }
}

Messages marked with [Cannot verify]? That means that while a digest was provided, it doesn’t match with the one generated by our server. Someone may be trying to impersonate one of your users or your encryption is incorrect.