Agent API for mobile & desktop apps

The Agent API powers MagizAI's own mobile and desktop agent apps — and you can build on it. Agents sign in, see the inbox, and answer conversations. Every action runs the exact same logic as the web inbox, so behavior is identical.

Sign in

Exchange an agent's email and password for a Bearer token. Only owners, admins and agents can sign in; viewers are read-only.

POST /api/agent/login

{ "email": "[email protected]", "password": "…", "device_name": "iPhone 15" }

Response:

{
  "token": "…",
  "user": { "id": 5, "name": "Sam", "email": "…", "role": "agent" },
  "company": { "id": 1, "name": "Acme", "plan": "pro" }
}

Send the token on every other call: Authorization: Bearer …. Sign out with POST /api/agent/logout.

The inbox

• GET /api/agent/me — the signed-in agent and company.
• GET /api/agent/inbox — the conversation list and unread counts. Filter with ?filter=all|ai|human|resolved.
• GET /api/agent/conversations/{id} — one conversation with its full message history (also marks it read). {id} is the conversation's public id.

Handling a conversation

• POST /api/agent/conversations/{id}/reply — { "body": "…" }. Sends an agent message (auto-takes over) and delivers it to the visitor's widget, WhatsApp or email automatically.
• POST …/takeover — take the chat from the AI.
• POST …/release — hand it back to the AI.
• POST …/resolve — close it as resolved.
• POST …/reopen — reopen a closed chat.
• GET /api/agent/tags, POST …/tags ({ tag_id }), DELETE …/tags/{tag} — manage tags.
• GET /api/agent/canned — canned responses for the composer.

AI assist while replying

• POST …/suggest — an AI-drafted reply grounded in the bot's knowledge.
• POST …/enhance — polish the agent's own draft ({ body, mode: fix|professional|friendly|concise|expand }).
• POST …/summary — a short summary of the conversation.

Getting live updates

Today the apps stay current by polling GET /api/agent/inbox every few seconds (and re-fetching an open conversation), exactly like the web inbox. A push channel (WebSocket) for instant new-message notifications is on the roadmap.

A typical flow

• Log in and store the token.
• Poll the inbox for new or updated chats.
• Open a conversation to read its messages.
• Take over and reply, or resolve it when done.