Use the API with an AI agent

Updated · 3 min read

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

  1. Open Integrations, then API keys, and choose New API key.

  2. Give it a Name, like "Support agent".

  3. 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".

  4. 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 with 409 collision and 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.

Made with Simplest1