Official Userlike Messenger API

Install

npm install @userlike/messenger

ES modules

import { createMessenger } from '@userlike/messenger';

commonjs

const { createMessenger } = require('@userlike/messenger');

AMD loader (requirejs)

require(['userlike-messenger'], function (userlike) {
  userlike.createMessenger({ ... });
});

script tag

<!-- 
unpkg is an open source project. It's not affiliated with Userlike. Use it to quickly and easily load 
messenger api without bundling it yourself. We highly advise against using unpkg for production.
-->
<script src="https://unpkg.com/@userlike/messenger/dist/browser/index.min.js"></script>
<script>
  UserlikeMessenger.createMessenger({ ... });
</script>

---

Usage

See examples for further details on how to use createMessenger.

Usage with typescript

See the typescript playground.

Usage with javascript

See the javascript playground

Usage with react + typescript

See the react playground.

Examples

Create the API

import { createMessenger, v1 } from "@userlike/messenger";

async function createApi(): Promise<v1.Api> {
  const result = await createMessenger({
    version: 1,
    widgetKey: "YOUR_WIDGET_SECRET",
  });

  if (result.kind === "error") throw new Error(result.error);

  const { api } = result.value;

  if (api === null) {
    throw new Error(
      "api reached end-of-life, please check documentation and upgrade."
    );
  }

  return api;
}

Create/destroy messenger

async (api: v1.Api) => {
  await api.mount();
  await api.unmount();
};

Change visibility

// Hide button and notifications
(api: v1.Api) =>
  api.setVisibility({
    main: true,
    button: false,
    notifications: false,
  });

// Show everything
(api: v1.Api) =>
  api.setVisibility({
    main: true,
    button: true,
    notifications: true,
  });

Clear user session / Logout

(api: v1.Api) => api.logout();

Maximize/Minimize

async (api: v1.Api) => {
  await api.maximize();
  await api.minimize();
};

Set custom data

(api: v1.Api) =>
  api.setCustomData({
    test: "test data",
  });

Set contact info

(api: v1.Api) =>
  api.setContactInfo({
    name: "Foo Bar",
    email: "foobar@example.com",
  });

Listen to changes

const subscription = api.state$.subscribe({
  next: (state) => console.log("next", state),
  complete: () => console.log("complete"),
});

subscription.unsubscribe();

You can use rxjs, or other streaming libraries:

import * as Rx from "rxjs";
import * as $ from "rxjs/operators";
import { v1 } from "@userlike/messenger";

const foo = Rx.pipe(
  api.state$,
  $.filter(({ state }) => state !== v1.MessengerState.Hidden)
);

const bar = Rx.pipe(api.state$, $.map(v1.getUnreadMessageCount));

Error handling

Messenger API never throws an error. Instead it returns an ActionResult which represents either a successful outcome or an erroneous outcome. In technical terms, ActionResult is a tagged union of ActionSuccess and ActionError, similar to Rust's Result<E, T>.

It's important to notice that the API function won't throw an error by itself, but you need to handle the Action Result and throw an error by yourself as you need it.

Versioning

Userlike Messenger API follows relatively short cycles of deprecations and end of lifes. The API versioning is designed in such a way to force its consumers to be prepared and to plan for an end-of-life situation. When end-of-life date is reached. that version of the API becomes unavailable; which is reflected in Typescript types.

We highly suggest you to use Typescript to consume Userlike Messenger API so to be able to handle unhappy code paths safely.

Dates

• v1
  Deprecation: 2025-08-01
  End-of-life: 2026-08-01