> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Plain

## Overview

Connect your ElevenLabs AI agents with [Plain](https://www.plain.com/) to work support threads. The integration covers two scopes:

* **Tools**: leave internal notes for teammates, add and remove labels, set thread status and priority, and assign threads to teammates or to the agent itself.
* **Triggers**: automatically draft or send responses when matching Plain threads receive customer messages across email, chat, and Slack.

## Capabilities

| Capability                | Support                                                                                                                                                   |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zero retention mode (ZRM) | Not supported                                                                                                                                             |
| Attachments in triggers   | Customer-sent images (PNG, JPEG, GIF, WebP) and PDF files, when **Allow file attachments** is enabled in the agent settings — see the trigger notes below |
| Attachments in tools      | Not supported — tools operate on text only; the agent cannot send attachments back to Plain                                                               |

## Setup

This integration authenticates with a Plain machine user API key. Triggers also need the workspace request-signing secret so ElevenLabs can verify webhook deliveries.

#### Create a machine user

In Plain, go to **Settings → Machine users** and click **Add Machine User**. Enter a **name** for internal reference and a **public name**, which is shown to customers if the machine user interacts with them.

Use a dedicated machine user for the ElevenLabs agent when you plan to route threads by assignment. That keeps assignment-based reporting and human handoff clear.

#### Generate an API key

Select the machine user and click **Add API Key**. Copy the key immediately — it is not shown again after closing the dialog.

Grant the least privilege needed for the features you enable:

| Permission                                                             | Needed for                                              |
| ---------------------------------------------------------------------- | ------------------------------------------------------- |
| `thread:read`                                                          | Reading thread history for tools and triggers           |
| `thread:edit`                                                          | Status and priority tools                               |
| `thread:reply`                                                         | Direct customer replies from the trigger                |
| `thread:search`                                                        | Looking up threads when using tools                     |
| `thread:assign` / `thread:unassign`                                    | Assignment tools and assignment-based routing           |
| `note:create`                                                          | Internal note tools                                     |
| `label:create` / `label:delete`                                        | Label tools                                             |
| `threadFieldSchema:read`                                               | Reading thread field schemas (type and allowed values)  |
| `threadField:create` / `threadField:update` / `threadField:delete`     | Thread field tools                                      |
| `generatedReply:create`                                                | Suggested replies from the trigger (default mode)       |
| `customer:read`                                                        | Customer context and dynamic variables on trigger turns |
| `attachment:download`                                                  | Downloading customer-sent images/files for the agent    |
| `webhookTarget:create` / `webhookTarget:read` / `webhookTarget:delete` | Automatic trigger webhook setup and cleanup             |

To give the API key all required permissions, copy the full permission list, and click the From clipboard into the API key dialog:

```text
thread:read,thread:edit,thread:reply,thread:search,thread:assign,thread:unassign,note:create,label:create,label:delete,threadField:create,threadField:update,threadField:delete,generatedReply:create,customer:read,attachment:download,webhookTarget:create,webhookTarget:read,webhookTarget:delete
```

The interface should look like this:

![Plain API key permissions dialog with the From clipboard button](/docs/_fern-files/_img/485ab9c85e5f1b989045cc440a43dfcc6f16c3bac0196f3eb407ccb473a2c651.webp)

Do not grant `workspaceHmac:edit`. ElevenLabs never rotates Plain's workspace signing secret.

#### Connect in ElevenLabs

In the ElevenLabs integration setup, enter the **API key**.

#### Copy the workspace request-signing secret

Triggers verify every Plain webhook with the workspace HMAC secret.

1. In Plain, open **Settings → Request signing**.
2. View or generate the workspace request-signing secret.
3. Copy it. You will paste it into the trigger setup in the next step.

This secret is workspace-global: rotating it affects every webhook target in the Plain workspace. Prefer viewing the existing secret over regenerating it unless you intend to update every consumer.

## Triggers

Enable the **Thread event** trigger when you want the agent to respond automatically to customer activity on Plain threads. On activation, ElevenLabs creates an enabled Plain webhook target for your workspace. Deactivating the trigger deletes that target. You do not need to paste a webhook URL into Plain manually.

### Create the trigger

Open the **Triggers** tab of the Plain integration and enable **Thread event**. Fill in:

| Field                      | Description                                                                                                           |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Agent**                  | The ElevenLabs agent that should handle matching Plain threads. Branch selection is supported.                        |
| **Request signing secret** | The workspace secret from **Settings → Request signing**. Stored encrypted; not shown again in public trigger config. |
| **Routing mode**           | Process all threads, or only threads assigned to this API key's machine user. Defaults to all threads.                |
| **Channel filter**         | All supported channels, or restrict to email, chat, or Slack. Defaults to all.                                        |
| **Response mode**          | Suggested reply (default) or direct customer reply.                                                                   |

Only one Thread event trigger is allowed per Plain API connection. Overlapping all-thread triggers on separate connections to the same Plain workspace can produce duplicate responses — avoid that setup.

Changing response mode, routing, or channel filter requires deleting and recreating the trigger.

### Routing: all threads vs assigned

Plain API keys can read workspace data, but each key belongs to a specific machine user. That machine user is the author identity for replies and can also be assigned threads. Assignment is a routing convention, not an API authorization boundary.

* **All threads** (default): process customer messages from supported threads visible to the connection, subject to the channel filter. Assignment events are ignored.
* **Assigned to machine user**: only act when the thread's primary assignee is the machine user for this API key. ElevenLabs resolves that identity automatically — you do not enter a machine-user ID. Assignment transitions wake the agent so a workflow or teammate can hand a thread over after it already has customer messages.

For richer conditions (labels, customer tier, support hours, tenant), configure a Plain workflow that assigns matching threads to the machine user, then use **Assigned to machine user** routing.

### Recording replies after handover

After a thread is handed over or escalated to a teammate, the agent stops replying, but the teammate's replies are still recorded in the same ElevenLabs conversation and marked as human replies. Use them in analytics and Architect queries to see how humans resolved what the agent handed off. Only conversations the agent already handled are recorded, and recording never sends anything to the customer. Attachments on teammate replies are not recorded.

Recording is rolling out gradually and may not be enabled for your workspace yet. Triggers created before it was available are not subscribed to outbound events: deactivate and reactivate the trigger in ElevenLabs, or enable `thread.email_sent`, `thread.chat_sent`, and `thread.slack_message_sent` on its webhook target in Plain.

### Channel filter

Supported customer channels in v1:

* **All** — email, chat, and Slack
* **Email**
* **Chat**
* **Slack**

Microsoft Teams and Discord are not supported yet. Slack message edits are also unsupported because Plain does not emit another received-message event for an edit.

### Suggested vs direct replies

* **Suggested reply** (default): posts a Plain generated reply for human review via `addGeneratedReply`. Safe for initial rollout; teammates can accept, edit, or discard it.
* **Direct reply**: posts a customer-visible reply via `replyToThread`. Use only after you trust the agent in a safe inbox. The reply is attributed to the API key's machine user. Replies go out as the agent speaks, in conversation order. If the agent talks, uses a tool, then talks again, the customer sees two messages. On email, that is two emails.

Agent replies use markdown (headings, bold, lists, links, and code). Direct replies also include a plain-text fallback for clients that do not render markdown.

### Plain workflows

A common pattern:

1. Create a dedicated machine user and API key for the agent.
2. Build a Plain workflow that assigns selected threads (by label, channel, tier, or other conditions) to that machine user.
3. Enable the Thread event trigger in **Assigned to machine user** mode with **Suggested reply**.
4. After validating quality, recreate the trigger in **Direct reply** mode if you want autonomous customer-facing replies.
5. To escalate to a human, reassign the thread away from the machine user — assignment mode stops further agent output.

### Verify the setup

1. Confirm an enabled webhook target appears under **Plain Settings → Webhooks** after you create the trigger.
2. Create a test thread on a channel allowed by your filter.
3. For assignment mode, assign the thread to the machine user.
4. Confirm one ElevenLabs conversation appears. In suggested mode you should see one generated-reply draft. In direct mode you may see more than one customer message if the agent spoke more than once.
5. Send a follow-up and confirm the same conversation resumes without duplicate replies.

If nothing arrives, check the request-signing secret, API key permissions (especially webhook target and reply scopes), routing mode, and channel filter.

## Limitations

* Webhook processing runs in-process after ElevenLabs returns `200`. Work can be lost if the process stops before the turn finishes. Plain may retry the delivery, but a retry after a partial failure can result in more than one reply for the same customer message.
* Trigger activation and local persistence are not transactional. A rare failure window can leave a Plain webhook target without a matching ElevenLabs trigger (or the reverse on deactivation). Orphan targets can be removed under **Plain Settings → Webhooks**.
* Plain has no way to recognize a repeated reply request as a duplicate, so if ElevenLabs crashes right after Plain accepts a reply, retrying can post the same reply twice.
* Rotating the workspace HMAC requires updating or recreating every trigger that stores the old secret.
* Each trigger consumes one of Plain's 25 webhook targets per workspace.
* Inbound attachments (images/files a customer sends) are downloaded and passed to the agent when the agent has file input enabled, subject to Plain's virus scan result and the agent's normal file size/type limits. This includes images pasted directly into an email body, which Plain omits from the normal attachments list and embeds in the message markdown instead. The machine user's API key needs the `attachment:download` permission for this. Outbound attachments (the agent sending a file back to Plain) are not supported yet.
* The integration uses Plain's UK GraphQL endpoint.
* Threads use bounded recent history: at most 1,000 messages (50 per page, up to 20 pages), fetched most recent first. Older messages in longer threads are not included as context.

## Plain tools

Add Plain tools to your agent to manage support threads during conversations. Once the integration is connected, you can enable individual tools on your agent's configuration page.

### Available tools

The integration provides fourteen tools for working a thread:

* **Fetch thread information** — fetch a thread's metadata: status, priority, assignee, and labels.
* **Create internal note** — record analysis, context, or follow-up items on a thread. Notes are only visible to teammates, never to the customer.
* **Update labels** — add and remove labels on a thread in a single call.
* **Set thread status** — set a thread's status using the statuses shown in Plain's UI.
* **Mark thread as done** — mark a thread as done when there is nothing left to do.
* **Mark thread as todo** — move a thread back to todo, undoing a done or snoozed state.
* **Snooze thread** — snooze a thread for a duration of time.
* **Set thread priority** — set the thread priority to urgent, high, normal, or low.
* **Assign thread** — assign a thread to a teammate or to a machine user.
* **Unassign thread** — remove the current assignee from a thread.
* **Upsert thread field** — set a custom thread field's value on a thread.
* **Bulk upsert thread fields** — set multiple custom thread field values in a single call.
* **Fetch thread field schemas** — look up the configured type and allowed values of one or more thread fields.
* **Clear thread field** — remove a custom thread field's stored value from a thread.

### Tool reference

#### plain_fetch_thread_information

Fetches a thread's metadata: status, priority, assignee, and labels. Useful for gathering context before triaging or annotating a thread. The tool intentionally does not return the thread's content (title, description, preview text) or customer details, so it cannot leak another customer's data if called with an arbitrary thread ID.

| Parameter   | Type   | Description         |
| ----------- | ------ | ------------------- |
| `thread_id` | string | The thread to fetch |

#### plain_create_internal_note

Adds an internal note to a thread. Useful for posting summaries, findings, or handover context for teammates.

| Parameter     | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| `thread_id`   | string | The thread to add the note to      |
| `customer_id` | string | The customer the thread belongs to |
| `text`        | string | Note content in plain text         |

#### plain_update_labels

Adds and/or removes labels on a thread in one call. At least one of the two lists must be provided.

| Parameter               | Type   | Description                                    |
| ----------------------- | ------ | ---------------------------------------------- |
| `thread_id`             | string | The thread to update                           |
| `label_type_ids_to_add` | array  | Label type IDs of the labels to add            |
| `label_ids_to_remove`   | array  | IDs of label instances currently on the thread |

Adding and removing use different identifiers. Adding takes **label type IDs**, which you can copy in Plain under **Settings > Labels** by hovering over a label type and selecting **Copy label ID**. Removing takes the IDs of the **label instances** on the thread, which are returned when labels are added.

#### plain_set_thread_status

Sets a thread's status, the options match the available statuses in the plain UI.

| Parameter          | Type    | Description                                                                                          |
| ------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
| `thread_id`        | string  | The thread to update                                                                                 |
| `status`           | string  | The status to set; see the table below                                                               |
| `duration_seconds` | integer | How long to snooze for. Only valid with `paused_for_later`; omit it to pause the thread indefinitely |

| `status`               | Plain UI group | Plain UI label       | Meaning                                                         |
| ---------------------- | -------------- | -------------------- | --------------------------------------------------------------- |
| `needs_first_response` | Todo           | Needs first response | No one has replied yet                                          |
| `needs_next_response`  | Todo           | Needs next response  | The customer replied and is waiting on us                       |
| `investigating`        | Todo           | Investigating        | Actively being worked on                                        |
| `close_the_loop`       | Todo           | Close the loop       | A linked issue was updated, so the customer needs an update     |
| `waiting_for_customer` | Snoozed        | Waiting for customer | We replied and are snoozed until the customer replies           |
| `paused_for_later`     | Snoozed        | Paused for later     | Parked until the duration runs out, or indefinitely without one |
| `done`                 | Done           | Done                 | Nothing left to do                                              |
| `ignored`              | Done           | Ignored              | No action needed at all, for example spam                       |

Snoozed threads move back to todo when their timer runs out and, either way, as soon as there is new activity.

#### plain_mark_thread_as_done

Marks a thread as done. In Plain, done means "nothing left to do for now" — any new activity moves the thread back to todo.

| Parameter       | Type   | Description                                                                                                  |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `thread_id`     | string | The thread to update                                                                                         |
| `status_detail` | string | Optional detail recorded with the status change: `done_manually_set`, `done_automatically_set`, or `ignored` |

#### plain_mark_thread_as_todo

Moves a thread back to todo, for example to undo marking it as done or to unsnooze it.

| Parameter       | Type   | Description                                                                                                                                    |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `thread_id`     | string | The thread to update                                                                                                                           |
| `status_detail` | string | Optional detail recorded with the status change: `created`, `in_progress`, `new_reply`, `thread_discussion_resolved`, or `thread_link_updated` |

#### plain_snooze_thread

Snoozes a thread. The thread moves back to todo when the timer runs out or when there is new activity.

| Parameter          | Type    | Description                                                                                |
| ------------------ | ------- | ------------------------------------------------------------------------------------------ |
| `thread_id`        | string  | The thread to update                                                                       |
| `duration_seconds` | integer | How long to snooze for; defaults to one day                                                |
| `status_detail`    | string  | Optional detail recorded with the snooze: `waiting_for_customer` or `waiting_for_duration` |

#### plain_set_priority

Sets the priority of a thread.

| Parameter   | Type   | Description                          |
| ----------- | ------ | ------------------------------------ |
| `thread_id` | string | The thread to update                 |
| `priority`  | string | `urgent`, `high`, `normal`, or `low` |

#### plain_assign_thread

Assigns a thread to a user or a machine user. Provide exactly one of `user_id` or `machine_user_id`.

| Parameter         | Type   | Description                                                                        |
| ----------------- | ------ | ---------------------------------------------------------------------------------- |
| `thread_id`       | string | The thread to assign                                                               |
| `user_id`         | string | The user to assign the thread to                                                   |
| `machine_user_id` | string | The machine user to assign the thread to, for example the agent's own machine user |

#### plain_unassign_thread

Removes the current assignee from a thread.

| Parameter   | Type   | Description            |
| ----------- | ------ | ---------------------- |
| `thread_id` | string | The thread to unassign |

#### plain_upsert_thread_field

Sets a custom thread field's value on a thread, creating it if it does not already have a value. The field must already be configured in Plain under **Settings > Thread fields**. Provide exactly one of the value parameters below, matching the field's configured type, or Plain rejects the call.

| Parameter        | Type    | Description                                                                          |
| ---------------- | ------- | ------------------------------------------------------------------------------------ |
| `thread_id`      | string  | The thread to update                                                                 |
| `key`            | string  | The stable key of the thread field                                                   |
| `string_value`   | string  | Value for a STRING-typed field                                                       |
| `enum_value`     | string  | Value for an ENUM-typed field; must be one of the field's predefined allowed options |
| `bool_value`     | boolean | Value for a BOOL-typed field                                                         |
| `number_value`   | number  | Value for a NUMBER-typed field                                                       |
| `currency_value` | number  | Value for a CURRENCY-typed field                                                     |
| `datetime_value` | string  | Value for a DATE-typed field, as an ISO 8601 datetime string                         |

#### plain_bulk_upsert_thread_fields

Sets multiple custom thread field values in one call, each creating the field's value if it does not already have one. Every field must already be configured in Plain under **Settings > Thread fields**, and each entry must provide exactly one value parameter matching the field's configured type.

| Parameter       | Type  | Description                                                                                                                                                                                               |
| --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `thread_fields` | array | The fields to set. Each entry targets one field on one thread and carries the same parameters as `plain_upsert_thread_field` (`thread_id`, `key`, and exactly one typed value). Up to 50 entries per call |

Plain applies the upserts without a transaction. If any entry fails, the call is reported as failed, but upserts that already succeeded are not rolled back; the error names which fields failed and which were applied.

#### plain_fetch_thread_field_schemas

Fetches the configured schema of one or more thread fields by their thread field schema IDs, in a single call. Use this to learn a field's type and allowed values before setting it with the upsert tools.

| Parameter                 | Type  | Description                                             |
| ------------------------- | ----- | ------------------------------------------------------- |
| `thread_field_schema_ids` | array | The thread field schema IDs to fetch. Up to 50 per call |

Each returned schema includes the field's `key`, `label`, `description`, `type` (`STRING`, `ENUM`, `BOOL`, `NUMBER`, `CURRENCY`, or `DATE`), the allowed options for `ENUM` fields, whether it is required, and any default value. IDs that do not match a thread field schema in the workspace are returned in `not_found_ids`.

#### plain_clear_thread_field

Removes a custom thread field's stored value from a thread. Has no effect if the field has no value.

| Parameter   | Type   | Description                        |
| ----------- | ------ | ---------------------------------- |
| `thread_id` | string | The thread to update               |
| `key`       | string | The stable key of the thread field |

### Configuring tools

#### Add an integration tool

On your agent's configuration page, click **Add tool** and select **Add integration tool**.

#### Select Plain tools

Choose your Plain connection and toggle the tools you want the agent to use. For example, a triage agent might only need labels, priority, and assignment, while an annotating agent might also create internal notes.

#### (Optional) Provide parameters

Each tool's parameters are filled by the agent during the conversation. You can optionally pre-fill specific parameters with constants or [dynamic variables](/docs/eleven-agents/customization/personalization/dynamic-variables) — for example, supplying `customer_id` from the conversation context, or fixing `machine_user_id` to the agent's own machine user so it can assign threads to itself.

> **Note**
>
> Plain returns mutation failures in the response body rather than as HTTP errors. The tools surface
> these error messages to the agent, so it can react — for example, when a label type is archived or
> a label is already present on the thread.

## Useful links

* [Plain GraphQL API documentation](https://www.plain.com/docs/graphql)
* [Plain authentication and API keys](https://www.plain.com/docs/graphql/authentication)
* [Plain webhooks](https://www.plain.com/docs/webhooks)
* [Plain request signing](https://www.plain.com/docs/request-signing)
* [Plain agents: routing](https://www.plain.com/docs/agents/routing)
* [Machine users](https://www.plain.com/docs/agents/machine-users)
* [Labels](https://www.plain.com/docs/graphql/labels)
* [Webhook targets](https://www.plain.com/docs/graphql/webhook-targets)