Plain

https://www.plain.com/docs
Admin
Plain offers a GraphQL API for programmatic access to its platform, enabling management of customer...
Tokens:138,483
Snippets:1,607
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install the GraphQL SDK

Source: https://www.plain.com/docs/graphql/sdk

Install the package via npm to get started.

```bash
npm install @team-plain/graphql
```

--------------------------------

### Install UI Components SDK

Source: https://www.plain.com/docs/ui-components/sdk

Install the package along with its required peer dependency.

```bash
npm install @team-plain/ui-components @team-plain/graphql
```

--------------------------------

### Start the local development server

Source: https://www.plain.com/docs/customer-cards/examples

Starts the API server on http://localhost:3000.

```bash
npm run start
```

--------------------------------

### workspaceDiscordChannelInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceDiscordChannelInstallationInfo

Fetches the Discord OAuth installation URL. Redirect the user to this URL to start the authorization process.

```APIDOC
## GraphQL Query: workspaceDiscordChannelInstallationInfo

### Description
Returns the Discord OAuth installation URL needed to connect a Discord server (guild) to this workspace. Redirect the user to the returned URL to begin the OAuth flow.

### Signature
`workspaceDiscordChannelInstallationInfo(redirectUrl: String!): WorkspaceDiscordChannelInstallationInfo!`

### Arguments
- **redirectUrl** (String!) - Required - The URL to which Discord will redirect after authorization.

### Returns
- **installationUrl** (String!) - The URL to initiate the Discord OAuth flow.

### Example Query
```graphql
query WorkspaceDiscordChannelInstallationInfo($redirectUrl: String!) {
  workspaceDiscordChannelInstallationInfo(redirectUrl: $redirectUrl) {
    installationUrl
  }
}
```

### Example Variables
```json
{
  "redirectUrl": "string"
}
```

### Example Response
```json
{
  "data": {
    "workspaceDiscordChannelInstallationInfo": {
      "installationUrl": "string"
    }
  }
}
```
```

--------------------------------

### Fetch Workspace Slack Sidekick Installation Info

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceSlackSidekickInstallationInfo

Use this GraphQL query to retrieve the installation URL. The redirectUrl argument is required.

```graphql
query WorkspaceSlackSidekickInstallationInfo($redirectUrl: String!) {
  workspaceSlackSidekickInstallationInfo(redirectUrl: $redirectUrl) {
    installationUrl
  }
}
```

--------------------------------

### Fetch Discord Installation URL

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceDiscordChannelInstallationInfo

Use this GraphQL query to obtain the installation URL for Discord integration.

```graphql
query WorkspaceDiscordChannelInstallationInfo($redirectUrl: String!) {
  workspaceDiscordChannelInstallationInfo(redirectUrl: $redirectUrl) {
    installationUrl
  }
}
```

--------------------------------

### Handle Email Received Event with Plain SDK

Source: https://www.plain.com/docs/webhooks/thread-email-received

This example demonstrates how to set up a webhook handler using the Plain SDK to process incoming emails. Ensure you have the SDK installed and configured with your API key.

```typescript
import { Webhook } from 'plain-sdk';

const webhook = new Webhook({ apiKey: 'YOUR_API_KEY' });

webhook.on('thread.email.received', async (event) => {
  const { thread_id, email } = event.data;

  console.log(`Received email in thread ${thread_id}: ${email.subject}`);

  // Process the email data here
});

// Start the webhook server (example using Express)
// app.post('/webhook', webhook.handler);

```

--------------------------------

### userAuthSlackInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/userAuthSlackInstallationInfo

Retrieves a Slack OAuth installation URL. Optionally accepts a workspace ID to scope the installation.

```APIDOC
## GraphQL Query: userAuthSlackInstallationInfo

### Description
Returns a Slack OAuth installation URL for the current user to connect their user-auth Slack integration. This URL can optionally be scoped to a specific Slack workspace.

### Arguments
- **workspaceId** (String) - Optional - The ID of the specific Slack workspace to scope the installation to.

### Returns
- **url** (String) - The Slack OAuth installation URL.
```

--------------------------------

### Install the Plain webhooks SDK

Source: https://www.plain.com/docs/agents/receiving-events

Use npm to add the required package to your project.

```bash
npm install @team-plain/webhooks
```

--------------------------------

### Query Response

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceDiscordChannelInstallationInfo

The expected JSON response structure containing the installation URL.

```json
{
  "data": {
    "workspaceDiscordChannelInstallationInfo": {
      "installationUrl": "string"
    }
  }
}
```

--------------------------------

### workspaceSlackSidekickInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceSlackSidekickInstallationInfo

Retrieves the installation URL for the Slack Sidekick by providing a redirect URL.

```APIDOC
## GraphQL Query: workspaceSlackSidekickInstallationInfo

### Description
Fetches the installation URL required to set up the Slack Sidekick for a workspace.

### Arguments
- **redirectUrl** (String!) - Required - The URL to redirect to after installation.

### Returns
- **WorkspaceSlackSidekickInstallationInfo!** - An object containing the installationUrl.

### Query Example
```graphql
query WorkspaceSlackSidekickInstallationInfo($redirectUrl: String!) {
  workspaceSlackSidekickInstallationInfo(redirectUrl: $redirectUrl) {
    installationUrl
  }
}
```

### Variables Example
```json
{
  "redirectUrl": "string"
}
```

### Response Example
```json
{
  "data": {
    "workspaceSlackSidekickInstallationInfo": {
      "installationUrl": "string"
    }
  }
}
```
```

--------------------------------

