A customer event will be created in all threads that belong to the provided customer ID. If you want an event to appear in a specific thread use a thread event.

To create an event you need a customer ID.

You can get this by upserting a customer in Plain, from data in webhooks or other API calls you made. If you want to test this, press ⌘ + K on any thread and then “Copy customer ID” to get an ID you can experiment with.

In this example we’ll be creating the following event:

Example event

For this you’ll need an API key with the following permissions:

  • customerEvent:create
import { PlainClient, uiComponent } from '@team-plain/typescript-sdk';

const client = new PlainClient({ apiKey: 'plainApiKey_xxx' });

const res = await client.createCustomerEvent({
  title: 'API key generated',

  customerIdentifier: {
    // You can use the email:
    emailAddress: 'jane@acme.com',

    // ...or if you set external id on customers:
    // externalId: 'YOUR_ID',

    // ...or you can use the customer's id in Plain:
    // customerId: 'c_01H14DFQ4PDYBH398J1E99TWSS'

  components: [
      text: 'New API key was added with the fingerprint **3b7896975ee9fd15eeb7** with 4 associated roles.',
      size: 'M',
      label: 'View in admin',
      url: 'https://admin.your-app.com',

  // Optional - if provided, this will ensure that this event can only
  // be created once and fail on the second time. This external id acts
  // as an idempotency key while also letting you correlate an event to
  // something your systems.
  externalId: 'XXX',

if (res.error) {
} else {

Which would console.log:

  "__typename": "CustomerEvent",
  "id": "tev_01HB924RWAW8H3Q8KZDFWYBJHZ",
  "externalId": null,
  "customerId": "c_01H14DFQ4PDYBH398J1E99TWSS",
  "title": "API key generated",
  "createdAt": {
    "__typename": "DateTime",
    "iso8601": "2023-09-26T15:36:23.690Z",
    "unixTimestamp": "1695742583690"
  "createdBy": {
    "__typename": "MachineUserActor",
    "machineUserId": "mu_01HBZM0TZAKAZPJ47NX7X7XMDY"
  "updatedAt": {
    "__typename": "DateTime",
    "iso8601": "2023-10-05T10:10:04.785Z",
    "unixTimestamp": "1696500604785"
  "updatedBy": {
    "__typename": "MachineUserActor",
    "machineUserId": "mu_01HBZM0TZAKAZPJ47NX7X7XMDY"