These endpoints belong to examples/laravel-api, not to the reusable Composer package or browser SDK. Routes in routes/admin-console.php are included inside the existing authenticated, throttled API group. Send the standalone account's bearer token using Authorization: Bearer …; do not put credentials in URLs. Existing authentication contracts and chat permissions still apply.
Access and scope#
| Account role | Console overview, conversation list/inspection and audit | Operations |
|---|---|---|
| Platform administrator | All services, or an optional service_id filter | Allowed |
| Service administrator | Their stored service only | Forbidden |
| Customer or seller/provider team member | Forbidden | Forbidden |
service_id is optional/nullable and at most 64 characters. For service administrators the authenticated account's stored service always wins; passing another service cannot grant access. A platform administrator's console does not require an active chat scope, and a selected chat scope does not restrict their global console permission. A supplied platform filter with no matching data returns an empty result. Authentication rejects inactive accounts/services using the existing middleware.
All endpoints return 401 for missing, expired or revoked authentication and 403 for unauthorized roles. Invalid filters return Laravel's 422 validation response. Inspection returns 404 for absent conversations and conversations outside the administrator's scope. Browser-supplied actor IDs or role labels never determine authorization or the audit actor.
All timestamps are ISO 8601 UTC. Conversation/message identifiers are JSON numbers; account, participant, sender and audit-target identifiers are strings. The implementation reads current tables; multi-query overview/inspection results are not a snapshot locked against concurrent chat activity.
Overview#
GET /api/admin/overview?service_id=example-service
type ConsoleOverview = {
data: {
totals: {
services: number; providers: number; accounts: number;
conversations: number; messages: number;
open: number; pending: number; resolved: number;
};
activity: Array<{ date: string; messages: number }>;
generated_at: string;
};
};Totals include active and inactive registered services/providers/accounts in the authorized scope. Global account totals include platform administrators; service totals include only accounts assigned to that service. Message counts join the corresponding conversation to enforce its service scope. Activity contains seven UTC calendar dates ending today, in ascending order, with zero counts included. It counts persisted messages created on those dates.
Conversation list#
GET /api/admin/conversations
Optional filters: service_id, status (open, pending, resolved), q (at most 120 characters), page (1–1,000,000), and per_page (1–100, default 20). The default page is 1. Search matches a literal substring of subject, provider name or customer name; %, _ and ! do not become wildcard operators. Whitespace-only searches are ignored. Results sort by updated_at descending, then conversation ID descending.
type ConsolePage = {
current_page: number; per_page: number; total: number; last_page: number;
};
type ConsoleConversation = {
id: number; service_id: string; service_name: string | null;
provider_id: string; provider_name: string | null;
subject: string; status: 'open' | 'pending' | 'resolved';
customer_id: string; customer_name: string | null;
participant_count: number; message_count: number;
last_message_at: string | null; created_at: string; updated_at: string;
};
type ConsoleConversations = { data: ConsoleConversation[]; meta: ConsolePage };Names are resolved from current service/provider/account records; customer name falls back to the conversation's participant snapshot. Missing related records produce nullable names. Message/participant counts use aggregated joins; list queries do not issue one query per returned conversation. This endpoint does not expose message bodies, commerce context, account email or credentials. Pagination is stable for equal timestamps; concurrent updates can still move a conversation between offset-based pages.
Audited inspection#
POST /api/admin/conversations/{id}/inspect
Accepts the same optional service filter. Returns:
type ConsoleInspection = {
data: {
conversation: ConsoleConversation;
participants: Array<{
id: string; name: string; role: string; last_read_message_id: number;
}>;
messages: Array<{
id: number; conversation_id: number; body: string;
sender: { id: string; name: string; role: string };
card: MessageCard | null;
attachments: Attachment[];
created_at: string; client_message_id: string;
}>;
};
meta: { has_more: boolean };
};MessageCard and Attachment match the existing chat DTOs. Inspection uses the package-internal MessagePresenter only after console authorization. It returns safe names/metadata and short-lived attachment URLs, never storage paths or disk names; inspect again when links expire. Normal chat responses use the same presenter. The presenter itself grants no access and must receive only rows the caller has authorized. Platform inspection of an inactive service remains permitted; this does not enable its chat writes or change the inspector's active service, membership or read state.
The latest 50 messages are returned in ascending message-ID order. has_more means older messages exist; inspection does not provide an older-page control. Each successful request inserts admin.inspected into sc_audit_events with the authenticated administrator's actual account ID and stored role. It records no message body, password, token or requested identity. Repeated inspections produce separate audit events. Failed authorization does not create an event.
Inspection does not add a conversation participant or change read state. Administrators must still join through the existing chat endpoint before replying or marking messages read. Inspection is an administrative read action, not impersonation or an alternate message-send API.
Combined audit history#
GET /api/admin/audit
Optional filters: service_id, kind (all, management, conversation, billing, default all), exact action (at most 100 characters), page, and per_page. Pagination bounds/defaults are the same as the conversation list. Results sort by event creation descending, source ascending, then source-local ID descending. Use both source and id as the UI key; the three source tables have independent identifier sequences.
type ConsoleAudit = {
data: Array<{
source: 'management' | 'conversation' | 'billing'; id: number; action: string;
actor: { id: string; name: string; role: string } | null;
service_id: string | null; target_type: string; target_id: string;
details: Record<string, string | boolean>; created_at: string;
}>;
meta: ConsolePage;
};Management events resolve scope from their service/provider/account target using joins. The event actor's service and browser-provided filters cannot substitute for the target's scope. Deleted/unresolvable targets and platform-admin account targets have no service; those events are visible only in the platform-global view. Conversation events join their conversation's service. This uses existing tables and adds no historical service column; deleting a target can therefore remove its management event from a service administrator's view.
Billing events come from chat_billing_audit and use that row's explicit service_id, actual actor reference and target. They are included in kind=all and can be selected with kind=billing or the console's Billing event-source filter. Plan events with a null service appear only in the platform-global view; service administrators and platform views filtered to a service cannot see them. The union is filtered, ordered and paginated as one result, so meta.total counts all included sources rather than the current page or only non-billing records.
actor uses the current account profile, including its current role, and is null for operator events or missing accounts. The inspection event's details.role preserves the role used at inspection time. Older event types may not contain a historical role. Only string/boolean values under status, role, service_id, provider_id, and is_active are returned in details; all other keys, arrays, numbers and null values are omitted. Passwords, email changes, names, message bodies, tokens and arbitrary stored details are not exposed by this endpoint. Billing payment references, submission/decision notes, request/decision UUIDs, payment identifiers and monetary fields are also excluded. Use the separately authorized billing API for invoice/payment details; the audit endpoint is not a financial record export.
BillingAuditTest covers all-source pagination and ordering, billing-only and exact-action filters, platform/global versus forced service scope, null-service plan-event isolation, missing actors, customer/seller denial and detail-field redaction. Run php vendor/bin/phpunit --filter BillingAuditTest from the API app.
Application operation checks#
GET /api/admin/operations — platform administrators only.
type ConsoleOperations = {
data: {
database: { connected: boolean; driver: string | null };
storage: { writable: boolean };
queue: { pending: number | null; failed: number | null };
cache: { available: boolean };
checked_at: string;
};
};Database runs SELECT 1; driver is reported only on success. Storage checks whether Laravel's framework, logs and private-app directories are writable by the web process. Queue counts are rows in the configured application's jobs and failed_jobs tables; pending includes delayed/reserved rows. An unavailable table/check returns null, not a fabricated zero. These counts do not indicate whether a worker is running and do not cover non-database queue backends.
Cache writes a random probe with a ten-second TTL, reads it back and attempts cleanup. Failed probes return false. Errors are suppressed rather than returning database addresses, filesystem paths, credentials or raw exception text. This is an authenticated application check; authentication itself still depends on a working database. It is not a host monitor, uptime guarantee, WebSocket/worker process check, capacity test, billing check or backup-restore verification.
Verification#
From examples/laravel-api:
php vendor/bin/pint app/Http/Controllers/ConsoleController.php routes/admin-console.php tests/Feature/ConsoleTest.php --test
php vendor/bin/phpunit --filter ConsoleTestThe focused suite verifies platform/global and service scope, customer/seller denial on every endpoint, cross-service inspection denial, provider boundaries, actual audited identity, latest-message limits, no automatic joining/read changes, pagination/search, constant list query counts, audit redaction/null actors/orphan targets and degraded operation checks. Native Windows PHP 8.3 with SQLite passed eight tests/161 assertions during implementation. Live MySQL execution and deployment smoke checks for these new endpoints have not yet been performed.