### Example Upsert Tenant Input

Source: https://www.plain.com/docs/graphql/tenants/upsert

Provides an example of the input object for the `upsertTenant` mutation. The `externalId` should be the unique identifier from your system.

```json
{
  "input": {
    "externalId": "team-123",
    "name": "Team Awesome"
  }
}
```

--------------------------------

### Thread Status Transitioned Webhook Example

Source: https://www.plain.com/docs/webhooks/thread-status-transitioned

This example demonstrates the structure of the webhook payload when a thread's status transitions. It includes details about the thread and the event.

```json
{
  "event": "thread.status.transitioned",
  "data": {
    "thread": {
      "id": "thread_abc123",
      "status": "resolved",
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-01-01T12:05:00Z",
      "metadata": {
        "customer_id": "cust_xyz789"
      }
    },
    "previous_status": "open"
  }
}
```

--------------------------------

### WorkflowButton GraphQL Example

Source: https://www.plain.com/docs/ui-components/workflow-button

This example demonstrates how to configure and use the WorkflowButton component with a GraphQL mutation to trigger a workflow. Ensure the workflow ID is correctly specified.

```graphql
mutation TriggerWorkflow($workflowId: ID!) {
  triggerWorkflow(workflowId: $workflowId)
}

```

--------------------------------

### myLinearInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/myLinearInstallationInfo

Returns the OAuth installation URL to initiate the Linear authorization flow for the current user.

```APIDOC
## GraphQL Query: myLinearInstallationInfo

### Description
Returns the OAuth installation URL to initiate the Linear authorization flow for the current user. The returned URL should be used in the UI to allow the user to grant Plain access to their Linear account.

### Arguments
- **redirectUrl** (String) - Required - The redirect URI registered for the Linear OAuth app. The authorization code delivered to this URL is subsequently used in the `createMyLinearIntegration` mutation.

### Response
- **installationUrl** (String) - The URL to redirect the user to for Linear authorization.
```

--------------------------------

### mySlackInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/mySlackInstallationInfo

Returns a Slack OAuth installation URL for the current user to connect their personal Slack notifications integration. Pass this URL to Slack's OAuth flow and exchange the resulting code with createMySlackIntegration.

```APIDOC
## GraphQL Query: mySlackInstallationInfo

### Description
Returns a Slack OAuth installation URL for the current user to connect their personal Slack notifications integration. This URL should be used to initiate the Slack OAuth flow.

### Usage
Pass the returned URL to Slack's OAuth flow and exchange the resulting code with the `createMySlackIntegration` mutation.
```

--------------------------------

### workspaceSlackInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceSlackInstallationInfo

Retrieves the Slack OAuth installation URL required to connect a workspace-level Slack integration.

```APIDOC
## workspaceSlackInstallationInfo

### Description
Returns a Slack OAuth installation URL for connecting a workspace-level Slack notifications integration. This URL should be passed to Slack's OAuth flow, and the resulting code can then be exchanged using the `createWorkspaceSlackIntegration` mutation.

### Query
`workspaceSlackInstallationInfo`

### Usage
Call this query to obtain the authorization URL required to initiate the Slack integration process for your workspace.
```

--------------------------------

### Build UI Components Example

Source: https://www.plain.com/docs/ui-components/sdk

Construct a layout using various UI components like rows, dividers, and buttons.

```ts
import { uiComponent } from "@team-plain/ui-components";

const components = [
  uiComponent.row({
    mainContent: [uiComponent.text({ text: "Customer Plan", size: "L" })],
    asideContent: [uiComponent.badge({ label: "Pro", color: "GREEN" })],
  }),
  uiComponent.divider(),
  uiComponent.text({ text: "Signed up 3 days ago", color: "MUTED" }),
  uiComponent.spacer({ size: "M" }),
  uiComponent.container({
    content: [
      uiComponent.linkButton({
        label: "View in Stripe",
        url: "https://dashboard.stripe.com/...",
      }),
      uiComponent.copyButton({
        value: "cus_abc123",
        tooltip: "Copy Stripe ID",
      }),
    ],
  }),
];
```

--------------------------------

### importCustomers Variables

Source: https://www.plain.com/docs/graphql-reference/mutations/importCustomers

Example input variables for the importCustomers mutation.

```json
{
  "input": {
    "customers": [
      {
        "externalId": "string",
        "fullName": "string",
        "tenants": [
          {
            "externalId": "string",
            "name": "string"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Thread Assignment Transitioned Webhook Example

Source: https://www.plain.com/docs/webhooks/thread-assignment-transitioned

This example demonstrates the structure of the payload received when a thread's assignment is transitioned. It includes details about the thread, the previous and new assignee, and the event type.

```json
{
  "event": "thread.assignment.transitioned",
  "thread_id": "thr_12345",
  "payload": {
    "thread": {
      "id": "thr_12345",
      "subject": "New customer inquiry",
      "assignee_id": "usr_abcde",
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:05:00Z"
    },
    "previous_assignee_id": "usr_fghij",
    "assignee_id": "usr_abcde"
  }
}
```

--------------------------------

### createWorkflowStep Variables

Source: https://www.plain.com/docs/graphql-reference/mutations/createWorkflowStep

Example input variables for the createWorkflowStep mutation.

```json
{
  "input": {
    "workflowId": "id",
    "type": "CONDITION",
    "payload": "string",
    "transitions": [
      "id"
    ]
  }
}
```

--------------------------------

### SDK Usage for Handling Slack Messages

Source: https://www.plain.com/docs/webhooks/thread-slack-message-received

Example of how to use the Plain SDK to handle incoming Slack messages. This snippet demonstrates setting up a webhook handler.

```javascript
import { Webhooks } from "@plain/sdk";

