Headless Support Portal

When a customer signs up to your product you first have to create a tenant for that customer. You can read more about tenants here, but in essence each tenant in Plain should 1:1 map to your own workspace/team/org concept in your product.

This is an essential first step so that you can make sure that when someone access the support portal they only see their team’s support requests. Without this it would be difficult/impossible to know which support requests belong to the customer’s workspace/team/org.

To create tenants in Plain you can upsert them. After that you can add individual customers to that tenant.

You can, if you are prototyping this, skip this step and instead just fetch support requests for the customer that is logged in. This means that if John and Lucy are both part of the same team in your product, John will only see his own tickets vs also being able to see Lucy’s latest support requests. Depending on your product this might work fine but for most B2B SaaS this is not the ideal experience.

Once you have set tenants & threads for all support requests you can fetch them via our API and show them to the customer

To display a list of support requests you will need to fetch the appropriate threads from your workspace. The recommended way to do this is to filter by tenant.

  const threads = await plainClient.getThreads({
    filters: {
      tenantIdentifiers: [{ externalId: tenantExternalId }],
      statuses: [ThreadStatus.Todo, ThreadStatus.Snoozed],
    },
  });

If in Step 1 you opted for not using Tenants then you can also filter by customerId here in order to fetch just the threads belonging to a specific customer.

This will give you back a list of threads but not give you back the content of a thread. To do so you must use this query. This will fetch all relevant message timeline entries. This example is showing how to do this via GraphQL directly but this can also be done with our SDK using the rawRequest method.

query threadTimeline($threadId: ID!, $first: Int, $after: String, $last: Int, $before: String) {
  thread(threadId: $threadId) {
    title
    description
    priority
    status
    createdAt {
      __typename
      iso8601
    }
    customer {
      fullName
    }
    updatedAt {
      __typename
      iso8601
    }
    timelineEntries(first: $first, after: $after, last: $last, before: $before) {
      edges {
        cursor
        node {
          id
          timestamp {
            __typename
            iso8601
          }
          actor {
            __typename
            ... on UserActor {
              user {
                fullName
              }
            }
            ... on CustomerActor {
              customer {
                fullName
              }
            }
            ... on MachineUserActor {
              machineUser {
                fullName
              }
            }
          }
          entry {
            __typename
            ... on CustomEntry {
              title
              components {
                __typename
                ... on ComponentText {
                  text
                }
              }
            }
            ... on ChatEntry {
              chatId
              text
            }
          }
        }
      }
      pageInfo {
        __typename
        hasPreviousPage
        hasNextPage
        startCursor
        endCursor
      }
    }
  }
}

To submit new support requests from your portal you can create a contact form which, when submitted, create a thread within Plain.

What is important is that when you create the thread you pre-fill the customer’s tenant id. This ensures that the support request they create is then visible in the support portal.

You can read more on how to create a thread here.

One thing to note is that you are not constrained at all here by the data you want to gather. Although a simple form with just a message and a title does work, it’s typically much more useful and powerful to ask structured questions such as what the support request is about, how urgent it is and much more.

You can read more on contact forms, as well as see some real examples here.

To reply to threads directly from your support portal is probably the most difficult part of building a good support portal from the UI side of things.

In terms of the interaction with Plain, however, it’s as simple as calling the replyToThread mutation.

Depending on the channels you support your UI here might vary. For example if you want to not support email communication here you don’t need to allow for specifying Cc and Bcc addresses.