Skip to main content
Customer cards are a powerful feature in Plain that let you show information from your own systems while looking at a customer or thread in Plain. This makes sure you always have important context when helping customers. Customer cards are configured on Plain (see how to 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 will send a request to your API like the below example: 
{
  "cardKeys": ["plan-details"],

  "customer": {
    "id": "c_01GW2NTPQNPWTRKAC0G8Z518W2",
    "email": "alex@grocery.co",
    "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. Feel free to try these out in your 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 →