const webhooks = new Webhooks({
  secret: "YOUR_WEBHOOK_SECRET",
});

webhooks.on("thread_slack_message_received", async ({ data }) => {
  console.log("Received Slack message:", data);
  // Process the message data here
});

// To handle raw HTTP requests, you can use:
// const handler = webhooks.createHandler();
// app.post("/webhook", handler);
```

--------------------------------

### workspaceLinearInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceLinearInstallationInfo

Retrieves the Linear OAuth installation URL for the app actor flow.

```APIDOC
## workspaceLinearInstallationInfo

### Description
Builds the Linear OAuth installation URL for the app actor flow (actor=app).

### Operation
GraphQL Query
```

--------------------------------

### Customer Group Membership Changed Event Schema Example

Source: https://www.plain.com/docs/webhooks/customer-group-membership-changed

This snippet shows an example payload for the customer group membership changed event.

```json
{
  "event": "customer.group_membership.changed",
  "data": {
    "changeType": "ADDED",
    "customer": {
      "id": "cus_123",
      "email": "test@example.com"
    },
    "group": {
      "id": "grp_456",
      "name": "VIP Customers"
    }
  }
}
```

--------------------------------

### Workflow Capabilities Response

Source: https://www.plain.com/docs/graphql-reference/queries/workflowCapabilities

Example response structure for the workflowCapabilities query.

```json
{
  "data": {
    "workflowCapabilities": {
      "hasConditionSupport": true,
      "hasWaitSupport": true,
      "allowedActionTypes": [
        "string"
      ]
    }
  }
}
```

--------------------------------

### Handling Webhooks with Plain SDK

Source: https://www.plain.com/docs/webhooks/thread-assignment-transitioned

This example shows how to use the Plain SDK to handle incoming webhook events, specifically filtering for the 'thread.assignment.transitioned' event and processing its payload.

```javascript
import { Webhooks } from "@plain/sdk";

const webhooks = new Webhooks({
  secret: "YOUR_PLAIN_SECRET",
});

app.post("/webhooks", async (req, res) => {
  const signature = req.headers["plain-signature"];
  const payload = req.body;

  try {
    const event = await webhooks.verify(payload, signature);

    switch (event.type) {
      case "thread.assignment.transitioned":
        console.log("Thread assignment transitioned:", event.data);
        // Handle the assignment transition
        break;
      // ... other event types
    }

    res.sendStatus(200);
  } catch (error) {
    console.error("Webhook verification failed:", error);
    res.sendStatus(400);
  }
});

```

--------------------------------

### Slack Message Received Webhook Example

Source: https://www.plain.com/docs/webhooks/thread-slack-message-received

This is an example payload for the Slack message received webhook. It shows the structure of the data sent when a message is received.

```json
{
  "event": "thread_slack_message_received",
  "data": {
    "thread_id": "t1234567890",
    "message_id": "msg1234567890",
    "channel_id": "C0123456789",
    "user_id": "U0123456789",
    "text": "Hello, world!",
    "timestamp": "1678886400.123456"
  }
}
```

--------------------------------

### workspaceSlackChannelInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceSlackChannelInstallationInfo

Retrieves the Slack OAuth installation URL required to connect a workspace Slack channel integration. The returned URL should be used in the Slack OAuth flow, and the resulting code can then be exchanged using the createWorkspaceSlackChannelIntegration mutation.

```APIDOC
## GraphQL Query: workspaceSlackChannelInstallationInfo

### Description
Returns a Slack OAuth installation URL for connecting a workspace Slack channel integration. Pass this URL to Slack's OAuth flow and exchange the resulting code with createWorkspaceSlackChannelIntegration.

### Usage
```graphql
query {
  workspaceSlackChannelInstallationInfo {
    installationUrl
  }
}
```
```

--------------------------------

### createThread Variables

Source: https://www.plain.com/docs/graphql-reference/mutations/createThread

Example input variables structure for the createThread mutation.

```json
{
  "input": {
    "customerIdentifier": {}
  }
}
```

--------------------------------

### SDK Usage for Customer Group Membership Changed Event

Source: https://www.plain.com/docs/webhooks/customer-group-membership-changed

Example of how to handle the customer group membership changed event using the Plain SDK.

```javascript
import { Webhooks } from "@plain/webhooks";

const webhook = new Webhooks({
  secret: "whsec_...",
});

app.post("/webhook", async (req, res) => {
  const signature = req.headers["plain-signature"];
  const payload = req.body;

  try {
    const event = webhook.verify(payload, signature);

    switch (event.data.type) {
      case "customer.group_membership.changed":
        console.log("Customer group membership changed:", event.data.payload);
        break;
      // ... handle other event types
    }

    res.json({ success: true });
  } catch (error) {
    console.error("Webhook verification failed:", error);
    res.status(400).send(`Webhook Error: ${error.message}`);
  }
});

```

--------------------------------

### SDK Usage for Thread Status Transitioned Webhook

Source: https://www.plain.com/docs/webhooks/thread-status-transitioned

This example shows how to handle the thread.status.transitioned event using the Plain SDK. It includes setting up a webhook handler and processing the event data.

```javascript
import { Webhook } from "@plain/sdk";

const webhook = new Webhook({
  secret: "YOUR_WEBHOOK_SECRET",
});

webhook.on("thread.status.transitioned", async (event) => {
  const { thread, previous_status } = event.data;
  console.log(
    `Thread ${thread.id} transitioned from ${previous_status} to ${thread.status}`
  );
});

