Skip to main content
An agent in Plain is a machine user: the same identity used for any API integration. It can be assigned threads, reply to customers, be @-mentioned, and appear on the timeline. Customers see its public name and avatar.

​
Create a machine user

1

Add the machine user

Go to Settings → Machine users & API Keys and click Add machine user.
  • Name: visible only to your team. Describe the agent, for example Support Agent.
  • Public name: what customers see, for example Acme Support.
  • Avatar: optional, shown next to messages.
For an internal agent, set Type to Custom agent so it appears in Ask Sidekick. A support agent does not need that; assignment and thread APIs work for any machine user. On an existing machine user, click Change type.
2

Create an API key

Click Add API key and grant the permissions this agent needs. For a support agent that reads and replies:
  • thread:read
  • thread:reply
  • generatedReply:create for suggested replies
  • thread:assign and thread:unassign for handoffs
  • customer:read
Add more if the agent labels threads, marks them done, or creates customer events. A mutation without the right permission returns an error that names it.Copy the API key when it is created. Plain shows it once.
3

Use the API key

Send it as Authorization: Bearer plainApiKey_your_api_key_here.
A machine user can hold more than one API key, so you can rotate without downtime. Create one machine user per agent.

​
Machine user ID

You need the ID in code, for example to check assignment. See routing. It is the last segment of the URL: Settings → Machine users & API Keys → /settings/machine-users/mu_…. Or load the machine user that owns the key with myMachineUser.

​
Reply as a team member

By default a reply from your agent shows the machine user’s public name. To have the agent reply as a specific team member instead, add them to the API key’s impersonation allow list, then pass impersonation.asUser to replyToThread. The allow list belongs to the API key, not the machine user, and a key with an empty list can’t reply as anyone. Open the API key from the machine user’s page and, under Impersonation, add who it may reply as:
  • individual team members
  • everyone holding a built-in role: Owner, Admin or Support
  • everyone holding a custom role
Only a team member can set the list, and only for people and roles whose permissions they hold themselves. An admin can add other admins and support users, but not the owner. You can also set it with impersonationAllowList on createApiKey or updateApiKey, as userIds, roleIds (role_owner, role_admin or role_support) and customRoleIds. Setting it replaces the whole list, and updateApiKey also replaces permissions, so send the key’s full permission list alongside it.