The Atlas JavaScript SDK is the code that controls the Atlas widget on your website or app. With it, your developers decide when the chat starts, who the customer is, what the widget looks like and when session recording runs.

You don't need to know how to code to use this article. Each section explains what the code does and when you'd want it, so you can pick what you need and hand the code to your developers.

Related articles:
• How to install Atlas on your website or app: Add the install snippet and copy your app ID.
• How to enable customer (user) authentication: Create the user hash that protects your customers' identity.
• How to configure the chat widget: Change the widget's look and behavior without code.

What you can do with the SDK

I want to…	Use
Load and start the widget	The install snippet and `start`
Remove the widget from a page	`shutdown`
Tell Atlas who the customer is	`identify`
Load the widget without the chat	`chat.enabled: false`
Open the chat from my own button	`chat.openWindow()`
Hide or show the chat bubble	`chat.hideBubble()` and `chat.showBubble()`
Open the chat with a message already typed	`showNewChat`
Move the bubble to another corner	`position` and `offset`
Show the chat only in some countries	`access.countries`
Change the widget's colors, size or titles	Styling options
Record sessions only on some pages	`recording.start()` and `recording.stop()`
Open the Help Center, a category or an article	Help Center methods
Start a specific chatbot	`triggerChatbot`

Requirements:
Atlas must be installed on your site or app. Copy the install snippet from "App Configuration > Getting Started > Installation", because it already includes your workspace's app ID.

Start and stop the widget

Start the widget

The install snippet loads Atlas on the page. Add it before the </head> tag on every page where the widget should appear. YOUR_APP_ID is your workspace's app ID, which Atlas fills in for you on the installation page.

(() => {
  "use strict";
  var t,
    e = {
      appId: "YOUR_APP_ID",
      v: 2,
      q: [],
      call: function () {
        this.q.push(arguments);
      },
    };
  window.Atlas = e;
  var n = document.createElement("script");
  (n.async = !0), (n.src = "https://app.atlas.so/client-js/atlas.bundle.js");
  var s = document.getElementsByTagName("script")[0];
  null === (t = s.parentNode) || void 0 === t || t.insertBefore(n, s);
})();

Then start the widget:

window.Atlas.call("start");

Most options in this article go inside this start call, so you set them when the widget loads.

Stop the widget

Removes the widget from the page, for example on pages where you don't offer support.

window.Atlas.shutdown()

Send Atlas requests through your own server

If your company routes third-party requests through its own servers, set proxyUrl to your server's address. Atlas then sends its API requests there instead of directly to Atlas.

window.Atlas.proxyUrl = 'https://api.yourserver.com/api/v1/atlas_proxy'

Tell Atlas who the customer is

Identify the customer

When a customer is logged in to your app, the identify call tells Atlas who they are. Agents then see the customer's name and details in every conversation, instead of an anonymous visitor.

window.Atlas.call("identify", {
  userId: '123',
  name: 'John Doe',
  email: 'john@example.com',
  phoneNumber: '+14153101234'
 })

Important:
Add a userHash to the identify call so no one can pretend to be another customer. Your server creates it with your secret key. To set it up, read How to enable customer (user) authentication.

Add more customer details

Use fields for standard details, like job title or address, and customFields for your own Atlas custom fields. Create the custom fields in Atlas first, then use their keys here.

  window.Atlas.call("identify", {
    userId: '123',
    name: 'John Doe',
    email: 'john@example.com',
    phoneNumber: '+14153101234',
    userHash: '39d97cc77da23fb515d37e6cea066692a799cf85d1330489e2c',
    fields: {
        title: 'CEO',
        department: 'Sales',
        photo: 'https://cdn.filestackcontent.com/2dq5VghRlipv4aWAPAUE',
        street1: '1 main street',
        street2: '#123',
        city: 'San Francisco',
        country: 'US',
        postalCode: '94102',
    },
    customFields: {
        'field1_key': 1,
        'field2_key': 'B',
        'field3_key': '2021-01-23',
    }
})

Add the customer's company

Use account to link the customer to their company, so agents see which company the customer belongs to.

  window.Atlas.call("identify", {
    userId: '123',
    name: 'John Doe',
    email: 'john@example.com',
    phoneNumber: '+14153101234',
    userHash: '39d97cc77da23fb515d37e6cea066692a799cf85d1330489e2c',
    account: {
        name: 'Acme Inc',
        email: 'support@acmeinc.com',
        website: 'https://acmeinc.com',
        externalId: 'account_id',
        monthlySpend: '999',
        industry: 'Computers',
        customFields: {
          'account_field1_key': '1',
          'account_field2_key': 'A',
          'account_field3_key': '2023-01-12',
        }
    }
})

Control when the chat runs

By default, the chat starts with the widget. Use these options to load the widget without the chat, for example to record sessions on a page where you don't offer chat.