// Example of how to verify and parse an incoming request
// const payload = await webhook.verify(request.body, request.headers["plain-signature"] as string);
// console.log(payload);

```

--------------------------------

### Email Received Webhook Schema Example

Source: https://www.plain.com/docs/webhooks/thread-email-received

This snippet shows an example of the JSON payload received when an email is sent to your workspace. It includes sender, recipient, subject, and body details.

```json
{
  "event": "thread.email.received",
  "data": {
    "thread_id": "thr_12345",
    "email": {
      "id": "eml_abcde",
      "from": {
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
      },
      "to": [
        {
          "name": "Support Team",
          "email": "support@example.com"
        }
      ],
      "cc": [],
      "bcc": [],
      "subject": "Inquiry about your service",
      "body": {
        "text": "Hello,\nI would like to inquire about your services.\nThank you.",
        "html": "<p>Hello,</p><p>I would like to inquire about your services.</p><p>Thank you.</p>"
      },
      "date": "2023-10-27T10:00:00Z",
      "attachments": []
    }
  }
}
```

--------------------------------

### Example Chat Received Webhook Payload

Source: https://www.plain.com/docs/webhooks/thread-chat-received

This is an example of the JSON payload received when a chat message from a customer is sent. It includes details about the thread, sender, and message content.

```json
{
  "event": "thread.chat.received",
  "thread": {
    "id": "th_12345",
    "created_at": 1678886400,
    "customer_id": "cu_abcde",
    "assignee_id": "us_fghij",
    "status": "open",
    "subject": "Issue with order",
    "tags": ["billing", "urgent"],
    "metadata": {
      "order_id": "ORD-98765"
    }
  },
  "message": {
    "id": "msg_67890",
    "created_at": 1678886405,
    "sender_type": "customer",
    "sender_id": "cu_abcde",
    "body": {
      "content": "Hi, I have a question about my recent order.",
      "type": "text"
    },
    "attachments": []
  },
  "account": {
    "id": "ac_klmno"
  }
}
```

--------------------------------

### myMSTeamsInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/myMSTeamsInstallationInfo

Retrieves the OAuth installation URL for the current user to connect their personal Microsoft Teams account. Returns null if the workspace integration is not configured.

```APIDOC
## GraphQL Query: myMSTeamsInstallationInfo

### Description
Returns the OAuth installation URL for the current user to connect their personal Microsoft Teams account to Plain. Returns null in `installationUrl` if the workspace does not have an MS Teams workspace integration configured.

### Response
- **installationUrl** (String | null) - The OAuth URL for connecting the MS Teams account, or null if the integration is not configured.
```

--------------------------------

### refreshSidekickMcpServerTools

Source: https://www.plain.com/docs/graphql-reference/mutations/refreshSidekickMcpServerTools

Re-discover a custom MCP server's tools (tools/list) and reconcile the cached snapshot: newly-appeared tools start in the "ask" (approval-required) state.

```APIDOC
## refreshSidekickMcpServerTools

### Description
Re-discover a custom MCP server's tools (tools/list) and reconcile the cached snapshot. Newly-appeared tools start in the "ask" (approval-required) state.

