Custom Addon Builder

In addition to simply embedding your website in Lime Connect, it’s also possible to use the Custom Add-on Frontend API to communicate between the Message Center and your application. For example, it’s possible to get real-time data from Lime Connect or update Lime Connect’s contact information from your application.

Getting started

To define a custom add-on, go to Settings > Add-ons > Custom Add-ons and click on the Add button.

You can then specify the name of the add-on, the URL where it is hosted, and the URL of the icon that will be displayed in the conversation details sidebar. It is recommended to use an icon with a 1:1 aspect ratio, a transparent background and no padding for optimal results.

Content policy

To ensure cross-origin usage of your add-on, set a frame-ancestors Content-Policy directive. Additional information can be found at the following link: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors

Example:

plain text
Content-Security-Policy: frame-ancestors https://app.lime-connect.com;

Local development

If the content policy is set correctly, you can develop your add-on on a local server and use its URL, such as 127.0.0.1.

Life-cycle

Custom add-ons are loaded as soon as the operator opens a conversation. Once the operator leaves or changes the conversation, the add-on is unmounted, resulting in the loss of its state.

Listening to Message Center events

Communication with your add-on will be done through the JavaScript postMessage API. Upon loading your add-on, we will provide you with initial events, including contact information, conversation information, operator information and the transcript. Continue to listen for incoming events using the postMessage API to receive real-time data.

From version 2 onwards, we will only start sending events once we have received a “ready” action.

Example:

javascript
// Start to listen for incoming events
window.addEventListener("message", (message) => {
  if (message.origin !== "https://app.lime-connect.com") return;

  switch (message.data.name) {
    case "contact_information":
      setContactInfo(message.data.payload);
      break;
  }
});

// Required for v2+
window.parent.postMessage({ name: "ready", payload: {} }, "https://app.lime-connect.com");

Triggering Message Center actions

Your add-on can trigger actions within the Message Center, such as replacing the chat input text or displaying a toast.

Example:

javascript
window.parent.postMessage(
  {
    name: "toast",
    payload: {
      message: "Hello from the add-on!",
      status: "warning",
    },
  },
  "https://app.lime-connect.com"
);

Events

Transcript

This event is triggered once when the add-on becomes active and every time a new text message is added to the conversation.

It includes all the messages the operator can see, depending on how much they’ve scrolled back in the conversation’s history.

typescript
type Sender = {
  type: "contact" | "operator";
};

type TextMessage = {
  type: "message";
  body: string;
  textFormat: "markdown_v1" | "plain_text";
  sender: Sender;
};

type TranscriptEvent = {
  name: "transcript";
  payload: {
    transcript: TextMessage[];
  };
};

const example: TranscriptEvent = {
  name: "transcript",
  payload: {
    transcript: [
      {
        sender: { type: "contact" },
        body: "Hello, I have a question about your product.",
        textFormat: "plain_text",
        type: "message",
      },
      {
        sender: { type: "operator" },
        body: "Hello, how can I help you?",
        textFormat: "plain_text",
        type: "message",
      },
    ],
  },
};

Contact information

This event is triggered once when the add-on becomes active and every time the contact information is updated.

Note that the contact information may be null if not specified by the operator or the contact.

typescript
type ContactEvent = {
  name: "contact_information";
  payload: {
    id: string;
    name: string | null;
    email: string | null;
    locale: string | null;
    mobileNumber: string | null;
    phoneNumber: string | null;
    salutation: "mr" | "ms" | "pr" | "prof" | null;
    street: string | null;
    city: string | null;
    country: string | null;
    company: string | null;
    gender: "m" | "f" | "d" | null;
    customFieldData: Record<string, string | string[] | null>;
  };
};

const example: ContactEvent = {
  name: "contact_information",
  payload: {
    id: "1111",
    name: "Jane Doe",
    email: "jane@example.com",
    locale: "en_US",
    mobileNumber: "+325920392947",
    phoneNumber: "+325920392947",
    salutation: "ms",
    street: "Im Mediapark 8",
    city: "Köln",
    country: "DE",
    company: "Lime Connect",
    gender: null,
    custom_field_data: null,
  },
};

