Skip to main content
Customise chat

​
General customization

You can customize the chat widget to match your brand and user experience. You can change various aspects of the chat widget including both the appearance and behavior. 
Plain.init({
  appId: '<YOUR_CHAT_APP_ID>',

  // Optional. Hides the launcher, you can manually show it by calling `Plain.open()` (default: false)
  hideLauncher: false,

  // Optional. A collection of links shown on the Welcome screen
  links: [
    {
      // Optional, supported icons are:
      //   'bell',
      //   'book',
      //   'bug',
      //   'bulb',
      //   'chat',
      //   'integration',
      //   'discord',
      //   'email',
      //   'slack',
      //   'link',
      //   'pencil',
      //   'send',
      //   'support',
      //   'error'
      icon: 'book', 
      text: 'View our docs',
      url: 'https://www.plain.com/docs',
    },
  ],

  // Optional. The entry point of the Chat.
  entryPoint: {
    // Type is either 'default' or 'chat'. 'default' will open the intro screen, 'chat' opens up straight into a chat.
    type: 'chat',
    //  Optional. The external ID of which chat to open. If not provided it will default to the last conversation the user had
    externalId: 'example_external_id',
    // Optional. Prevents the user from going back to the intro screen to start a new chat
    singleChatMode?: false,
  },

  // Optional. Lets you specify which HTML element to insert the chat into.
  // When specified, launcher will be hidden by default.
  embedAt: '#embed',

  // Optional. Hides the 'Powered by Plain' branding
  hideBranding: false,

  // Optional. The color scheme of the Chat, is either 'auto', 'light', or 'dark'
  // 'auto' uses the user's browser preference to decide between light and dark mode (default: 'auto')
  theme: 'light',

  // Optional. Various styling options
  // Colors can also be passed in this format { light: '#FFFFFF', dark: '#000000' }. Based on the theme chosen by you or browser preference
  style: {
    brandColor: '#22C55E'; // This will be used in various places in the chat widget such as the primary chat button and send message button
    launcherBackgroundColor: '#000000'; // These can also be passed in this format { light: '#FFFFFF', dark: '#000000' }
    launcherIconColor: '#FFFFFF';
  }

  // Optional. Logo which is shown in the header of the chat intro screen.
  // If you have uploaded a logo in your chat settings, this setting will take priority over that.
  logo: {
    // url to get the logo from
    url: 'http://example.com';
    // Optional. Alt text which is displayed on hover of the logo
    alt: 'An example logo';
  };

  // Optional. Position of the chat widget when it is floating.
  // See https://developer.mozilla.org/en-US/docs/Web/CSS/position for more information - only bottom and right are supported
  position: {
    right: '10px',
    bottom: '10px',
  }

  // Optional. Allows you to set fields for the threads which are created from chats
  threadDetails: {
    // See the data model documentation [asdasd](/chat/customization#all-threads) for more information on these fields
  };

  // Optional. Lets you customize the buttons which are used to start a new chat on the intro screen
  chatButtons: [
    // See the chat buttons documentation for more information on these fields
  ];
});

​
Enhance your chat flows with Plain’s data model

Plain’s chat widget is designed to be flexible and powerful. You can use Plain’s data model to enhance your chat flows, providing a more tailored experience for your users and improving your ability to triage and respond. You can currently set the following fields on threads created from the chat widget:
  • Labels
  • Tiers
  • Tenants
  • External IDs
There are several places in the configuration you can add these with varying effects:

​
All threads

Providing a top-level threadDetails object in the Plain.init function will set these fields on all threads created from the chat widget. You could, for example, set a label based on the page the user is on. 
Plain.init({
  // ...Other options

  threadDetails: {
    // Optional. Labels to be set on created threads. 
    // To find a label id open the Plain app and go to 'Settings' -> 'Labels', you can select `Copy label ID` from the overflow menu on each label
    labelTypeIds: ['lt_01JDAB92EBHP3DSXS43DW96WBS'],

    // Optional. A tier to be set on created threads.
    // To find a tier ID open the Plain app and go to 'Settings' -> 'Tiers'. Select a tier and then copy the ID from the URL.
    // You can also specify a tier by its external ID e.g { externalId: 'example_external_id' }
    tierIdentifier: { tierId: 'tier_01JDABCAZBDFKH7WA6WNBDSA2F' },

    // Optional. A tenant to be set on created threads.
    // To find a tenant ID open the Plain app and click 'Tenants' under 'Browse' in the left sidebar. Select a tenant and then copy the ID from the URL.
    // You can also specify a tenant by its external ID e.g { externalId: 'example_external_id' }
    tenantIdentifier: { tenantId: 'te_01HT539973HNVZFSDXWHPT8FH1' },

    // Optional. An external ID to be set on created threads.
    externalId: 'example_external_id';
  }
});

​
Chat buttons

Chat buttons image
You can configure the primary chat button and any additional chat buttons that appear on the intro screen with text and an icon using the chatButtons array. You can also pass threadDetails to a chat button to set fields on the thread when the user creates a chat from that specific button. If you provide the same field in both the top-level threadDetails and a chat button, any single value fields will be overridden by the chat button and any multi-value fields will be appended to. 
Plain.init({
  // ...Other options

  chatButtons: [
    {
      // Optional. The name of the icon to display, see above for full options
      icon: 'bulb',

      // The text to display on the button
      text: 'Give feedback',

      // Optional. Allows you to set fields for the threads which are created with this button. See above for full options.
      threadDetails: {},

      // Optional. Form elements which the user must fill out before sending a chat message. See below for full options.
      form: {},
    }
  ]
})

​
Chat forms

Chat forms image
Similar to chat buttons, chat forms allow you to set fields on the thread when the user creates a chat. These are specific to each chatButton. 

Plain.init({
  // ...Other options
  chatButtons: [
    {
      // ...Other chat button options
      form: {
        // The fields which make up the form. All form fields must be filled in for a user to send a chat message
        fields: [
          {
            // Currently only dropdown form fields are supported
            type: 'dropdown',

            // Optional. The placeholder text displayed on the dropdown
            placeholder: 'Select a topic...',

            // The options which are available in the dropdown, minimum of 1 required.
            options: [
              {
                // Optional. An icon to be displayed on the dropdown option. See above for full options.
                icon: 'bug',

                // The text which is displayed for this dropdown option
                text: 'Bug report',

                // Optional. Enables setting values on threads when this option is selected by the user. See above for full options
                threadDetails: {},
              }
            ],
          }
        ]
      },
    }
  ]
})

​
Additional methods

We provide additional methods on the Plain object to provide more control over the chat widget. This may be helpful to keep the chat widget in-sync with your existing application state. 
// This takes the same arguments as Plain.init. It will update the chat widget in-place with the new configuration.
// Only top-level fields are updated, nested fields are not merged.
Plain.update({ ... });

// This takes the same arguments as `customerDetails` in Plain.init.
// This will update just the customer details in the chat widget. This may be useful if you have asynchronous authentication state
Plain.setCustomerDetails({ ...})

// Opens and closes the widget if using the default, floating mode
Plain.open();
Plain.close();

// These are event listeners that will be fired when the chat widget is opened or closed respectively
// These return a function that can be called to remove the listener
Plain.onOpen(() =>{ 
  // Opened
});
Plain.onClose(() => {
  // Closed
});

// Returns whether or not the chat widget is initialized
Plain.isInitialized();

// This returns an array with debug logs that have been collected by the chat widget
// This is useful if you are contacting Plain support with an issue regarding the chat widget
// This will redact sensitive information such as customer details
Plain.exportDebugLogs();
⌘I