Skip to content
alzafchat / Developers

Documentation / Reference

Configuration

Client and server options, required values and secrets.

API & technical reference
On this pageLaravel packageExample API / Reverb environmentShared JavaScript SDKNext website review build

These settings describe implemented configuration sources. Example defaults are local-development defaults. Their presence is not production-readiness evidence. Standard Laravel database/runtime options follow Laravel's own configuration; chat-specific options are listed below.

Laravel package#

Standalone native operators can configure an existing private MySQL host using the external database procedure. Its private approval file belongs only on the server; it is not an SDK/widget option. Host Composer integrations continue to use their own Laravel database and identity configuration; no additional host login system is required by these helpers.

Publish service-chat-config to override config/service-chat.php.

KeyType / defaultRequiredSecret / locationBehavior
service-chat.route_prefixstring, api/chatYesNo, serverREST path prefix
service-chat.middlewarestring array, ['api','auth']YesNo, serverHost authentication and API protection
service-chat.adapterclass string, nullYesNo, serverMust implement HostAdapter; missing adapter throws a configuration error
service-chat.attachments.diskstring disk name, FILESYSTEM_DISK env (fallback local)NoNo, serverStorage disk for attachment bytes. Must be private; a disk with visibility => public is refused with 500.
service-chat.attachments.max_kilobytesinteger, 8192NoNo, serverPer-file ceiling; enforced by validation and re-checked on confirm
service-chat.attachments.max_per_messageinteger, 5NoNo, serverAttachments per message and per staged composer set
service-chat.attachments.mimetypesstring list, jpeg/png/webp/pdfNoNo, serverAuthoritative content allowlist; images render inline, other kinds download
service-chat.attachments.url_ttl_minutesinteger, 60NoNo, serverLifetime of the signed download URL
service-chat.attachments.upload_modeauto, proxy or presigned; default autoNoNo, serverauto presigns direct-to-storage on remote disks and proxies on local disks
service-chat.attachments.download_modeauto, route or disk; default autoNoNo, serverauto uses the disk's URL for remote disks and the signed route for local disks
service-chat.attachments.presign_ttl_minutesinteger, 15NoNo, serverLifetime of a presigned upload URL / confirm ticket
service-chat.attachments.middlewarestring array, ['api','signed']YesNo, serverServing route protection; keep signed, never add auth

The standalone application supplies account bearer middleware and its database identity adapter. Demo login remains local/testing only. An embedding host can replace this middleware/adapter with its own trusted identity integration. Changing the route prefix requires configuring the SDK's broadcast-auth URL.

Attachments on S3#

Attachment storage follows the host's filesystem configuration, so a host whose FILESYSTEM_DISK is already s3 needs no chat-specific storage setting. The package only talks to Laravel's Storage facade and does not require the AWS SDK; the host's s3 disk must have league/flysystem-aws-s3-v3 installed, exactly as any other Laravel S3 disk does.

To use a different disk, or to be explicit:

dotenv
SERVICE_CHAT_ATTACHMENT_DISK=s3

Checklist for direct-to-S3 uploads (upload_mode=auto on an S3 disk, or presigned):

  1. The bucket is private (no public read policy, no public ACLs).
  2. The bucket has CORS allowing PUT from each frontend origin, with the content-type header and ETag exposure as needed.
  3. A lifecycle rule expires objects under the service-chat/ prefix; the backend does not ship a purge job for staged or abandoned uploads.
  4. The IAM principal can PutObject/GetObject/HeadObject/DeleteObject only under the chat prefix.

Without the CORS rule uploads still work: the SDK falls back to posting the file through the API, which validates it server-side. Downloads use presigned GET URLs for S3, so <img>/download links keep working without bucket CORS.

download_mode=route forces every download back through the package (useful when the bucket cannot be reached by browsers directly); download_mode=disk forces the storage URL even on a local disk. Presigned GET URLs carry only ResponseContentDisposition, not the package's nosniff/CSP headers.

The corresponding environment variables (all optional, all server-side, none secret — they are storage settings, not credentials):

