Skip to content
alzafchat / Developers

Documentation / Reference

Chat API

REST endpoints, permissions, pagination and retries.

API & technical reference
On this pageAttachmentsMessage cardsStandalone service operations

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.

14 endpoints

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}

HTTP request
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}]

HTTP request
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.

HTTP request
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

HTTP request
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

HTTP request
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}

HTTP request
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.

HTTP request
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.

HTTP request
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.

HTTP request
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).

HTTP request
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

HTTP request
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

HTTP request
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

HTTP request
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

HTTP request
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-key PUT when the disk is remote (S3) and proxies through the package when it is local.
  • proxy always posts the file to the attachment endpoint, which sniffs the real content type before storing.
  • presigned requires presign support and returns 500 when 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.