Download the PHP package funnelchat/funnelchat-php without Composer

funnelchat-php

The official PHP SDK for the Funnelchat public API: contacts, conversations and messages, templates, WhatsApp forms, tags, custom fields, groups, numbers and webhooks, with the resources and their types generated from the OpenAPI spec.

• PHP 8.1 or later, PSR-4.
• Any PSR-18 HTTP client with PSR-17 factories, which the SDK finds by itself. With Guzzle (7 or 8) it also applies the timeout.
• Retries with exponential backoff, pagination with foreach (generators), typed exceptions, the X-Request-Id of every response and webhook signature verification.
• Responses are arrays (the decoded JSON) typed with PHPDoc: PHPStan understands them and PhpStorm 2025.1 or later completes their keys.

Status: v0. The public API is at v0 and may change. The full reference is on the developers portal. Some types come from the code of the API in production rather than from the published spec: they are listed in Pending of the spec.

Installation

Guzzle is not required: any PSR-18 client with PSR-17 factories works (for example symfony/http-client with nyholm/psr7). The SDK finds them with php-http/discovery; if Composer asks about its plugin, you can say no.

The package is published on Packagist.

First call

You need an API key (<id>|fc_live_...) created in the panel, in "Developers" → "Create API key", with the permissions for what you are going to use. The panel groups them by area, one box per permission. There are twelve and a key can have all of them; there is no wildcard:

This README names each one as the panel does: WhatsApp numbers → View is the View box of the WhatsApp numbers area.

Within each area, Send includes Edit and Edit includes View; Manage groups and Create, connect and delete are separate. Keep the key in an environment variable: the client reads it from FUNNELCHAT_API_KEY when you do not pass it.

Client options (named arguments):

The timeout. PSR-18 has no timeout, so the SDK can only apply one with Guzzle: the Guzzle it builds by itself gets 30 seconds, and if you pass your own, it applies the timeout you set (if you set none, your Guzzle configuration rules). With another client, configure the timeout in that client: if you pass timeout, the SDK fails right away so nobody believes there is one.

Every request sends Authorization: Bearer <key>, Accept: application/json and User-Agent: funnelchat-php/<version> php/<version>. The key never shows up in a var_dump, print_r, var_export, dd() or serialize of the client, nor in the message of an error. A connection error carries your HTTP client's exception as getPrevious(), which may include the request with its headers: do not log it whole.

In Laravel, register a single client for the whole app: see examples/laravel/app/Providers/FunnelchatServiceProvider.php.

The resources

The resources the Node SDK also has have the same methods, with the arguments in the same order: path parameters first, then the query or the body (arrays), and the call options last.

The resource classes are generated from the spec: the parameters, query, body and response of each method are typed in its PHPDoc with array shapes (array{id: int, name: string, …}). The schemas of the spec are PHPStan aliases in Funnelchat\Generated\Schemas (ContactResource, TagResource…), which you can use in your code with @phpstan-import-type ContactResource from \Funnelchat\Generated\Schemas. For any other route, see Any route.

Sending a message

Sending with an API key needs the Contacts and conversations → Send permission and follows the WhatsApp rules.

Open window: free text. With an official Meta number you can only send free text if the contact wrote to you in the last 24 hours. Check the window first:

• send returns ['message' => […]]: the registered message, with its id, status queued and your client_reference. Queued is not sent: the next statuses (sent, delivered, read or failed) arrive through the message.status_changed event, with the same id as message_id, or you read them with $funnelchat->messages->get(2001, $id).
• If the message could not be queued, it still comes back, with status failed and error.reason not_queued. When it fails, error has Meta's code and title, or a null code, a title and a Funnelchat reason (device_unavailable, insufficient_balance, window_closed, recipient_unreachable…).
• Contact cards (sendContactCard) return ['messages' => […]], one per card; a forward (forward), one item per target with status (queued or blocked), reason and its message; a template (templates->send) and a form (messages->sendForm), ['message' => […]].
• client_reference (1 to 64 visible ASCII characters, no spaces) comes back in the message, in the contact's history and in message.status_changed.
• contact_id goes in the body, but send fills it with the contact of the route when you do not pass it.
• Send the phone (or whatsapp_id) of the same contact: the API checks it, and if it does not match the contact of the route it answers 422 recipient_mismatch.
• With options, buttons or a list.

