iblai-api-agent-support

Mirrored from iblai/vibe · 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.

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:

  {
    "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:

  {
    "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:

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):

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