Download the PHP package uchara/uchara-php without Composer

Uchara PHP SDK

Official PHP SDK for the Uchara Chat Platform. It provides:

• ServerSDK — server-to-server integration with the authenticated /v1/* REST API (members/agents, invites, channels, bots, conversations, messages, contacts, canned responses, API keys).
• AgentSDK — authenticate human workspace agents with email/password JWTs and send messages attributed to the logged-in agent.
• VisitorSDK — embed the chat widget in customer applications via the public /v1/widget/* endpoints.
• Laravel integration — a service provider, manager, facade and config file with auto-discovery for Laravel 10/11. The native SDK itself has no Laravel dependency.

Requirements

• PHP 8.1 or higher
• Composer
• ext-json

Installation

For Laravel 10/11 the service provider and facade are registered automatically via package auto-discovery. Publish the config file with:

Quick Start — Server SDK

Members (a.k.a. agents)

Workspace members are the human users of a workspace. Because many users refer to them as "agents", ergonomic Agent aliases are provided alongside the canonical Member methods.

Invites

Channels, Bots & Messages

Quick Start — Agent SDK

Use AgentSDK when messages must appear as a specific human agent. The API derives sender_type=agent and sender_id from the access token, so do not provide those fields yourself.

The access and refresh tokens are stored in the SDK instance. Refresh the session when needed:

Multi-agent collaboration and approval flow

Conversations support multiple collaborating agents. There is no separate "approval" endpoint: an authorized assignee/admin invites an existing same-workspace member, and that member accepts by joining. Identity and authorization are always derived from the authenticated member's JWT — the SDK never sends an inviter field.

takeoverConversation() is a separate bot-to-agent takeover — it transitions a bot conversation to open and assigns it to the calling agent. It is not a collaborator approval step and does not replace the invite → join flow above.

Secure backend-to-browser agent session (legacy agent-token flow)

Prefer the one-time dashboard SSO flow described under the Server SDK section below for seamless dashboard handoff. This agent-token flow remains supported for existing integrations.

For a custom browser dashboard, do not expose the Server API key. Create the short-lived agent session on your backend and return only the token pair to the browser:

Then initialize the browser Agent SDK with the returned session:

The agent-token endpoint verifies that the email belongs to an active member in the API key's workspace. Access tokens are short-lived; keep and rotate the refresh token according to your frontend session policy.

One-time dashboard SSO

For a seamless handoff from your own authenticated backend to the Uchara dashboard, issue a one-time SSO ticket with the Server SDK and return the resulting redirect_url to the browser. The API key stays on your backend; the browser only ever sees an opaque, short-lived ticket in the URL fragment.

There is no dedicated SDK helper for this — use the underlying HTTP client via ServerSDK::http()->post(...):

Security guidance:

• Keep the API key backend-only — never expose it in browser code.
• Do not log, store, or reuse redirect_url values.
• The ticket is short-lived (60 seconds), one-time, and consumed atomically on exchange; only its hash is stored server-side.
• No JWT, API key, or refresh token ever appears in the URL.

Quick Start — Visitor SDK

Read receipts & delivery status

Every message carries a delivery_status field (plus delivery_status_at and, on failure, delivery_error). The lifecycle is monotonic and idempotent:

with failed (and recovered for messages that later succeed). The possible values are exposed as constants on Uchara\SDK\DeliveryStatus:

Mark a conversation as read so the other side sees a read receipt on their own sent messages:

Factory

The Uchara factory builds SDK instances from a config array or directly:

Laravel

Set the environment variables and use the facade:

Error Handling

UcharaException exposes the HTTP status via getStatus() (alias of getCode()), the parsed error payload via getDetails(), and the full structured response via getResponse().

Advanced HTTP access

The simple helpers (get/post/patch/put/delete) return the unwrapped data payload. When you need the status code, pagination meta or response headers, use request():

Development

Documentation

Full documentation: https://www.uchara.com/docs/sdk/php

License

MIT