A file by URL. With file (the URL) you send an image, a video, an audio, a document or a sticker. If the URL does not show the format (a signed URL, or one without an extension), say what it is with file_type (image, video, audio, document or sticker); for such a document, also file_name with its extension:

If one is missing, the API answers 422 with the field in errors (file_type, file_name or file), or 415 (UnsupportedMediaTypeException, with supportedFileTypes) when the extension cannot be sent.

Closed window: an approved template. The route takes the number (3) and the template id (45), which comes from $funnelchat->templates->list():

A WhatsApp form. form_id is the id of the published form (family_id); the answers arrive through whatsapp_form.completed:

When a send is stopped. If a send breaks a WhatsApp rule, it does not go out: you get an exception.

$exception->isSendRuleError() tells you whether the exception is one of these rules or one of the other refusals of a send (not_sent, template_not_found, form_not_published, provider_unsupported…; the list is in Funnelchat\Exception\SendErrors::CODES). A send is never retried by itself, because a retry can deliver the same message twice. If a 429 rate_limited sent nothing and you want the SDK to retry for you, ask for it in that call (a mac_lockout_24h is never retried):

The full example is in examples/plain-php/send-message.php.

Groups

Groups are read only through the API, with Groups and campaigns → View: the account's groups, their participants, joins and leaves, the messages sent to them and their scheduled messages.

Creating and connecting numbers

The official signup by link ('type' => 'meta') is not available in production yet: it answers 503 meta_connect_disabled until Funnelchat registers its domain with Meta. QR numbers and QR links work. Try the Meta flow against the sandbox, turning it on there.

A number belongs to the account of the API key and uses the plan's quota, with the same rules as the panel. Creating, deleting, asking for the QR and creating or revoking links need WhatsApp numbers → Create, connect and delete; reading links, WhatsApp numbers → View. Tag each number with your own external_reference (your customer's id, for example): it comes back in the number, in every device.* event, and filters the list.

A QR number

• The QR lasts 5 seconds: ask for it every 5 seconds, show it at once and scan it right away. An older QR reaches WhatsApp expired and it refuses to link the phone.
• country (optional, two letters) is the country of the phone: the WhatsApp session is opened from there.
• The account has at most one QR number not connected yet: creating another answers 409 pending_number_exists with its device_id. Connect that one, or delete it, first.
• same_number_as adds QR to an official number in coexistence, without using quota.
• A QR number is not official: WhatsApp can ban it.

A connect link

A single-use page for your customer, with no Funnelchat session. The number is created when the page ends.

• 'type' => 'meta' answers 503 meta_connect_disabled in production until Funnelchat registers its domain with Meta. A qr link works: its page renews the QR every 5 seconds.
• With 'type' => 'qr', country (two letters) is the country of the phone, as in devices->create(). It does not go with device_id nor with meta (422 invalid_request), and the link returns it in lower case ('ar').
• With 'type' => 'meta', provision_us_number: true offers a US number from the pool. A pool number is always dedicated: it needs dedicated in allowed_connection_types and does not go with device_id; otherwise 422 invalid_request. Your customer pays Meta directly, with a payment method in their WhatsApp account.
• 'device_id' => 41 reconnects that number instead of creating one, without new quota. Its method must match the link's type (422 connection_type_mismatch).
• The page claims the link when your customer presses its button, not when it opens: a messenger's link preview does not use it up.
• A meta link tolerates retries: after a Facebook or Meta failure it stays pending and your customer can try again on the page; the fifth failure makes it failed (facebook_auth_failed or meta_error). quota_exceeded, trial_number_blocked and number_not_owned close it at the first attempt.
• Learn the result three ways: the device.connected event (with connect_link_id and external_reference), return_url (it gets connect_link_id, status, and device_id or error_code), or reading the link:

