Everything your team does with tickets, an AI agent or a script can do through the API: list the tickets waiting, read one, reply or write a note, set its status. A reply sent this way is emailed to the customer like any other, and a person can read and correct it on the ticket's page.
Make a key
-
Open Integrations, then API keys, and choose New API key.
-
Give it a Name, like "Support agent".
-
Under Scopes, tick only what the agent needs. To answer tickets:
- Read tickets and their conversations (
tickets:read) - Open tickets, reply, write notes and change tickets (
tickets:write) - Read saved replies (
saved_replies:read), to reuse your team's answers.
An agent that only drafts notes for your team still needs
tickets:write; it simply never sends"kind": "reply". - Read tickets and their conversations (
-
Choose Create API key and copy the key. It is shown once.
A key acts as the member who made it: its replies carry that member's name, and it can do only what that member may do. A key made by a member of the Agent group can reply and change tickets, never delete one.
Show the agent the API
Your site describes its whole API for an AI at /llms.txt
(for a site at acme.simplest1.com, https://acme.simplest1.com/llms.txt), and for people at /api/docs.
Give the agent that address and the key. The key goes in each request:
Authorization: Bearer sk_live_...
The calls an agent uses
List the open tickets, the one waiting longest first:
GET /api/v1/tickets?status=open
Read one, with its whole conversation and your team's notes:
GET /api/v1/tickets/{id}
Reply, and set the ticket to wait on the customer:
POST /api/v1/tickets/{id}/messages
{"kind": "reply", "body": "Hi Ana, ...", "status": "pending"}
Or leave a note for your team instead, never emailed:
POST /api/v1/tickets/{id}/messages
{"kind": "note", "body": "Looks like the March invoice bug; suggest a refund."}
Change its priority, category, assignee or status:
PUT /api/v1/tickets/{id}
{"priority": "high"}
Statuses, priorities and kinds are ids, like open or urgent, never
words in a language.
The same rules as a member
- Nobody overwrites anybody. Send the id of the last message the agent
read as
seen_id. If someone wrote since, the reply is refused with409 collisionand nothing is sent: read the ticket again. - Your plan's emails count. Each reply and each copy counts against the
site's emails for the day; past them a reply is refused with
429. - Ratings are the customer's. No key can set one.
- Writing first to a new address (
POST /api/v1/tickets) is on paid plans, as in the admin.
Let the agent hear about new tickets
Instead of asking every few minutes, add a webhook under Integrations,
Webhooks with A ticket is opened (ticket.created) and A message
is written on a ticket (ticket.message). Your site calls the agent's
address each time, and the agent reads the ticket and answers.
Start with notes: have the agent draft its answers as notes for a few days, read them, and let it reply once its answers are ones you would send.