Load the widget without the chat

window.Atlas.call("start", {
  chat: {
    enabled: false
  }
})

Start the chat later

window.Atlas.chat.start()

Stop the chat

window.Atlas.chat.stop()

Control the chat bubble

The bubble is the round button customers click to open the chat. Hide it when you'd rather open the chat from your own button or link.

Hide the bubble when the widget loads

// Hide the bubble on startup
window.Atlas.call("start", {
  chat: {
    hideBubble: true
  }
})

Open the chat from your own button

window.Atlas.chat.openWindow()

Hide or show the bubble at any time

⟦ HTML BLOCK 17 · Code block ⟧

⟦ HTML BLOCK 18 · Code block ⟧

Don't open the chat when an agent replies

By default, the chat window opens when a new agent message arrives. Set openIncoming to false to keep it closed, for example to show an unread counter in your own design instead.

⟦ HTML BLOCK 19 · Code block ⟧

React to new messages and to the window opening

Callbacks let your app do something when an agent sends a message (onNewAgentMessage) or when the chat window opens or closes (onWindowVisibilityChange). For example, update your own unread counter.

⟦ HTML BLOCK 20 · Code block ⟧

Open the chat with a message already typed

Opens a new chat with your text filled in, for example "I need help with billing" from a link on your billing page.

Atlas.call('showNewChat', { text: 'Hello' })

Position and layout

Move the bubble

position sets the corner and offset sets the distance from the edges, in pixels.

window.Atlas.call("start", {
    chat: {
        'position': 'bottomLeft',
        'offset': [20, 21]
    }
});

Run your own action from the layout menu

If your widget's layout menu has an option that should trigger something in your app, register a callback with the option's key. In this example, the hello option shows an alert.

window.Atlas.call("start", {
    callbacks: {
        hello: () => alert('hello!')
    },
})

Change settings after the widget loads

Use update to change chat settings without reloading the page.

window.Atlas.call('update', {
    'chat': {
        'position': 'bottomLeft',
        'offset': [80, 21]
    }
});

Show the chat only in some countries

Show the chat only in specific countries

Atlas.call('start', {
    access: { countries: ['US'] },
})

Hide the chat in specific countries

Add inverseCountries: true to hide the chat in the listed countries instead.

Atlas.call('start', {
    access: {
        countries: ['US'],
        inverseCountries: true,
    },
})

Style the widget

Change the widget's colors, size, launcher label, title, subtitle and logo from code. To change the widget without code, read How to configure the chat widget.

Atlas.call('start', {
  chat: {
    brandColor: 'linear-gradient(180deg, pink 0%,gold 84%)', // or color '#ff0000'
    textColor: 'light',
    maxHeight: '50%', // can be any CSS unit
    maxWidth: 300, // if number is passed it will be interpreted as pixels
    launcher: {
      label: 'Welcome',
    },
    widget: {
      title: 'H1',
      subtitle: 'H2',
      // can be the http(s) url as well
      logo: 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==',
    },
  },
})

Control session recording

By default, Atlas records sessions on every page with the install snippet. Use these options to record only on some pages, for example to skip pages with sensitive information.

Don't record when the widget loads

window.Atlas.call("start", {
  recording: {
    enabled: false
  }
})

Start recording on a page

window.Atlas.recording.start()

Stop recording on a page

window.Atlas.recording.stop()

Get the session ID

Returns the current session's ID, so you can send it to error monitoring tools, like Sentry, and match an error to its recording.

window.Atlas.recording.getSessionId()

Open the Help Center

Open your Help Center inside the widget from anywhere in your app, for example from a "Help" link.

Open the Help Center home:

window.Atlas.call('openHelpCenter')

Open a category:

window.Atlas.call('openArticlesCategory', 'category')

Open a specific article. Use the article's slug, the end of its URL:

window.Atlas.call("openArticle", {
    "slug": "703242-session-recording"
});

Open a search with your text:

window.Atlas.call('openArticlesSearch', 'how to setup helpcenter')

Start a chatbot

Starts a specific chatbot, for example when a customer clicks "Talk to sales". Replace CHATBOT_KEY with the "Chatbot Key" from the chatbot's entry block.

window.Atlas.call("triggerChatbot", "CHATBOT_KEY");

Important:
In the chatbot's setup, "Start Conversation" must be set to "Via SDK" for this to work.

FAQs & Troubleshooting

Do I need a developer to use this?

Yes. The SDK is code that goes into your website or app. Share this article with whoever maintains it.

Where do I find my app ID?

In "App Configuration > Getting Started > Installation" . The install snippet there already includes it.

Why doesn't Atlas show the customer's name?

The identify call is missing or runs before the install snippet. Add it after the install snippet, once the customer is logged in.

Was this article helpful?

Table of contents

How to use the Atlas JavaScript SDK

Overview