Customer cards

Live context straight from your own systems when helping customers.

Customer cards show information from your own systems next to a customer or thread in Plain, so your team has the context it needs without leaving the queue.

Customer cards are configured on Plain (see how to create one) and requested by Plain from your APIs.

High-level flow

For a more detailed description of the protocol, check out the full spec.

1. A thread is viewed in Plain.

2. Plain fires a POST request to your API with:

   • The thread customer’s email, id and, if set, externalId
   • The thread’s id and, if set, externalId.
   • If the thread has a tenant, the tenant id and, if set, externalId.
   • The configured customer card keys

3. Your API responds with the JSON for each card

4. Cards are shown to the user in Plain.

Based on your customer card settings, Plain sends a request to your API like the below example:

{
  "cardKeys": ["plan-details"],

  "customer": {
    "id": "c_01GW2NTPQNPWTRKAC0G8Z518W2",
    "email": "[e-mail]",
    "externalId": "id-of-customer-in-your-systems" // nullable
  },
  "thread": {
    "id": "th_01J2HV0V702XKWMG58G169BS23",
    "externalId": "some-id-you-specified" // nullable
  },
  "tenant": {
    "id": "te_0VX2HE0V702AKWMG5SG16ABS11",
    "externalId": "some-id-you-specified" // nullable
  }
}

Your API should then reply with a list of cards matching the requested keys where each card contains the components you want to display:

{
  "cards": [
    {
      "key": "plan-details",
      "timeToLiveSeconds": 86400,
      "components": [
        {
          "componentText": {
            "text": "Enterprise Tier"
          }
        }
      ]
    }
  ]
}

UI components

To define what each customer card should look like, you use the Plain UI components. All the components are documented in the Plain UI Components section.

You can find example customer cards and an example API you can check out team-plain/example-customer-cards. You can try these in your own workspace.

Example cards

To demonstrate what you can build with customer cards we’ve built some examples you can view and which are open source.

Customer cards Examples →

Playground

The UI components playground lets you build and preview the component JSON needed to create a customer card. Use this to prototype a customer card before starting to build your integration.

Playground →