VariableMaps toDefault
SERVICE_CHAT_ATTACHMENT_DISKattachments.diskFILESYSTEM_DISK, else local
SERVICE_CHAT_ATTACHMENT_MAX_KBattachments.max_kilobytes8192
SERVICE_CHAT_ATTACHMENT_MAX_PER_MESSAGEattachments.max_per_message5
SERVICE_CHAT_ATTACHMENT_URL_TTLattachments.url_ttl_minutes60
SERVICE_CHAT_ATTACHMENT_UPLOAD_MODEattachments.upload_modeauto
SERVICE_CHAT_ATTACHMENT_DOWNLOAD_MODEattachments.download_modeauto
SERVICE_CHAT_ATTACHMENT_PRESIGN_TTLattachments.presign_ttl_minutes15

S3 credentials themselves are the host's normal Laravel AWS_* variables and stay server-side. Never expose them to a browser; browsers receive only per-file presigned URLs.

Example API / Reverb environment#

VariableType / fallbackRequiredSecretLocation / responsibility
APP_ENVstringYesNoServer; demo authentication only in local/testing
APP_KEYLaravel app keyYesYesServer only; generate locally
CHAT_AUTH_TOKEN_LIFETIME_MINUTESinteger, 480NoNoNormal account bearer-token lifetime in minutes, server only
CHAT_AUTH_REMEMBER_LIFETIME_MINUTESinteger, 43200NoNoRemembered account token lifetime in minutes, server only
CHAT_AUTH_SOCKET_PRUNE_SECONDSinteger, 5NoNoReverb access-revocation check interval, server only
BROADCAST_CONNECTIONstringYes for realtimeNoServer; must be reverb for live events
CHAT_ALLOWED_ORIGINScomma-separated full origins; localhost:3000, 127.0.0.1:3000, localhost:5173, localhost:5174 over HTTPYes for cross-originNoAPI CORS; include each actual LAN frontend origin
REVERB_SERVER_HOSTstring, 0.0.0.0NoNoReverb listening interface
REVERB_SERVER_PORTinteger, 8085NoNoReverb listening port
REVERB_APP_IDstringYesNoServer broadcasting app ID
REVERB_APP_KEYstringYesNoPublic key; same value in browser config
REVERB_APP_SECRETstringYesYesServer only; never an npm/public option
REVERB_HOSTstring, 127.0.0.1YesNoServer-to-Reverb destination
REVERB_PORTinteger, 8085NoNoServer-to-Reverb port
REVERB_SCHEMEhttp/https, httpNoNoServer-to-Reverb transport
REVERB_ALLOWED_ORIGINScomma-separated hostnames, localhost,127.0.0.1Yes for LAN/browserNoReverb browser origins; include LAN hostname/IP

Restart processes or clear/rebuild cached configuration after server changes. Listening host 0.0.0.0 is not a browser destination. Server destination 127.0.0.1 can remain valid when Reverb shares the server, while remote browsers need the reachable LAN/public hostname.

Shared JavaScript SDK#

new ChatClient(options) takes these options:

OptionTypeDefault / requiredSecret / runtime
apiBaseUrlstringRequired; full /api/chat rootNo; browser/server HTTP client
authEndpointstringOptional; derived /api/broadcasting/auth conventionNo; private-channel authorization location
tokenstring or callback returning string/PromiseRequiredSensitive user credential; memory only in demos
reverbobjectOptional; omitted means HTTP without realtimePublic connection settings
reverb.keystringRequired when Reverb configuredPublic app key
reverb.hoststringRequired when Reverb configuredReachable browser hostname
reverb.portnumberRequired when Reverb configuredBrowser port
reverb.schemehttp or httpsRequired when Reverb configuredSelects ws/wss transport
fetchfetch-compatible functionglobalThis.fetchOptional custom HTTP transport

Constructing/importing the client does not start a connection. subscribe requires a browser. Own and clean up the client using disconnect().

Next.js public environment options and defaults are documented once in the example README. Vue and widget options are documented in their Vue and HTML integration guides. Public environment changes need a rebuild in compiled applications.

CHAT_DEV_ALLOWED_ORIGINS is a server-only Next.js development option (string, empty default, not secret). It contains comma-separated hostname/IP entries without scheme or port. The example always allows 127.0.0.1; Next allows localhost. The LAN launcher supplies the selected LAN address. This is separate from API CORS and Reverb origin configuration and does not grant chat access.

Next website review build#

VariableType / defaultRequiredSecret / locationBehavior
CHAT_NEXT_PREVIEWstring, unsetNoNo; build/start process onlyExact 1 selects .next-preview; compact selects .next-compact-preview; other values use normal .next. Set identically for build and start. Not a browser SDK option.

See local preview setup. Stop the preview before replacing its own build output. Standard release and LAN startup commands retain their existing default.