Skip to main content
The Plain integration captures support threads from your Plain workspace in real time. Customer emails, chat messages, and your team’s internal notes flow into Modem, where they are grouped into topics, classified by type, and linked to the people and companies behind them. The Modem Agent can also act on Plain directly: look up threads and customers, reply to customers, add internal notes, and change a thread’s status, priority, labels, and assignee.

​
How it works

Modem connects to Plain with a machine-user API key you create in your Plain workspace. When you paste the key, Modem validates it, fetches your workspace’s Request signing secret, and registers a webhook target in Plain automatically. From then on Plain pushes thread activity to Modem as it happens; every delivery is verified against the signing secret before it’s processed. API keys in Plain don’t expire, so there’s no re-authorization cycle. Capture is webhook-based and real-time: a new customer message typically shows up in Modem within a few minutes.

​
Prerequisites

  • Owner or admin role in your Modem organization, to connect and manage the integration
  • Access to create machine users and API keys in your Plain workspace

​
Setup

1

Create a machine-user API key in Plain

In Plain, go to Settings → Machine users / API keys and create a key. See Permissions below for what it needs.
2

Paste the key into Modem

Go to Settings → Integrations → Plain in your Modem dashboard, paste the key, and click Connect Plain. Modem encrypts the key before storing it.
3

Modem registers its webhook

Modem validates the key, reads your workspace’s Request signing secret, and registers a webhook target in Plain. New thread activity starts flowing immediately.
4

Optionally run a backfill

Import recent existing threads so ongoing conversations show up too. See Historical Backfill below.

​
Permissions

The machine-user API key needs these permissions for capture: To let the agent act on Plain, also grant the permissions for the actions you want it to take: Leave these out to keep the agent read-only in Plain. If the agent tries an action the key isn’t allowed to take, Plain rejects it and the agent tells you which permission is missing.
If your key can’t be granted workspaceHmac:read, use the enter it manually option on the connect form and paste the secret from Plain under Settings → Request signing instead.

​
What Gets Captured

​
Thread messages

For each Plain thread, Modem captures the timeline as a single conversation:
  • Customer emails received and support replies sent
  • Chat messages from both sides
  • Internal notes written by your team, marked as internal
Email bodies are cleaned before they’re stored: quoted-reply chains and signature blocks are stripped, and inline attachment data is collapsed to a short placeholder. Attachment files themselves are not ingested.

​
Thread metadata

Each thread’s title, status, priority, labels, assignee, and a link back to the thread in Plain. Status, priority, and label changes are recorded on the conversation timeline for context. Only real messages feed topic analysis.

​
Customers

Plain customer profiles (name and email) sync as they’re created and updated, and message authors are resolved to Modem people by email address. For live activity, your own teammates are matched to their real email addresses too, so support replies link to existing team members instead of creating duplicates. Backfilled history uses teammates’ display names only. Plain’s automation and system actors are flagged as bots.

​
Historical Backfill

Connecting only captures activity from that point forward. To pull in recent history, run the optional backfill from Settings → Integrations → Plain: it imports threads created in the last 30 days, up to 500 threads, along with their messages. The backfill runs in the background and doesn’t block real-time capture. Plain’s API is rate-limited, so a busy workspace can take a while; the card shows progress and you can re-run it if it fails.

​
Using the Agent with Plain

The Modem Agent can query your captured Plain data like any other source, and it can act on Plain directly through Plain’s GraphQL API: looking up live threads, customers, and labels; replying to customers; adding internal notes; and changing a thread’s status, priority, labels, and assignee.
  • Approval prompts. Every action asks for your approval in the chat before it runs, unless you chose to always approve that action. Lookups never need approval.
  • Replies reach the customer. A reply is sent to the customer through the thread’s channel, usually email. Use an internal note for anything only your team should see.
Plain attributes API actions to the machine user that owns the API key, so agent replies and notes appear in Plain under that machine user. Customers see the machine user’s public name.

​
Troubleshooting

The most common gap is workspaceHmac:read: without it Modem can’t fetch the Request signing secret automatically. Grant the permission to the machine user, or use the manual fallback on the connect form and paste the secret from Plain under Settings → Request signing. Also confirm the key has read access to threads and customers plus webhookTarget:create.
The API key is missing the permission for that action. The agent’s error names the permission Plain asked for. Add it to the machine user’s API key in Plain; see the agent actions table under Permissions.
Confirm the integration shows as connected in Settings → Integrations → Plain, then allow a few minutes for webhook delivery and processing. Modem only captures activity that happens after you connect; run the backfill for recent existing threads. If nothing arrives, disconnecting and reconnecting registers a fresh webhook target.
The backfill covers threads created in the last 30 days, up to 500 threads, so older or excess threads aren’t imported. If a run failed, the card shows the error and a Run again button; re-running is safe and won’t duplicate messages. If it still looks wrong, contact support@modem.dev.
Message authors are matched to Modem people by email address. If a Plain customer has no email on their profile, their activity won’t be linked automatically.

​
Disconnecting

To disconnect Plain:
  1. Go to Settings → Integrations → Plain
  2. Click Disconnect and confirm
Modem stops accepting deliveries from the workspace and attempts to remove the webhook target it registered in Plain. Removal is best-effort: if the stored API key has already been revoked or Plain’s API is unavailable, the disconnect still completes and you may need to delete the target in Plain yourself. Historical data remains in Modem after disconnecting.

The Modem Agent

Query and act on your captured Plain conversations from the web.

Topics

See how support threads are grouped into themes and classified.

Companies & People

Understand how Plain customers are linked into unified profiles.

All Integrations

Browse every data source and agent tool.