At most 20 links are open per account, and 10 can be created per minute.

Finding, tagging and deleting your customer's numbers

Deleting is physical and frees the quota: an official number loses the app subscription but stays registered with Meta, and a QR number's session is closed. It emits device.deleted. There is no undo.

devices->list() now takes the query first, like every other list; the call of 0.1, devices->list($options), still works.

Idempotency-Key

devices->create() and connectLinks->create() take idempotencyKey in the options (1 to 255 characters), sent as the Idempotency-Key header. For 24 hours, the same key with the same body answers the same number or link without creating another, with the header Idempotent-Replayed: true (read it in $funnelchat->lastResponse()->headers). Only successful answers are replayed: a refusal is evaluated again. With a different body, 422 idempotency_key_mismatch; while the first call runs, 409 operation_in_progress. With a key, the SDK also repeats the create after a timeout or a 5xx (see Retries).

The events of a number

device is id, name, number, connection (qr, coexistence, dedicated or null) and external_reference. connect_link_id is, in device.connected, the link of that connection; in the other three, the last link that connected the number; null when no link did. The fields that production does not send yet (device.connection, device.external_reference, connect_link_id and reason) are optional in the types: read them with ?? null. The types are DeviceConnectedEvent, DeviceDisconnectedEvent, DeviceDeletedEvent and DeviceHealthChangedEvent in Funnelchat\Generated\WebhookEvents.

Receiving webhooks with Laravel

Verify the signature over the raw body, exactly as it arrived: $request->getContent(), not $request->all() or $request->json(). If you decode it and encode it again, the signature changes.

examples/laravel has it put together with a controller, a job that deduplicates by id and dispatches by type, the client's provider, the route and the configuration. We tested it copied as is into a Laravel 13 app (with PHPStan at the max level, through Larastan).

With plain PHP

The full example is in examples/plain-php/webhook.php.

What each function does

• Webhook::constructEvent($rawBody, $signatureHeader, $secret) verifies the signature and returns the decoded event: id, type, version, occurred_at and data. When something fails, it throws WebhookVerificationException with a reason: missing_header, malformed_header, timestamp_out_of_tolerance, signature_mismatch, missing_secret, invalid_body, invalid_json, invalid_event.
• If you only want a yes or no, Webhook::verify($rawBody, $signatureHeader, $secret) returns true or false and never throws.
• Both reject a signature whose t is more than 300 seconds away from your clock. To change that, use the fourth argument: Webhook::verify($rawBody, $header, $secret, 600).
• The body can be a string or a PSR-7 StreamInterface.
• The algorithm is exactly the one of the portal's snippets/verificar-firma.php: X-Funnelchat-Signature: t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>." + raw body with the full secret, compared in constant time (hash_equals), and there can be several v1. The tests use the vectors of the portal's tests/test_firmas.py and compare, case by case, with a copy of the snippet.
• They are also on the client: $funnelchat->webhooks->verify(…) and $funnelchat->webhooks->constructEvent(…).

The event types. type is a string, because new types can arrive before the SDK knows them: answer 2xx to the ones you do not handle. Once you checked type, the alias of that event gives you the full shape (they are in Funnelchat\Generated\WebhookEvents: MessageReceivedEvent, MessageStatusChangedEvent…; and XxxData for its data):

The catalog of events the SDK knows, with their status, is Funnelchat\Generated\WebhookEvents::CATALOG.

Subscribing

