Plain
Capture support threads from Plain and act on them with the agent
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 and registers a webhook target automatically. Modem generates a separate credential to authenticate deliveries, so you do not need to copy Plain’s Request signing secret.
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
Create a machine-user API key in Plain
In Plain, go to Settings → Machine users & Agents, add a machine user. Choose Agent as its type, then add an API key to it. See Permissions below for what it needs.
Paste the key into Modem
Go to Settings → Integrations → Plain in your Modem dashboard, paste the API key, and click Connect Plain. Modem encrypts the key before storing it and registers a webhook target. New thread activity starts flowing automatically.
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:
| Permission | Why Modem needs it |
|---|---|
thread:read |
Read threads and their messages (emails, chats, notes) |
timeline:read |
Import a thread’s messages when you run the backfill |
customer:read |
Link messages to the people behind them |
label:read |
Carry each thread’s labels into Modem |
machineUser:read |
Attribute threads assigned to a machine user |
user:read |
Show teammates’ real names and emails, not a placeholder |
webhookTarget:create |
Register Modem’s webhook target automatically |
webhookTarget:delete |
Remove Modem’s webhook target when you disconnect |
Plain’s permission picker opens on Most used, which leaves out some of these. Choose Copy read-only permissions to capture and analyze conversations, or Copy read and write permissions to also enable the agent actions below. Both options are available in settings and onboarding. Paste the list using From clipboard on Plain’s API key form; this replaces the current selection. Each copy button has its own expandable permission list.
Choosing the Agent machine-user type does not grant write access. The API key’s permissions control access, and write actions follow your Modem approval settings. Granting write access does not enable automatic replies or chatting with Modem inside Plain.
Once connected, Settings → Integrations → Plain checks the key and shows which of these permissions it is missing, so you can add them in one pass. Click Check again after you change the key in Plain.
To let the agent act on Plain, also grant the permissions for the actions you want it to take:
| Permission | Agent action |
|---|---|
thread:reply |
Reply to a customer on a thread |
note:create |
Add an internal note |
thread:edit |
Mark a thread done or todo, snooze it, or change its priority |
labelType:read |
Look up a label by name before adding it |
label:create, label:delete |
Add or remove labels |
thread:assign, thread:unassign |
Assign or unassign a thread |
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.
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 90 days, up to 10,000 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.
Troubleshooting
Connecting fails with a permission error
Confirm the key has thread:read, customer:read, and webhookTarget:create. Copy the permission list from Modem’s connect form
and paste it with From clipboard on Plain’s API key form.
The backfill fails with a missing permission
The error names the permission the key is missing, such as thread:read. Add it to the machine user’s API key in Plain, then click
Run again. To see every missing permission at once, open Settings → Integrations → Plain.
The agent can't reply, add notes, or change threads
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.
New threads aren't appearing
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 seems incomplete
The backfill covers threads created in the last 90 days, up to 10,000 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.ai.
Authors aren't linking to people
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:
- Go to Settings → Integrations → Plain
- 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.