# iblai-api-agent-support

> Mirrored from [`iblai/base`](https://github.com/iblai/base) · [`skills/agents/iblai-api-agent-support/SKILL.md`](https://github.com/iblai/base/blob/main/skills/agents/iblai-api-agent-support/SKILL.md). This page is generated — edit it in the repository, not here.

Manage an agent's human-support tickets through the API: list and filter the
tickets users raised with an agent, read a ticket's reply thread, respond as
the support team, move tickets through their lifecycle, and close or delete
them. Use when triaging or responding to support requests escalated from
agent chats. The UI twin is
[`/iblai-vibe-agent-support`](https://raw.githubusercontent.com/iblai/base/refs/heads/main/skills/agents/iblai-vibe-agent-support/SKILL.md).

## Auth & conventions

- **Base URL:** `https://api.iblai.app`
- **Header:** `Authorization: Api-Token $IBLAI_API_KEY` on every request.
- **Path vars:** `{org}` = `$IBLAI_ORG`, `{username}` = `$IBLAI_USERNAME`,
  `{mentor}` = the agent's unique id (e.g. `d17dc729-60fd-4363-81a0-f67d9318b03e`).
- **Prefix:** every route below hangs off
  `https://api.iblai.app/dm/api/ai-mentor/orgs/{org}/users/{username}` (written `{u}`
  below). The path token is named `user_id` on the wire but takes the **username**.
- Not connected yet? Run **`/iblai-api-login`** first to populate `IBLAI_ORG`,
  `IBLAI_USERNAME`, and `IBLAI_API_KEY`.
- DELETE calls are destructive — confirm with the user first.

## Concepts

- **Tickets are opened by the agent, not by this API.** When a user asks an agent
  for human help mid-chat, the agent's human-support tool files a
  `HumanSupportTicket` — there is **no POST create endpoint** here. The requester
  fields (`username`, `email`, `full_name`, `user`) and the source `session` are
  resolved server-side from that chat; `subject` and `description` are authored by
  the agent (the `description` is often HTML or Markdown, not plain text).
- **Visibility:** org admins see every ticket in the org; other users see only the
  tickets they raised themselves.
- **Lifecycle:** `status` walks `open` → `in_progress` → `closed`. The dedicated
  `close/` endpoint sets `status: closed`, the same as patching `status`.
- **Conversation thread:** each ticket has `TicketMessage` replies. `sender` is the
  numeric user id of the author (always the caller who posted it) — the requester's replies carry their `user` id,
  support-team replies carry the responder's id, and `null` marks a
  system-generated message.
- **Prerequisite:** the agent only offers escalation while its human-support tool
  is enabled — toggle it with **`/iblai-api-agent-tool`** (pull the exact slug
  from that skill's `available-tools/` read).

## Reads

### Tickets

- **GET** `{u}/support-tickets/?mentor_id={mentor}&status={open|in_progress|closed}&username={requester}&session={session}&page={n}&page_size={n}` — paged ticket list. Filters stack: `mentor_id` scopes to one agent, `username` to one requester, `session` to the chat session that raised the ticket.
- **GET** `{u}/support-tickets/{id}/` — one ticket.

### Messages

- **GET** `{u}/support-ticket-messages/?ticket={ticketId}&sender={senderUsername}&page={n}&page_size={n}` — paged message list; pass `ticket` to load one ticket's conversation thread. The `sender` filter matches the sender's **username**, not the numeric id the message carries (`?sender=42` matches nothing).
- **GET** `{u}/support-ticket-messages/{id}/` — one message.

## Writes

### Tickets

- **PUT** `{u}/support-tickets/{id}/` — replace a ticket's editable fields:
  ```json
  {
    "subject": "string (required, ≤255 chars)",
    "description": "string (required)",
    "status": "open | in_progress | closed"
  }
  ```
- **PATCH** `{u}/support-tickets/{id}/` — edit a subset (e.g. `{ "status": "in_progress" }`).
- **POST** `{u}/support-tickets/{id}/close/` — close a ticket (no body): sets `status: closed` and returns the ticket. Admins and the requester can call it.
- **DELETE** `{u}/support-tickets/{id}/` — delete a ticket (no body). Destructive — confirm with the user first.

### Messages

- **POST** `{u}/support-ticket-messages/` — reply on a ticket:
  ```json
  {
    "ticket": "integer (required, ticket id)",
    "message": "string (required)"
  }
  ```
  The server always saves the caller as `sender`; a `sender` in the body is ignored.
- **PUT** `{u}/support-ticket-messages/{id}/` — replace a message (same fields as create).
- **PATCH** `{u}/support-ticket-messages/{id}/` — edit a subset (e.g. `{ "message": "string" }`).
- **DELETE** `{u}/support-ticket-messages/{id}/` — delete a message (no body). Destructive — confirm with the user first.
- PUT, PATCH and DELETE reach only the caller's own messages.

## Example

List one agent's open tickets, newest page first, then reply on ticket 42:

```bash
curl -s \
  "https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/support-tickets/?mentor_id=$MENTOR&status=open&page=1&page_size=10" \
  -H "Authorization: Api-Token $IBLAI_API_KEY"

curl -X POST \
  "https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/support-ticket-messages/" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket": 42, "message": "We are looking into this now."}'
```

## Notes

- List reads return a DRF page envelope — `{ "count": n, "next": url|null,
  "previous": url|null, "results": [...] }`; iterate `results`. DELETEs return `204`.
- There is no ticket-create endpoint — tickets only come from agent chats (see
  Concepts). To test the flow end-to-end, enable the human-support tool and ask
  the agent to escalate.
- `mentor_id` filters by the **agent's unique id**, not its name; `username`
  filters by the **requester**, independent of the `{username}` path token
  (the caller).
- `description` is agent-authored and frequently arrives as a full HTML document
  or Markdown — don't assume plain text when displaying or diffing it.
- `resolved_at` is never set by the API (it stays `null`, even after
  `close/`); use `updated_at` on a closed ticket if you need a close time.
- To load a conversation thread, filter messages by `ticket` and sort by
  `timestamp` ascending; match `sender` against the ticket's `user` to tell
  requester replies from support replies.

## Schema

**Ticket object** (`HumanSupportTicket`):

| field | mode | notes |
| --- | --- | --- |
| `id` | ro | integer |
| `username`, `email`, `full_name`, `user` | ro | requester identity; `user` is the numeric user id |
| `session` | ro | chat session the ticket was raised from |
| `subject` | rw | ≤255 chars |
| `description` | rw | agent-authored body; often HTML/Markdown |
| `status` | rw | `open` \| `in_progress` \| `closed` |
| `mentor_id` | ro | unique id of the agent the ticket belongs to |
| `created_at`, `updated_at` | ro | ISO 8601 |
| `resolved_at` | ro | always `null`; nothing in the API sets it |

**Message object** (`TicketMessage`): `id` (ro), `ticket` (ticket id), `sender`
(numeric user id or null for system messages), `message`, `timestamp` (ro, ISO 8601).