• Subscriptions need Notifications (webhooks) → View and Notifications (webhooks) → Manage, and for each event type, the View of the event's area: Contacts and conversations → View for message.received. When it is missing, create and update answer 422 with the problem in errors['events'], and the others 403 permission_denied.
• They belong to the account: list() (paginated) also brings the ones of other integrations, except those with events of an area your key cannot read.
• To change the URL use update($id, […]), which replaces url, events, description and filters (the secret does not change). test($id) sends a signed webhook.test right now and listDeliveries($id) is the history.
• rotateSecret($id) is not open to API keys: it answers 403 route_not_available. Rotate the secret from the dashboard.
• message.status_changed must be requested by name: * does not include it.
• The catalog, with the area and status (active or planned) of each type, is $funnelchat->webhooks->events() (needs WhatsApp numbers → View). Since 21-10 it includes, among others, message.status_changed, whatsapp_form.completed, group.message_received, group.reaction_added and group_join_request.created.

Pagination

The list… methods return a lazy Paginator: nothing is requested until you iterate it.

The SDK understands the three ways the API paginates: by page number (meta.current_page and meta.last_page), by cursor (meta.next_cursor) and lists that come whole in an array. The page size is requested with each route's parameter (perPage, per_page or pageSize, as the spec says). $page->body is the full response of that page, with meta and links.

Errors

Everything the SDK throws extends Funnelchat\Exception\FunnelchatException. When the API answers with an error, it is an ApiException:

Each HTTP status has its class, in Funnelchat\Exception: BadRequestException (400), AuthenticationException (401), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), UnsupportedMediaTypeException (415), UnprocessableEntityException (422), RateLimitException (429) and InternalServerException (5xx). Without a response: ApiConnectionException, and ApiConnectionTimeoutException when the timeout ran out.

The errors of the API entrypoint itself, which answers without reaching any area, have their own:

A 403 with errorCode route_not_available means that route is not open to API keys, even if your key has the permission.

The refusals of creating or connecting a number are in Funnelchat\Exception\DeviceErrors, each with the statuses it comes with, and $exception->isDeviceError() tells them apart. The ones you will see most: 403 numbers_not_included, 403 number_limit_reached (with limit, used and pending_device_ids in body), 409 pending_number_exists (with device_id), 422 method_already_present (with device_id), 422 connection_type_mismatch, 422 idempotency_key_mismatch, 429 too_many_open_links and 503 meta_connect_disabled. Nothing was created.

The request id

