# Plain on boxd

> Plain is a collaborative support platform for B2B support teams, offering a modern, AI-powered interface to consolidate support channels and assist customers efficiently.

- Page: https://boxd.sh/integrations/plain/
- CLI: `run plain` (23 commands, 23 marked common)
- SDK: `import { plain } from "@boxd/run"`; every parameter and response type is at `@boxd/run/plain`
- Triggers: 11
- Connect: `run auth plain` (API key), or https://app.boxd.sh/integrations/detail/plain
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth plain      # once: prints a link to connect your account
run plain           # list its commands
run plain list-tiers
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { plain } from "@boxd/run";

const result = await plain.listTiers({});
console.log(result);

plain.on("thread-created", async (event) => {
  // Thread Created: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run plain.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run plain <command> --help` lists the optional ones. "common" marks what `run plain` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-customer-to-group` ·common | `plain.addCustomerToGroup()` | `--customerGroupIdentifiers` `--customerId` | 0 | Add a customer to one or more customer groups |
| `create-customer-group` ·common | `plain.createCustomerGroup()` | `--color` `--key` `--name` | 1 | Creates a new customer group in Plain for organizing and segmenting customers |
| `create-thread` ·common | `plain.createThread()` | `--customerIdentifier` `--title` | 3 | Create a new thread |
| `delete-customer` ·common | `plain.deleteCustomer()` | `--customer-id` | 0 | Delete a customer from the system |
| `delete-user` ·common | `plain.deleteUser()` | `--user-id` | 0 | Delete a user from the system |
| `fetch-company` ·common | `plain.fetchCompany()` | `--company-id` | 0 | Fetch company details by ID |
| `fetch-issues` ·common | `plain.fetchIssues()` | `--customerId` | 2 | Fetches external issue tracker links (Jira, Linear, GitHub, etc.) associated with a customer's threads |
| `fetch-tier` ·common | `plain.fetchTier()` | `--tier-id` | 0 | Fetch a tier by its ID |
| `get-customer-by-email` ·common | `plain.getCustomerByEmail()` | `--email` | 0 | Fetch customer details by email address |
| `get-customer-by-id` ·common | `plain.getCustomerById()` | `--id` | 0 | Retrieve details of a specific customer by their unique ID |
| `get-customers` ·common | `plain.getCustomers()` | — | 6 | Fetch a list of customers |
| `get-thread-by-id` ·common | `plain.getThreadById()` | `--id` | 0 | Fetches comprehensive details of a specific thread by ID, including customer info, status, priority, labels, and assignments |
| `get-user-by-id` ·common | `plain.getUserById()` | `--user-id` | 0 | Fetch workspace user/team member by ID |
| `list-customer-groups` ·common | `plain.listCustomerGroups()` | — | 5 | List all customer groups |
| `list-threads` ·common ·deprecated | `plain.listThreads()` | — | 4 | Use PLAIN_PLAIN_QUERY_THREADS instead |
| `list-tiers` ·common | `plain.listTiers()` | — | 4 | Retrieve a list of tiers with pagination |
| `query-threads` ·common | `plain.queryThreads()` | — | 2 | Retrieve a paginated list of threads |
| `remove-customer-from-group` ·common | `plain.removeCustomerFromGroup()` | `--customerGroupIdentifiers` `--customerId` | 0 | Removes a customer from one or more customer groups in Plain |
| `run-graphql-query` ·common | `plain.runGraphqlQuery()` | `--query` | 1 | Execute any GraphQL query or mutation against Plain API |
| `send-message` ·common | `plain.sendMessage()` | `--textContent` `--threadId` | 3 | Send a new message within a thread |
| `update-company` ·common | `plain.updateCompany()` | `--domainName` `--name` | 4 | Upserts (creates or updates) a company in Plain |
| `update-thread` ·common | `plain.updateThread()` | `--threadId` `--title` | 0 | Update a thread's title |
| `upsert-customer` ·common | `plain.upsertCustomer()` | `--identifier` `--onCreate` `--onUpdate` | 0 | Upsert (create or update) a customer |

## Triggers

`plain.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"customer-event"` | Customer Event | — | Fires when a customer in Plain is created, updated or deleted |
| `"customer-group-changed"` | Customer Group Changed | — | Fires when a customer group is created, edited or deleted in Plain |
| `"customer-group-membership-changed"` | Customer Group Membership Changed | — | Fires when a customer is added to or removed from a customer group in Plain |
| `"thread-created"` | Thread Created | — | Fires when a new support thread is opened in Plain |
| `"thread-custom-field-updated"` | Thread Custom Field Updated | — | Fires when one of your own thread fields is set, changed or cleared on a Plain thread |
| `"thread-message-received"` | Thread Message Received | — | Fires when an inbound message arrives on a Plain thread |
| `"thread-message-sent"` | Thread Message Sent | — | Fires when your team sends a message out on a Plain thread |
| `"thread-note-created"` | Thread Note Created | — | Fires when an internal note is added to a thread in Plain |
| `"thread-note-mentioned"` | Thread Note Mention Created | — | Fires when an internal note mentions a machine user in Plain |
| `"thread-properties-updated"` | Thread Properties Updated | — | Fires when a thread's status, assignee, priority or labels change in Plain |
| `"thread-tenant-updated"` | Thread Tenant Updated | — | Fires when a thread's tenant is set, changed or cleared in Plain |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.