Download the PHP package sashalenz/chatwoot-api without Composer

Chatwoot API for Laravel

A thin, fluent Laravel SDK for the Chatwoot Application API. It wraps contacts, conversations and messages behind a small, expressive API so you can integrate Chatwoot into any Laravel application without hand-rolling HTTP calls.

Authentication. Chatwoot's Application API authenticates with the api_access_token header — a user/agent token or an agent-bot token — not Authorization: Bearer. This package handles that for you.

Requirements

• PHP ^8.2
• Laravel 11.x, 12.x or 13.x
• A Chatwoot installation (cloud or self-hosted) and an Application API access token

Installation

Install the package via Composer:

Optionally publish the config file:

Configuration

Set the following variables in your .env:

Three API families

• Application API (contacts(), conversations(), messages(), …) — the agent/system side. Authenticates with an agent/user access token and acts within an account.
• Client API (client()) — the public API-channel surface. Authenticates with the inbox identifier (no agent token) and is the canonical path for an integration that pushes a customer's messages into Chatwoot as incoming.
• Platform API (platformAccounts(), platformAgentBots(), platformUsers()) — installation-level provisioning of accounts, users and bots. Authenticates with the platform app token and is not account-scoped.

Usage

The package exposes a static entrypoint, ChatwootApi, with one method per resource. Entity methods return typed spatie/laravel-data DTOs (see Typed responses below).

Typed responses

Entity methods return DTOs under Sashalenz\ChatwootApi\Data\* (e.g. ContactData, ConversationData, MessageData, InboxData, …) with idiomatic camelCase properties mapped from Chatwoot's snake_case payloads. Unknown fields are ignored, so the DTOs tolerate Chatwoot adding keys.

• Single-entity methods (create, get/show, update) return the entity DTO.
• List methods return Paginated<…> — a payload array of DTOs plus the raw meta, with count(), currentPage() and totalCount() helpers.
• delete() (and removeMembers) return bool.
• A few ad-hoc action endpoints (toggleStatus, assign, setCustomAttributes, meta, all of reports(), platformUsers()->login()) return an Illuminate\Support\Collection of the raw response.

Client API (API-channel inbound bridge)

Push a customer's messages into an API-channel inbox using only the inbox identifier — no agent token. Messages are created as incoming.

Agent replies flow back to you via the inbox Webhook URL (a message_created event with message_type: outgoing) — handle that in your app and deliver to the transport (see Handling webhooks).

Handling webhooks

Chatwoot POSTs events to your configured Webhook URL. WebhookEvent parses the body and exposes the event plus typed accessors for the subject entity:

message(), conversation() and contact() return the relevant DTO (or null) regardless of which event family arrived; raw() exposes the full payload for anything not modelled. isIncoming()/isOutgoing() normalise the message type across the webhook (string) and REST (integer) forms.

Per-call account & token overrides

Useful for multi-account or multi-token setups. Any override wins over the config value:

API surface

See the Chatwoot Application API reference for the full set of accepted attributes.

Error handling

Non-2xx responses and transport failures are wrapped in Sashalenz\ChatwootApi\Exceptions\ChatwootApiException. Requests automatically retry transient failures (2 retries, 200 ms apart) with a 15 s timeout.

Testing

Changelog

Please see the commit history for changes.

Contributing

Pull requests are welcome. Please make sure composer test, composer analyse and composer format-test pass before submitting.

Security

If you discover a security issue, please email [email protected] instead of using the issue tracker.

Credits

• Oleksandr Petrovskyi

License

The MIT License (MIT). Please see the License File for more information.