- How do I install geekcodev/laravel-max-client in a Laravel app?
- Install it with Composer using composer require geekcodev/laravel-max-client. Laravel package auto-discovery registers the service provider and facade, so no manual registration is needed on supported versions. Publish the package config if you want to override the defaults, then add your MAX bot credentials to the environment file. Finish by clearing or rebuilding the config cache so the new keys are picked up.
- Which Laravel and PHP versions are supported, and can I use it outside Laravel?
- The package is a thin adapter built on standard Laravel pieces such as the service container, config repository, facades and queue, so it targets current Laravel releases. Check the composer.json constraints before upgrading a legacy application, and note that v1.2.2 requires the framework-agnostic core geekcodev/max-php-client at ^1.1.10 or newer. If you need MAX integration outside Laravel, use that core package directly instead of this adapter.
- How do I configure MAX bot credentials and environment variables?
- Publish the package configuration and keep the bot token, webhook secret and any mini-app session keys in your .env file rather than in committed config. The config file is read through Laravel's config repository, so run php artisan config:cache in production after changing values. Keep separate credentials per environment, because webhook subscriptions are per bot and per URL. Treat the token and webhook secret as secrets and never log them.
- How do I send a message, alert or notification to a MAX chat from Laravel?
- Resolve the client through the provided facade or inject it into a constructor, then call the core client methods for messages and notifications. It works the same from controllers, services, artisan commands and queued jobs, which keeps call sites clean inside Laravel services. For anything triggered by a request, dispatch a job instead of calling the API inline so user responses are not blocked by network latency. Alerts and notification fan-out are just loops over chat identifiers in your own service layer.
- How does the MAX webhook work and is the endpoint secure?
- The package ships a webhook route that is excluded from CSRF verification because MAX posts to it server-to-server. The handler is deliberately fail-closed: it compares the incoming secret with hash_equals and rejects the request before processing the payload when the check fails. Register the URL with php artisan max:subscribe and confirm what is active with php artisan max:subscriptions. Because delivery can repeat or arrive out of order, keep your handlers idempotent.
- Can I use Long Polling instead of a public webhook URL?
- Yes. Long Polling runs on top of the same framework-agnostic core, so you can receive updates without exposing a public HTTPS endpoint, which is useful for local development or hosts behind NAT. Run the polling loop as a supervised worker or long-running artisan command rather than inside a web request. Do not run Long Polling and a webhook subscription for the same bot at the same time, or you will process updates twice.
- How do I send MAX messages asynchronously with Laravel queues?
- Create jobs that resolve the MAX client and perform the API call, then dispatch them from your controllers, listeners or event handlers. Configure the queue connection, timeout and retry count so transient MAX API failures are retried and permanent ones land in failed_jobs for inspection. Since the client is container-resolved, each worker gets a properly configured instance without extra bootstrapping. Avoid storing large payloads in job properties; pass identifiers and reload the data in the job.
- How do I verify mini-app contact and read the web app session in v1.2.2?
- Version 1.2.2 adds WebApp\WebAppContactService and a final readonly WebApp\WebAppSession that map onto the existing max.webapp middleware lifecycle, so no new middleware or migration is required. Verification logic lives in the core package's WebAppContactVerifier and is not duplicated in the adapter. The confirmed-contact flag is stored in the session, not in max_users, so there is no database backfill. If you carried a custom contact_confirmed session key, set the MAX_WEBAPP_SESSION_CONTACT_CONFIRMED environment value so integrators do not silently lose confirmation state.
- How do I test MAX bot integration without calling the real API?
- Because the adapter registers the MAX client as a singleton in the container, you can bind a stub or mock implementation in your test case and assert what would have been sent. Use Queue::fake to verify that jobs are dispatched instead of letting them hit the network. Feature tests can post to the webhook route with the correct secret to exercise your handler, including rejection when the secret is wrong. Keep listener tests for duplicate, out-of-order and unknown event types so the new subscription types do not corrupt state.
- I upgraded to 1.2.2 but message edits still do not arrive. What did I miss?
- The default webhook subscription set moved from 6 to 13 types, but that change only takes effect after you re-subscribe. Run php artisan max:subscribe for each subscribed URL and confirm the result with php artisan max:subscriptions, which should now list 13 types per URL. Then make sure your listeners tolerate the new events such as message_edited, message_removed, dialog_cleared, chat_title_changed, user_added and user_removed, including deletes for records that no longer exist. Skipping the re-subscribe produces the same symptom as a broken package, so treat it as a mandatory runbook step after every upgrade.