Skip to main content
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 teammate. 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 teammate 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 labelling 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 a number of benefits:
  • A clear author for every message. Customers and teammates 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.
  • Easy rotation. 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’ll often want 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 visible in the Plain UI on your machine user’s page under Settings → Machine Users. The easiest approach is to 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 individual agents that do narrow tasks can often be easier to build and manage.