### Operation
Mutation
```

--------------------------------

### Fetch Next Page with `endCursor`

Source: https://www.plain.com/docs/graphql/pagination

Use the `endCursor` from a previous query to fetch the next page of results. This example demonstrates fetching 50 entries.

```graphql
query {
  customers(first: 50, after: "some_cursor") {
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}
```

--------------------------------

### Workspace Slack Integration Response

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceSlackIntegration

Example JSON response structure for the workspaceSlackIntegration query.

```json
{
  "data": {
    "workspaceSlackIntegration": {
      "integrationId": "id",
      "slackChannelName": "string",
      "slackTeamId": "string",
      "slackTeamName": "string",
      "slackTeamImageUrl68px": "string",
      "isReinstallRequired": true
    }
  }
}
```

--------------------------------

### mutation createWorkspaceSlackSidekickIntegration

Source: https://www.plain.com/docs/graphql-reference/mutations/createWorkspaceSlackSidekickIntegration

Installs the Plain Sidekick AI agent into the workspace's Slack. This operation requires the workspaceSlackSidekickIntegration:create permission and the ai_agent billing entitlement.

```APIDOC
## mutation createWorkspaceSlackSidekickIntegration

### Description
Installs Plain's Sidekick AI agent into the workspace's Slack. It exchanges the OAuth authorization code for a bot token, creates the #ask-plain Slack channel, and persists the integration.

### Requirements
- Permission: workspaceSlackSidekickIntegration:create
- Billing Entitlement: ai_agent

### Notes
- Fails if a channel named #ask-plain already exists.
- Only one Sidekick integration is allowed per workspace and per Slack team; calling this when one already exists returns an error.
```

--------------------------------

### updateSidekickPosthogConfig

Source: https://www.plain.com/docs/graphql-reference/mutations/updateSidekickPosthogConfig

Updates the operating instructions and default project that guide how Sidekick uses the PostHog integration. Pass null or an empty string to clear either field.

```APIDOC
## mutation updateSidekickPosthogConfig

### Description
Updates the operating instructions and default project that guide how Sidekick uses the PostHog integration. Pass null or an empty string to clear either field.
```

--------------------------------

### updateSidekickServiceConfig

Source: https://www.plain.com/docs/graphql-reference/mutations/updateSidekickServiceConfig

Updates the operating instructions that guide how Sidekick uses a connected service. Pass null or an empty string to clear the instructions.

```APIDOC
## mutation updateSidekickServiceConfig

### Description
Updates the operating instructions that guide how Sidekick uses a connected service (Datadog, Sentry, Grafana, Linear, Notion, incident.io, Attio, HubSpot, Jira, Granola, LaunchDarkly or Grain), identified by its serviceAuthorizationId. Pass null or an empty string to clear the instructions.

### Note
GitHub and PostHog have their own configuration shapes — use updateSidekickGithubConfig / updateSidekickPosthogConfig instead.
```

--------------------------------

### Basic Authentication Header

Source: https://www.plain.com/docs/webhooks

Example of the Authorization header sent when basic authentication credentials are included in the webhook URL.

```text
Authorization: Basic cGxhaW46cm9ja3M=
```

--------------------------------

### PlainClient Initialization

Source: https://www.plain.com/docs/graphql/sdk

How to initialize the PlainClient with an API key.

```APIDOC
## PlainClient Initialization

### Description
Initialize the client to interact with the Plain GraphQL API.

### Usage
```ts
import { PlainClient } from "@team-plain/graphql";

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

--------------------------------

### Handling Chat Received Event with Plain SDK

Source: https://www.plain.com/docs/webhooks/thread-chat-received

Example of how to use the Plain SDK to handle the 'thread.chat.received' event. This snippet demonstrates setting up a webhook handler to process incoming chat messages.

```javascript
import { Webhook } from "plain-sdk";

const webhook = new Webhook({ token: "YOUR_PLAIN_API_TOKEN" });

webhook.on("thread.chat.received", async ({ data }) => {
  const { thread, message } = data;

  console.log(`Received message from ${message.sender_id} in thread ${thread.id}`);
  console.log(`Message content: ${message.body.content}`);

  // You can now process the message, e.g., reply to the customer
  // await plainClient.threads.reply(thread.id, {
  //   body: {
  //     content: "Thanks for your message! We'll get back to you soon.",
  //     type: "text"
  //   }
  // });
});

// Start the webhook server (example using Express)
// app.post("/plain/webhooks", webhook.middleware());
```

--------------------------------

### Initialize the Plain Client

Source: https://www.plain.com/docs/graphql/sdk

Create a new client instance using your API key.

```ts
import { PlainClient } from "@team-plain/graphql";

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

--------------------------------

### Verify HMAC Signature in Node.js

Source: https://www.plain.com/docs/request-signing

Use this Node.js example to verify the `Plain-Request-Signature` header. Ensure the request body is stringified before hashing. Replace '<HMAC SECRET>' with your actual shared secret.

```javascript
const crypto = require('crypto');

// You may need to stringify the request body if you are using a library that parses it to a javascript object
const requestBody = JSON.stringify(request.body);

const incomingSignature = request.headers['Plain-Request-Signature'];
const expectedSignature = crypto
  .createHmac('sha-256', '<HMAC SECRET>')
  .update(requestBody)
  .digest('hex');

if (incomingSignature !== expectedSignature) {
  return response.status(403).send('Forbidden');
}
```

--------------------------------

### createHelpCenter

Source: https://www.plain.com/docs/graphql-reference/mutations/createHelpCenter

Creates a new help center. Requires the helpCenter:edit permission.

```APIDOC
## mutation createHelpCenter

### Description
Creates a new help center with a subdomain, branding, and access settings. Requires the helpCenter:edit permission.

### Operation
mutation createHelpCenter
```

--------------------------------

### Import UI Components

Source: https://www.plain.com/docs/ui-components/sdk

Import the main uiComponent helper to begin building components.

```ts
import { uiComponent } from "@team-plain/ui-components";
```

--------------------------------

### Expose local server with tunneling tools

Source: https://www.plain.com/docs/customer-cards/examples

Use these commands to create a public URL for the local server, allowing Plain to access it.

```bash
ngrok http 3000
```

```bash
lt --port 3000
```

--------------------------------

### createSidekickMcpServer

Source: https://www.plain.com/docs/graphql-reference/mutations/createSidekickMcpServer

Registers a custom MCP server for Sidekick and mints a Nango Connect session for in-browser OAuth consent. The server is initially created in an unreachable state and requires a subsequent call to completeSidekickMcpServerConnection after consent.

```APIDOC
## mutation createSidekickMcpServer

### Description
Registers a custom (customer-owned) MCP server for Sidekick and mints a Nango Connect session for in-browser OAuth consent. The server is created in an unreachable state; call completeSidekickMcpServerConnection after consent to discover its tools and mark it connected.
```

--------------------------------

### DeleteCustomerGroup Response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteCustomerGroup

Example JSON response structure for the deleteCustomerGroup mutation.

```json
{
  "data": {
    "deleteCustomerGroup": {
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### deleteWorkspaceFile Response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteWorkspaceFile

Example JSON response structure for the deleteWorkspaceFile mutation.

```json
{
  "data": {
    "deleteWorkspaceFile": {
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Mutation response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteMyFavoritePage

Example of the JSON response structure returned by the mutation.

```json
{
  "data": {
    "deleteMyFavoritePage": {
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Initialize the Plain GraphQL client

Source: https://www.plain.com/docs/agents/machine-users

Use the PlainClient from the GraphQL SDK to interact with the API using an environment-stored API key.

```ts
import { PlainClient } from "@team-plain/graphql";

const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });
```

--------------------------------

### Search knowledge sources and handle results

Source: https://www.plain.com/docs/agents/searching-knowledge

Demonstrates how to query knowledge sources and use the __typename field to distinguish between help center articles and indexed documents.

```ts
const results = await plain.query.searchKnowledgeSources({
  searchQuery: "how do I reset my password?",
  pageSize: 5,
});

for (const result of results) {
  console.log(result.content);

  // Narrow on __typename to get a reference back to the source
  if (result.__typename === "HelpCenterArticleSearchResult") {
    const article = await result.helpCenterArticle;
    console.log(article.title);
  } else if (result.__typename === "IndexedDocumentSearchResult") {
    const doc = await result.indexedDocument;
    console.log(doc.url);
  }
}
```

--------------------------------

### Query Variables

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceDiscordChannelInstallationInfo

Required variables for the workspaceDiscordChannelInstallationInfo query.

```json
{
  "redirectUrl": "string"
}
```

--------------------------------

### createDemoChannel

Source: https://www.plain.com/docs/graphql-reference/mutations/createDemoChannel

Creates or reuses a demo channel on a specified integration, invites the user, and seeds a demo thread.

```APIDOC
## mutation createDemoChannel

### Description
Creates (or reuses) a demo channel on the given integration's support channel (e.g. a demo Slack channel), invites the installing user, and seeds a demo customer thread so the integration can be tried out before going live.
```

--------------------------------

### Delete Customer Survey Response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteCustomerSurvey

Example response structure for the deleteCustomerSurvey mutation.

```json
{
  "data": {
    "deleteCustomerSurvey": {
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### DeleteChatApp Mutation Response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteChatApp

Example JSON response structure for the deleteChatApp mutation.

```json
{
  "data": {
    "deleteChatApp": {
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Get a thread by ID

Source: https://www.plain.com/docs/graphql/threads/get

Retrieves a specific thread using its unique identifier.

```APIDOC
## GraphQL Query: thread

### Description
Fetches a single thread by its unique ID. Requires `thread:read` permission.
```

--------------------------------

### helpCenterArticleBySlug

Source: https://www.plain.com/docs/graphql-reference/queries/helpCenterArticleBySlug

Fetches an article by its URL slug within a specific help center. Returns null if no article matches.

```APIDOC
## helpCenterArticleBySlug

### Description
Fetches an article by its URL slug within a specific help center. Slugs are unique per help center. Returns null if no article matches.
```

--------------------------------

### WorkflowTemplate Query Response

Source: https://www.plain.com/docs/graphql-reference/queries/workflowTemplate

Example JSON response structure for a successful workflowTemplate query.

```json
{
  "data": {
    "workflowTemplate": {
      "id": "id",
      "title": "string",
      "content": [
        {
          "type": "string",
          "value": "string"
        }
      ],
      "tags": [
        "string"
      ],
      "isFeatured": true,
      "author": "string"
    }
  }
}
```

--------------------------------

### Webhook Targets Response Format

Source: https://www.plain.com/docs/graphql-reference/queries/webhookTargets

Example JSON response structure for the webhookTargets query.

```json
{
  "data": {
    "webhookTargets": {
      "edges": [
        {
          "cursor": "string",
          "node": {
            "id": "id",
            "url": "string",
            "description": "string",
            "eventSubscriptions": [
              {
                "__typename": "WebhookTargetEventSubscription"
              }
            ],
            "version": "string",
            "isEnabled": true
          }
        }
      ],
      "pageInfo": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "startCursor": "string",
        "endCursor": "string"
      }
    }
  }
}
```

--------------------------------

### helpCenter

Source: https://www.plain.com/docs/graphql-reference/queries/helpCenter

Fetches a single help center by its ID. Returns null if the help center is not found.

```APIDOC
## helpCenter

### Description
Fetches a single help center by ID. Returns null if not found.

### Query
query helpCenter($id: ID!) {
  helpCenter(id: $id) {
    id
    name
  }
}
```

--------------------------------

### Workflow Query Response

Source: https://www.plain.com/docs/graphql-reference/queries/workflow

Example JSON response structure for a successful workflow query.

```json
{
  "data": {
    "workflow": {
      "id": "id",
      "name": "string",
      "trigger": "string",
      "startStepId": "id",
      "steps": [
        {
          "id": "id",
          "workflowId": "id",
          "type": "CONDITION",
          "name": "string",
          "payload": "string",
          "transitions": [
            "id"
          ]
        }
      ],
      "publishedAt": {
        "unixTimestamp": "string",
        "iso8601": "string"
      }
    }
  }
}
```

--------------------------------

### Delete Webhook Target Response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteWebhookTarget

Example JSON response structure for the deleteWebhookTarget mutation.

```json
{
  "data": {
    "deleteWebhookTarget": {
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Delete API Key Response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteApiKey

Example response structure returned by the deleteApiKey mutation.

```json
{
  "data": {
    "deleteApiKey": {
      "apiKey": {
        "id": "id",
        "description": "string",
        "permissions": [
          "string"
        ],
        "createdBy": {
          "__typename": "UserActor"
        },
        "createdAt": {
          "unixTimestamp": "string",
          "iso8601": "string"
        },
        "updatedBy": {
          "__typename": "UserActor"
        }
      },
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### createEscalationPath

Source: https://www.plain.com/docs/graphql-reference/mutations/createEscalationPath

Creates a new escalation path with a name, optional description, and an ordered list of up to 20 steps.

```APIDOC
## mutation createEscalationPath

### Description
Creates a new escalation path with the given name, optional description, and an ordered list of steps (up to 20). Each step routes the thread to either a specific user or the owners of a label type. Steps must not contain duplicates.

### Requirements
- Permission: `escalationPath:create`
- Feature Entitlement: Escalation paths
```

--------------------------------

### Get a discussion by ID

Source: https://www.plain.com/docs/graphql/discussions/get

Retrieves the details of a specific discussion using its unique ID.

```APIDOC
## Get a discussion by ID

### Description
Use this query to fetch the full details of a single discussion by providing its unique identifier.
```

--------------------------------

### Workflow Executions Query Response

Source: https://www.plain.com/docs/graphql-reference/queries/workflowExecutions

Example JSON response structure returned by the workflowExecutions query.

```json
{
  "data": {
    "workflowExecutions": {
      "edges": [
        {
          "cursor": "string",
          "node": {
            "id": "id",
            "workflowId": "id",
            "workflow": {
              "__typename": "Workflow"
            },
            "triggeredBy": "string",
            "executionStatus": "QUEUED",
            "errorMessage": "string"
          }
        }
      ],
      "pageInfo": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "startCursor": "string",
        "endCursor": "string"
      }
    }
  }
}
```

--------------------------------

### Delete Microsoft Teams Integration Response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteMyMSTeamsIntegration

Example JSON response structure for the deleteMyMSTeamsIntegration mutation.

```json
{
  "data": {
    "deleteMyMSTeamsIntegration": {
      "integration": {
        "id": "id",
        "msTeamsTenantId": "id",
        "isReinstallRequired": true,
        "msTeamsPreferredUsername": "string",
        "createdAt": {
          "unixTimestamp": "string",
          "iso8601": "string"
        },
        "createdBy": {
          "__typename": "UserActor"
        }
      },
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Implement a basic webhook-based agent

Source: https://www.plain.com/docs/agents

Uses Express to listen for thread creation events, verifies the webhook signature, and replies to the thread using the Plain GraphQL client.

```ts
import express from "express";
import { verifyPlainWebhook } from "@team-plain/webhooks";
import { PlainClient } from "@team-plain/graphql";

const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });

const app = express();
app.use(express.text({ type: "*/*" })); // we need the raw body for signature verification

app.post("/webhooks/plain", async (req, res) => {
  const result = verifyPlainWebhook(
    req.body,
    req.header("plain-request-signature")!,
    process.env.PLAIN_WEBHOOK_SECRET!,
  );

  if (result.error) {
    return res.status(400).send(result.error.message);
  }

  const event = result.data;

  if (event.payload.eventType === "thread.thread_created") {
    const reply = await generateReply(event.payload.thread); // your AI goes here

    await plain.mutation.replyToThread({
      input: {
        threadId: event.payload.thread.id,
        textContent: reply,
      },
    });
  }

  res.sendStatus(200);
});

app.listen(3000);
```

--------------------------------

### Delete AI Tone Rules Response

Source: https://www.plain.com/docs/graphql-reference/mutations/deleteAiToneRules

Example JSON response structure for the deleteAiToneRules mutation.

```json
{
  "data": {
    "deleteAiToneRules": {
      "error": {
        "message": "string",
        "type": "VALIDATION",
        "code": "string",
        "fields": [
          {
            "field": "string",
            "message": "string",
            "type": "VALIDATION"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### GET /snippets

Source: https://www.plain.com/docs/graphql-reference/queries/snippets

Retrieves a paginated list of all snippets in the workspace. Requires the snippet:read permission.

```APIDOC
## GET /snippets

### Description
Returns a paginated list of all snippets in the workspace. This endpoint supports standard forward and backward cursor pagination.

### Method
GET

### Endpoint
/snippets

### Permissions
- snippet:read
```

--------------------------------

### Discord Channel Integrations Response Format

Source: https://www.plain.com/docs/graphql-reference/queries/userAuthDiscordChannelIntegrations

Example JSON response structure returned by the userAuthDiscordChannelIntegrations query.

```json
{
  "data": {
    "userAuthDiscordChannelIntegrations": {
      "edges": [
        {
          "cursor": "string",
          "node": {
            "id": "id",
            "discordGuildId": "string",
            "discordUserId": "string",
            "discordUsername": "string",
            "discordGlobalName": "string",
            "discordUserEmail": "string"
          }
        }
      ],
      "pageInfo": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "startCursor": "string",
        "endCursor": "string"
      }
    }
  }
}
```

--------------------------------

### searchPlainHelpCenter

Source: https://www.plain.com/docs/graphql-reference/queries/searchPlainHelpCenter

Performs a semantic search across Plain's public help center documentation. This query is read-only and restricted to public product documentation.

```APIDOC
## GraphQL Query: searchPlainHelpCenter

### Description
Performs a semantic (vector) search across Plain's public help center (help.plain.com). This query is designed to help Sidekicks answer questions about how Plain works.

### Parameters
- **query** (String) - Required - The search term or question to perform a semantic search against.
- **pageSize** (Int) - Optional - The number of results to return (default: 10, max: 50).

### Behavior
- Read-only access to public product documentation.
- Results are ranked by relevance.
- Does not return caller data or other workspace content.
```

--------------------------------

### updateHelpCenter

Source: https://www.plain.com/docs/graphql-reference/mutations/updateHelpCenter

Updates the configuration of an existing help center.

```APIDOC
## mutation updateHelpCenter

### Description
Update the settings, branding, or access configuration of an existing help center. Only fields that are provided are updated.

### Permissions
Requires the `helpCenter:edit` permission.
```

--------------------------------

### scheduleBroadcast

Source: https://www.plain.com/docs/graphql-reference/mutations/scheduleBroadcast

Queues a broadcast to be sent, moving it from DRAFT to SCHEDULED. If called again before sending starts, it updates the scheduled time.

```APIDOC
## mutation scheduleBroadcast

### Description
Queues a broadcast to be sent, moving it from `DRAFT` to `SCHEDULED`. Calling this again on a broadcast that has not started sending changes when it will go out; once the send has started it is rejected.

### Requirements
- Requires `broadcast:send` permission
- Requires `broadcast:read` permission
- Broadcast must have a sender and at least one channel defined.
```

--------------------------------

### Fetch a customer by email using cURL

Source: https://www.plain.com/docs/graphql/introduction

Demonstrates how to query the GraphQL API for customer details using an email address and an API key.

```shell
PLAIN_TOKEN=XXX
PLAIN_CUSTOMER_EMAIL=XXX
curl -X POST https://core-api.uk.plain.com/graphql/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PLAIN_TOKEN" \
  -d '{"query":"query customerByEmail($email: String!) { customerByEmail(email: $email) { id fullName updatedAt { iso8601 } } }","variables":{"email":"'"$PLAIN_CUSTOMER_EMAIL"'"},"operationName":"customerByEmail"}'
```

--------------------------------

### createDiscussion

Source: https://www.plain.com/docs/graphql-reference/mutations/createDiscussion

Creates a new discussion. This mutation supersedes createThreadDiscussion and supports AGENT_SESSION discussions, which can be started without a thread.

```APIDOC
## mutation createDiscussion

### Description
Creates a new discussion. Supersedes createThreadDiscussion and additionally supports Sidekick AGENT_SESSION discussions (which can be started without a thread). For Slack, Email, and Cursor discussion types, a threadId is required. For AGENT_SESSION discussions, threadId is optional and the discussion may be associated with a source entity (company, tenant, etc.) or page instead.
```

--------------------------------

### Get a thread by external ID

Source: https://www.plain.com/docs/graphql/threads/get

Retrieves a thread using an external ID, which requires the associated customer ID.

```APIDOC
## GraphQL Query: threadByExternalId

### Description
Fetches a thread using an `externalId` unique to a customer. Requires both `externalId` and `customerId`. Requires `thread:read` permission.
```

--------------------------------

### mutation startServiceAuthorization

Source: https://www.plain.com/docs/graphql-reference/mutations/startServiceAuthorization

Initiates the OAuth authorization flow for a third-party service integration.

```APIDOC
## mutation startServiceAuthorization

### Description
Begins the OAuth authorization flow for a third-party service integration. Returns connection details including a serviceAuthorizationId and an HMAC digest that must be passed to the authorization URL to securely link the callback back to this workspace.

### Response
- **serviceAuthorizationId** (ID) - The unique identifier for the authorization session.
- **hmac** (String) - The HMAC digest required for secure callback verification.
```

--------------------------------

### workspaceMSTeamsInstallationInfo

Source: https://www.plain.com/docs/graphql-reference/queries/workspaceMSTeamsInstallationInfo

Retrieves the Microsoft Teams admin-consent URL. The query accepts a redirectUrl parameter to specify where the user should be sent after consent.

```APIDOC
## GraphQL Query: workspaceMSTeamsInstallationInfo

### Description
Returns the Microsoft Teams admin-consent URL that a workspace administrator must visit to authorize Plain's bot for the workspace's Azure AD tenant. If the workspace already has an integration, the URL is scoped to that tenant.

### Arguments
- **redirectUrl** (String) - The URL the user should be redirected to after consent.

### Response
- **url** (String) - The admin-consent URL for the Microsoft Teams integration.
```

--------------------------------

### sidekickMcpServer

Source: https://www.plain.com/docs/graphql-reference/queries/sidekickMcpServer

Retrieves a single custom MCP server by its unique identifier. Returns null if the server does not exist in the current workspace.

```APIDOC
## sidekickMcpServer

### Description
Fetches a single custom MCP server by its ID. If no server is found with the provided ID, the query returns null.

### Query
sidekickMcpServer(id: ID!)

### Parameters
- **id** (ID!) - Required - The unique identifier of the MCP server.
```

--------------------------------

### Upload attachment via multipart/form-data

Source: https://www.plain.com/docs/graphql/attachments

Examples for uploading the file data to the generated URL using browser-based FormData or Node.js.

```javascript
const formData = new FormData();

// Add the fields from uploadFormData
attachmentUploadUrl.uploadFormData.forEach(({ name, value }) => {
  formData.append(name, value);
});

// Add the file itself
formData.append('file', file);

await fetch(attachmentUploadUrl.uploadFormUrl, {
  method: 'POST',
  body: formData,
});
```

```javascript
const FormData = require('form-data');
const axios = require('axios');
const fs = require('fs');

const formData = new FormData();

// Add the fields from uploadFormData
attachmentUploadUrl.uploadFormData.forEach(({ name, value }) => {
  formData.append(name, value);
});

// Add the file itself
formData.append('file', fs.createReadStream('path/to/file.pdf'));

await axios.post(attachmentUploadUrl.uploadFormUrl, formData, {
  headers: formData.getHeaders(),
});
```

--------------------------------

### setupTenantFieldSchemaMapping

Source: https://www.plain.com/docs/graphql-reference/mutations/setupTenantFieldSchemaMapping

Maps a tenant field schema to a built-in Plain concept such as TIER, enabling automatic tier assignment based on the field's value. Only one schema can be mapped to a given concept at a time.

```APIDOC
## mutation setupTenantFieldSchemaMapping

### Description
Maps a tenant field schema to a built-in Plain concept such as `TIER`, enabling automatic tier assignment based on the field's value. Only one schema can be mapped to a given concept at a time.
```
Tokens:
Raw