Every response of the API, success or error, carries X-Request-Id: a different UUID per request, with which support finds the call. On an error it is in $exception->requestId; on a success, in $funnelchat->lastResponse() (the client's last response, with status, requestId and headers) or, for one call in particular, in onResponse, which also sees every page of a list:

An id you send yourself in X-Request-Id is not used: the API sets its own. There is no route to look a call up by its id.

Retries

• A request is retried on a 429, a 5xx or a network error (also when the timeout ran out), up to maxRetries times (2 by default), with the exceptions below.
• With Retry-After, the SDK waits exactly what it asks for. If it asks for more than 60 seconds, it does not wait: the exception is thrown right away with its retryAfter and you decide.
• Without Retry-After, the wait is exponential: 0.5 s, 1 s, 2 s… up to 8 s, with some jitter.
• A send is never retried by itself: the POSTs that need a Send permission (Contacts and conversations → Send or Groups and campaigns → Send: messages, contact cards, forwards, templates and forms). They are retried only if you pass 'retrySend' => true in that call. Reactions (PUT and DELETE) are retried, because repeating them changes nothing.
• A write that may have been applied is not repeated by itself: a POST or a PATCH is retried only on a 429 or a 503, when it was certainly not applied. On a 500, 502 or 504, a timeout or a dropped connection, the exception is thrown right away (a 502 origin_unreachable does not guarantee the area did not get it): read the state before repeating it. retrySend does not change this. Reads, PUTs and DELETEs are retried on any transient failure. It is the same rule as in the Node SDK.
• A create with an idempotencyKey (devices->create(), connectLinks->create()) is retried like a PUT: the API answers the same resource to the same key. A send is not, key or no key.
• 429 mac_lockout_24h, 429 mac_limit_reached, 429 too_many_open_links and 503 meta_connect_disabled are never retried.
• Per call you can change maxRetries and the headers, and with Guzzle the timeout:

Any route

request() calls any route, whether it is in a resource or not. Path parameters go in path, the query in query and the body in body:

It returns the decoded JSON (associative arrays), the text when the response is not JSON, or null when it came empty (204). Here the SDK does not know the shape of the response: if you want it typed, use the schema alias (/** @var BroadcastResource $broadcast */). The body [] is sent as {}.

paginate() is the same for lists: foreach ($funnelchat->paginate('/api/v1/broadcasts') as $broadcast).

The query is built the way Laravel reads it: arrays go as key[]=a&key[]=b, nested arrays with brackets, booleans as 1 and 0 and dates (DateTimeInterface) in ISO 8601, in UTC.

Funnelchat\Generated\Routes::ALL has every operation of the spec with its domain, its permission and the SDK method that calls it (sdk), or null when it is called with request().

Regenerating

Everything generated comes from a single script, in PHP:

What it does (scripts/generate.php):

1. With --spec, it copies the spec to spec/funnelchat.json and writes spec/procedencia.json: repository, branch, commit, date and sha256 of the file.
2. It adds spec/pending.json (the pending of the spec layer), but only what the snapshot does not bring. At the end it lists what the new snapshot already brings, so you can delete it from spec/pending.json.
3. It writes src/Generated/Routes.php (every operation), src/Generated/Schemas.php (every schema as a PHPStan alias), src/Generated/WebhookEvents.php (the catalog and the shape of each event, taken from the schema or from the example), src/Resources/*.php (one method per operation, with its types) and src/Generated/ResourceProperties.php (the client's properties).

spec/resources.json says which operation each method of each resource is: they are the same names as in Node. Regenerating never needs code edited by hand. If an operation of that list is no longer in the spec, the generation fails and says which one; if its shape changed, composer analyse flags it. After regenerating: composer check.

The current snapshot is the portal's, branch feat/openapi-unificada @ 0ef4abb, of 15-10: 191 paths and 230 operations of conversations 9d723d52c, communities fab0bb10 and accounts c234b6f8 (13-10). It predates what reached production on 21-10: what is new is in the pending layer. The details are in spec/procedencia.json. The snapshot's own texts (summaries and descriptions of its operations and events) are in Spanish, as the portal publishes them.

Pending of the spec

The spec snapshot is from 13-10. What reached production afterwards is in a separate layer, marked as such in the code, which the next regeneration replaces by itself once a snapshot brings it (and it tells you which entries can be deleted):

• spec/pending.json: paths, fields, responses, schemas and events, in OpenAPI format, with the source of each entry (x-fc-pending).

All of it comes from the code of the domains at the tags running in production on 22-10 (read only, git show <tag>:<file>): conversations v1.18.10 (a580a3d0), communities v2.34.52 (6f32f0b4) and accounts v1.4.24 (300cc843), plus the API entrypoint, api-edge v0.3.0 (a1c5b350).

The error codes of the sends are in Funnelchat\Exception\SendErrors, written by hand from the same sources: the spec does not list them. Those of creating and connecting numbers, in Funnelchat\Exception\DeviceErrors, from the contract.

Development

The suite runs on PHP 8.1 (with PHPUnit 10) and on PHP 8.5 (with PHPUnit 12), with Guzzle 7 and with Guzzle 8.

Testing against the sandbox

funnelchat-sandbox imitates the API and sends signed webhooks, with no real effects. Point the client at it with baseUrl and any well-formed key:

The Meta sign-up by link starts off in the sandbox, like production: type: 'meta' answers 503 meta_connect_disabled. Turn it on to try it, with npx funnelchat-sandbox --meta-connect, or while it runs:

The SDK's end-to-end tests run against it, version 0.2.0 or later (a send and its signed notices, which a receiver on PHP's built-in server verifies; the refusals; messages->get; a form from build to answer; X-Request-Id; a QR number created, scanned, disconnected and deleted, a connect link completed on its page, country, the refusals and the four signed device.* events). The tests of a meta link turn the Meta sign-up on by themselves:

License

MIT.