Customization

Plain.init({
  appId: 'your_chat_app_id_here',

  // 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',
      //   'discord_muted',
      //   'email',
      //   'slack',
      //   'slack_muted',
      //   '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.
  // Note: this must be a DOM Element, not a CSS selector string.
  embedAt: document.querySelector('#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
    brandBackgroundColor: '#22C55E', // Used for the background of the chat widget on the intro screen
    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, right, and zIndex are supported
  position: {
    right: '10px',
    bottom: '10px',
    zIndex: '1000', // Optional. Controls the stacking order of the widget
  },

  // Optional. Allows you to set fields for the threads which are created from chats
  threadDetails: {
    // See the data model documentation 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
  ],
});

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. Priority to set on created threads (1 = urgent, 2 = high, 3 = normal, 4 = low)
    priority: 3,

    // 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',

    // Optional. Thread fields to be set on created threads.
    threadFields: [
      { key: 'my_string_field', type: 'STRING', stringValue: 'some value' },
      { key: 'my_bool_field', type: 'BOOL', booleanValue: true },
      { key: 'my_enum_field', type: 'ENUM', stringValue: 'option_1' },
    ]
  }
});

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: {},
    }
  ]
})

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: [
          {
            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: {},
              }
            ],
          },
          {
            type: 'text',
            placeholder: 'Your order number',

            // The 'key' of the thread field that will be set
            threadFieldKey: 'order_number'
          }
        ]
      },
    }
  ]
})

// 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();