Conversation

This event is triggered once when the add-on becomes active and every time the conversation information is updated.

It contains meta information about the current conversation.

Note that some information may be null.

typescript
type ConversationEvent = {
  name: "conversation_information";
  payload: {
    id: string | null;
    topics: { text: string }[];
    locale: string | null;
    subject: string | null;
    customFieldData: Record<string, string | string[] | null>;
    widget: {
      id: string;
      name: string;
    };
  };
};

const example: ConversationEvent = {
  name: "conversation_information",
  payload: {
    id: "1111",
    topics: [{ text: "Support" }, { text: "Support" }],
    locale: "en_US",
    subject: "IT Support",
    customFieldData: null,
    widget: {
      id: "111",
      name: "My widget",
    },
  },
};

Operator

This event is triggered once when the add-on becomes active and every time the operator information is updated.

typescript
type OperatorEvent = {
  name: "operator_information";
  payload: {
    id: string;
    name: string;
    email: string;
    locale: string;
  };
};

const example: OperatorEvent = {
  name: "operator_information",
  payload: {
    id: "1111",
    name: "Jane Doe",
    email: "jane@example.com",
    locale: "en_US",
  },
};

JWT Token

This event is emitted in response to the generate_jwt_token action, providing a JWT token for authentication purposes.

typescript
type JwtTokenEvent = {
  name: "jwt_token";
  payload: { type: 'success', token: string } | { type: 'error', error: string };
};

const example: JwtTokenEvent = {
  name: "jwt_token",
  payload: {
    type: "success",
    token: "xxxxxxxxx...",
  },
};

Actions

Actions refer to events that can be triggered by the add-on to perform specific tasks in the Message Center.

Generate JWT Token

Request a new JWT token from the Message Center. Upon success, a new jwt_token event will be emitted with the fresh token.

typescript
type GenerateJwtTokenAction = {
  name: "generate_jwt_token";
  payload: {};
};

const example: GenerateJwtTokenAction = {
  name: "generate_jwt_token",
  payload: {},
};

Replace chat input

Send text to the operator’s chat input.

typescript
type ReplaceChatInputAction = {
  name: "replace_chat_input";
  payload: {
    textFormat: "plain_text" | "markdown_v1";
    message: string;
  };
};

const example: ReplaceChatInputAction = {
  name: "replace_chat_input",
  payload: {
    textFormat: "markdown_v1",
    message: "For more information [check out Lime Connect](https://app.lime-connect.com).",
  },
};

Toast

Display a toast.

typescript
type ToastAction = {
  name: "toast";
  payload: {
    status: "info" | "error" | "success" | "warning";
    message: string;
  };
};

const example: ToastAction = {
  name: "toast",
  payload: {
    status: "error",
    message: "An unexpected error has occurred.",
  },
};

Update contact information

Partially update contact information.

typescript
type UpdateContactAction = {
  name: "update_contact_information";
  payload: Partial<{
    name: string | null;
    email: string | null;
    locale: string | null;
    mobileNumber: string | null;
    phoneNumber: string | null;
    salutation: "mr" | "ms" | "pr" | "prof" | null;
    street: string | null;
    city: string | null;
    country: string | null;
    company: string | null;
    gender: "m" | "f" | "d" | null;
    customFieldData: Record<string, string | string[] | null>;
  }>;
};

const example: UpdateContactAction = {
  name: "update_contact_information",
  payload: {
    name: "Jane Doe",
    customFieldData: { "dd23-4dfd-f23f-s3rf": "Hello world!" },
  },
};

Update conversation information

Update conversation information.

typescript
type UpdateConversationAction = {
  name: "update_conversation_information";
  payload: {
    customFieldData: Record<string, string | string[] | null>;
  };
};

const example: UpdateConversationAction = {
  name: "update_conversation_information",
  payload: {
    customFieldData: { "dd23-4dfd-f23f-s3rf": "Hello world!" },
  },
};