All chat endpoints use authenticated host identity. Example headers: Authorization: Bearer <user-token>, Accept: application/json, Content-Type: application/json. Tokens belong to the signed-in individual. All responses wrap results in data; errors use Laravel JSON message and validation errors when applicable.
For the split production topology, prefix paths with https://api.alzafchat.com; the Sites frontend at https://alzafchat.com uses cross-origin bearer requests. SDK base URL is https://api.alzafchat.com/api/chat; private-channel auth is https://api.alzafchat.com/api/broadcasting/auth. Login/logout and account endpoints remain on the API host as well. Configure exact backend CORS origins and send no cross-site cookies; see security. API contracts do not change when frontend and backend use separate hosts.
Request snippets show the HTTP method, path and shared headers. Add the documented query or body fields; replace path placeholders before sending from your application.
GET/api/chat/me
Input
none
Result and permission
Verified identity {id,name,role,service_id,provider_id}
GET /api/chat/me HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>GET/api/chat/providers
Input
none
Result and permission
Service provider directory [{id,name,logo_url:string|null}]
GET /api/chat/providers HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>GET/api/chat/conversations
Input
optional limit 1–100; default50
Result and permission
Scoped inbox ordered by latest message ID descending; conversations without messages follow, newest conversation ID first. Serialized in page query + 5 preload queries (including last-message attachments) regardless of page size. List pagination beyond limit is deferred.
GET /api/chat/conversations HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>GET/api/chat/conversations/{id}
Input
none
Result and permission
Single scoped conversation DTO (same shape as list rows); 404 when out of scope
GET /api/chat/conversations/{id} HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>POST/api/chat/conversations
Input
provider_id string, subject 1–200 chars, optional context JSON object
Result and permission
Customer-only; returns the customer's existing conversation for that provider, otherwise creates one
POST /api/chat/conversations HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>GET/api/chat/conversations/{id}/messages
Input
limit1–100 default50; optional after_id≥0, before_id≥1
Result and permission
Ascending messages; meta:{has_more,first_id,last_id}
GET /api/chat/conversations/{id}/messages HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>POST/api/chat/conversations/{id}/messages
Input
body nonblank (UIs cap at 500 chars; server allows up to 5000) unless a card or attachment is present, client_message_id UUID, optional card object, optional attachment_ids int array (≤max_per_message)
Result and permission
Durable message; admin must join. New message blocked while resolved.
POST /api/chat/conversations/{id}/messages HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>POST/api/chat/conversations/{id}/attachments
Input
multipart file (image/jpeg, image/png, image/webp, application/pdf; ≤max_kilobytes)
Result and permission
Stages one attachment owned by the uploader, unclaimed until a send; returns the attachment DTO. Rejects outside the allowlist or over the size/staged cap.
POST /api/chat/conversations/{id}/attachments HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>POST/api/chat/conversations/{id}/attachments/presign
Input
name string≤200, mime allowlisted, size bytes≤limit
Result and permission
Upload negotiation. Answers {mode:"proxy"} (post the file to the attachment endpoint) or {mode:"presigned",upload_url,headers,expires_at,ticket}. Declares the mime/size before any bytes move.
POST /api/chat/conversations/{id}/attachments/presign HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>POST/api/chat/conversations/{id}/attachments/confirm
Input
ticket string from a presigned negotiation
Result and permission
Verifies the stored object (exists, size, sniffed type) then records it; idempotent for a retried confirm. 409 when the object never landed or belongs to another uploader, 410 when the ticket expired, 422 for a forged ticket or a size/type mismatch (the object is deleted).
POST /api/chat/conversations/{id}/attachments/confirm HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>POST/api/chat/conversations/{id}/join
Input
none
Result and permission
Service admin joins as own identity; repeat is harmless
POST /api/chat/conversations/{id}/join HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>POST/api/chat/conversations/{id}/read
Input
message_id existing in this conversation
Result and permission
Advance own read cursor; earlier reads do not regress; admin must join
POST /api/chat/conversations/{id}/read HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>PATCH/api/chat/conversations/{id}
Input
status: open/pending/resolved
Result and permission
Provider/admin only; audit entry
PATCH /api/chat/conversations/{id} HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>POST/api/broadcasting/auth
Input
Pusher socket_id, channel_name
Result and permission
Example host private-channel signature
POST /api/broadcasting/auth HTTP/1.1
Accept: application/json
Authorization: Bearer <user-token>Successful mutations return HTTP200. Conversation: {id:number,subject:string,status:string,provider_id:string,provider_name:string|null,provider_avatar_url:string|null,has_joined:boolean,context:object|null,participants:[{id,name:string|null,role:"customer"|"seller"|"admin"|"provider",avatar_url:string|null,is_primary:boolean}],unread_count:number,last_message:Message|null}. participants omits the authenticated viewer. Its one is_primary:true record is the list title: provider/store for a customer and customer for a seller or service admin. Customer responses always include a virtual provider participant so the store is available before any seller replies. Use avatar_url for the participant image with an initials fallback. provider_id, provider_name and provider_avatar_url identify, label and image the conversation's provider/store; provider_avatar_url is the registry logo_url normalized to avatar_url semantics. A service admin's selected thread header shows provider_name with the provider_avatar_url image (initials fallback) and lists the remaining participants in the description. has_joined is the server's admin join/send gate: true when the authenticated viewer already has a participant row. A missing has_joined means "not confirmed joined" (an admin must join before sending). service_id and the raw provider_logo_url key are intentionally not returned in conversation responses; use the verified identity from /me for service scope and provider_avatar_url for the image. Message: {id:number,conversation_id:number,body:string,sender:{id:string,name:string,role:string},card:{type,version,title,description?,image_url?,action?,data?,ref?}|null,attachments:[{id,kind,name,mime,size,url}]|null,created_at:UTC-ISO8601,client_message_id:UUID}. Bodies are plain text; consumers must not render as raw HTML. card is a display-only sidecar: body always carries the plaintext summary and is what every consumer renders when it cannot or will not render the card. See attachments for upload modes, signed URLs and limits.
With no cursor, history returns the latest limit messages ascending. With before_id, it returns the preceding page. With after_id, it returns the next ascending page; continue until has_more=false. Both bounds can be supplied to constrain a range. IDs are global and may have gaps. IDs—not timestamps—are pagination keys.
Attachments#
If multipart storage returns a failed/empty path, the endpoint responds with JSON HTTP500: The attachment could not be stored. Try uploading it again. No staged attachment row is created for that failed write. Diagnose the disk before retrying; no automatic message resend is introduced.
Unclaimed staged rows count toward the uploader/conversation staging cap. Removing a composer chip, navigating/reloading, sending unrelated text or waiting does not free that server capacity. There is currently no cancellation endpoint or expiry cleanup job. Operators need a reviewed retention/cleanup policy; do not bypass the cap or delete rows blindly to make a UI retry succeed.
A message may carry attachments: an array (or null) of {id:number,kind:"image"|"file",name:string,mime:string,size:number,url:string}. name and mime are display strings; render them as text. url is a time-limited URL (60 minutes by default) that needs no bearer token, so <img> and downloads work. Re-fetching history mints fresh URLs and is the supported way to recover an expired one; URLs are not stable identifiers.
Uploads are stage-then-send. POST /conversations/{id}/attachments stores the file and returns the DTO with the row still unclaimed. The next send claims it by id through attachment_ids; until then the uploader may remove it from the composer. An attachment can be claimed only by its uploader, only in its own conversation, and only while unclaimed, otherwise the send is 422. body may be blank when attachment_ids is non-empty or a card is present, so attachment-only messages are valid. Idempotent retries compare body, card and the claimed attachment id set; a different set under the same UUID is 409.
Hosts choose how bytes travel (service-chat.attachments.upload_mode):
auto(default) presigns a single-keyPUTwhen the disk is remote (S3) and proxies through the package when it is local.proxyalways posts the file to the attachment endpoint, which sniffs the real content type before storing.presignedrequires presign support and returns500when the disk lacks it.
Call POST /conversations/{id}/attachments/presign first when you manage uploads yourself; the response tells you which path to take. In presigned mode, PUT the bytes to upload_url with exactly the returned headers (the SDK drops runtime-owned headers such as host/content-length), then call POST .../attachments/confirm with ticket. The presigned URL is itself the authorization: never send the API bearer token to storage. Content-Type and Content-Length are signed into the URL, so a swapped type or a different length is rejected by the store. The server re-checks both on confirm, deletes an object that fails verification, and binds the ticket to one conversation, uploader, path and expiry, so a ticket cannot be replayed elsewhere or pointed at another user's object.
Presigned uploads need bucket CORS for PUT from every frontend origin. If that PUT fails (missing CORS, expired URL, network loss), the SDK retries through the proxy path, which re-validates the bytes server-side. A file genuinely rejected by policy fails again with the same reason. The bucket must be private and lifecycle rules should expire abandoned objects under the chat prefix; the backend does not ship a purge job.
download_mode controls url: auto returns the disk's own short-lived URL for remote disks (presigned S3 GET, with non-image kinds forced to download) and keeps local-server disks on the package's signed route; route always uses the package route; disk always prefers the storage URL. The package route sets Content-Type, X-Content-Type-Options: nosniff, a sandboxed Content-Security-Policy and forces non-image kinds to download. A disk whose visibility is public is refused with 500, because conversation files must not be fetchable by URL alone.
Message retries must reuse the UUID and identical body. Same conversation/sender/UUID returns the original message without another broadcast. A changed body returns409. Deduplication is permanent while the row exists. Conversation creation is idempotent by {service_id,customer_id,provider_id}: later requests return the original conversation without changing its subject, context, status or timestamps. Exact retry of a previously accepted message still succeeds after resolution.
Message cards#
POST /conversations/{id}/messages accepts an optional card object: {type:string≤64, version:1–100, title:string≤200, description?:string≤500, image_url?:https-URL≤2048, action?:{label:string≤120, url:https-URL≤2048}, data?:object≤20 keys, ref?:string≤128}. Unknown keys are stripped; the stored envelope may not exceed 4096 bytes. type is open vocabulary — hosts invent kinds (product, order, …) without a package change. The built-in renderer is generic (image, title, description, one action) and covers any well-formed kind; a host may override a specific type with its own renderer, and unusable payloads (missing type/title) fall back to the plaintext body. ref is an opaque host-set identity (e.g. product:42) for client-side dedupe of restaged suggestions. The card rides every message DTO (history, show, broadcasts); idempotent retries compare it alongside the body, so a changed card under a reused UUID returns409. All card strings render as plain text; image/action URLs must be HTTPS. A sent card is a point-in-time snapshot, not a live view — link out for live data.
401 unauthenticated;403 forbidden role or missing admin join;404 inaccessible/nonexistent conversation;409 closed conversation or UUID/body conflict;422 invalid payload, foreign read ID, invalid provider or oversized context;429 throttled. Example chat/auth middleware permits120 requests/minute/IP; demo login permits10/minute/IP. Retry-After is exposed through CORS so cross-origin clients can show the throttle delay. Hosts own their abuse limits.
Own account login, logout, platform service scope and management endpoints are documented in auth/management reference. Chat API identity comes from the central application's authenticated account; embedded hosts retain their own adapter contracts.
Local/testing demo login only: POST /api/demo/login {email,password} returns {data:{token,expires_at,user}} with the same account metadata shape as own login; token expires in8 hours and is stored hashed. Known demo accounts/password are in quickstart. Production denies demo login and demo-marked accounts. External server-to-server identity exchange is deferred.
Standalone service operations#
The central example additionally exposes the console API, manual billing API, write entitlement policy and server identity exchange. These are not new package routes for embedded hosts. Central chat writes can now return HTTP402 with billing_inactive or monthly_message_limit; persisted exact retries keep their original result. SDK callers receive the safe server error message.