# Setup

Missive Live Chat works on top of Twilio’s [Conversations API](https://www.twilio.com/messaging/conversations-api). Before creating your chat account, you first need to [sign up](https://www.twilio.com/try-twilio) 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:

<div data-with-frame="true"><img src="/files/nbn8v8PTKpSsMz5ffMdu" alt="Locate your SID and Auth Token on Twilio dashboard"></div>

### 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.

<div data-with-frame="true"><img src="/files/d6e0c055ee1ec930193b6e254348f0a71c687ca2" alt="Missive Live Chat setup"></div>

### 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.

{% code title="missive-chat-config.html" %}

```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 -->
```

{% endcode %}

#### 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.

{% code title="missive-chat-api.html" %}

```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 -->
```

{% endcode %}

| 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](/files/MzX0j7BtVrnaEeKogk7p)

**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.

{% code title="set-meta.js" %}

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

{% endcode %}

![Custom data attached to messages](/files/0c9f6158b375042e4a8dfaa350991bd119a18bce)

### 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.

{% code title="identify-example.js" %}

```javascript
w.MissiveChatConfig = {
  "id": "c3a1b3de-5e3f-4283-baaa-8e1d63fea126",
  "user": {
    "name": "Jane Doe",
    "email": "jane@acme.com"
  }
}
```

{% endcode %}

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](/files/1a3f72ca634a433c803bbb9e6360a03d4970423f)

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

{% code title="ruby-hmac.rb" %}

```ruby
# Ruby
digest = OpenSSL::HMAC.hexdigest(
  'sha256',
  'e72bvc5171hf23982d05j610514gfe2m',
  'jane@acme.com'
)
```

{% endcode %}

{% code title="node-hmac.js" %}

```javascript
// Node.js
digest = crypto.createHmac(
  'sha256',
  'e72bvc5171hf23982d05j610514gfe2m'
).update('jane@acme.com').digest('hex')
```

{% endcode %}

{% code title="php-hmac.php" %}

```php
// PHP
digest = hash_hmac(
  'sha256',
  'jane@acme.com',
  'e72bvc5171hf23982d05j610514gfe2m'
);
```

{% endcode %}

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

{% code title="verified-user-config.js" %}

```javascript
// digest == 'd78c55fe6579a12831b5e0cdc5765ff7d110fefb2e386a43067accb51ce242f2'
w.MissiveChatConfig = {
  "id": "c3a1b3de-5e3f-4283-baaa-8e1d63fea126",
  "user": {
    "name": "Jane Doe",
    "email": "jane@acme.com",
    "digest": "d78c55fe6579a12831b5e0cdc5765ff7d110fefb2e386a43067accb51ce242f2"
  }
}
```

{% endcode %}

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://missiveapp.com/docs/core-features/connected-accounts/other-channels/live-chat/setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.