Machine users

Give your agent its own identity in Plain, so its actions are attributable and permissioned.

In Plain, an agent is represented as a machine user. This is the same primitive used for any automation or integration, but it’s the right home for an agent because it gives your agent a name, an avatar, and an audit trail that’s distinct from any human user.

Machine users can be assigned threads, can reply to customers, can be @-mentioned, and show up in the timeline as the author of any message they send. When a customer sees a reply from your agent, they see the machine user’s public name and avatar.

Create a machine user

1. Add the machine user

   Go to Settings → Machine Users and click + Add Machine User.

   Two fields matter:

   • Name: only visible to your team. Use this to describe what the agent does, e.g. “Support Agent” or “Tier 1 Triage Bot”.
   • Public name: visible to customers when the agent sends a message, e.g. “Plainey” or “Acme Support”.

   You can also upload an avatar, which appears next to messages sent by the agent.

2. Create an API key

   From the machine user’s page, click + Add API key and pick the permissions your agent needs.

   Common permissions for an agent that reads threads and replies to customers:

   • thread:read: read threads and timelines
   • thread:reply: send replies via replyToThread
   • generatedReply:create: add suggested replies for a user to review
   • thread:assign and thread:unassign: for handoffs between the agent and humans
   • customer:read: look up customer context before replying

   If your agent does more, like labeling threads, marking them as done, or creating events on customers, add the matching permissions.

   Copy the API key once it’s created. You won’t be able to see it again.

3. Use the API key

   The API key goes in the Authorization header of every GraphQL request:

   Authorization: Bearer plainApiKey_xxx
   

   With the GraphQL SDK:

   import { PlainClient } from "@team-plain/graphql";
   
   const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });
   

Why use a machine user

Machine users give you three things:

• A clear author for every message. Customers and users can tell at a glance which messages came from the agent.
• Independent permissions. You can scope the agent’s API key narrowly without touching what your team can do.
• Rotation without downtime. You can issue and revoke API keys for the machine user without disrupting access as machine users can have more than one API key.
• Per-agent assignment. Threads can be assigned to a machine user directly. See routing.

Finding your machine user’s ID

You need your machine user’s ID in code, for example to check whether a thread is assigned to your agent before acting on it (see routing).

The ID is on the machine user’s page under Settings → Machine Users. Copy it and set it as an environment variable.

Multiple agents

You can create as many machine users as you want, one per agent. Smaller agents that do narrow tasks are less work to build and manage.