Wechat Work Contact Way Bundle Laravel Package

Getting Started

• Install via Composer: composer require tourze/wechat-work-contact-way-bundle. This is a Symfony bundle, not a Laravel package, so expect to wire it manually if you stay in Laravel.
• Look first at vendor/tourze/wechat-work-contact-way-bundle/src/. Check DependencyInjection/Configuration.php for config keys, and any Service/ or Client/ classes for the actual API calls.
• Minimal config typically needs WeChat Work corp_id, agent_id, secret, and callback token / encoding_aes_key if you handle events. In Symfony, register the bundle in config/bundles.php and create config/packages/tourze_wechat_work_contact_way.yaml.
• In Laravel, create a service provider that binds the bundle’s client/service classes with values from config/services.php. You may need to instantiate the Symfony container or use the classes directly if they have no container dependencies.
• First use case: create a “contact way” (联系我) QR code for a sales agent so customers can add them on WeChat Work. Call the contact-way creation service, persist the returned config_id, and render the qr_code URL in a view.

Implementation Patterns

• Inject the contact-way service into your controllers/jobs. Create a contact way with scene type, skip_verify, state, and user or department IDs. Store config_id, qr_code, and state in an Eloquent model for later lookup.
• Render the QR code either as the raw URL returned by WeChat or generate an image with a package like endroid/qr-code. Keep the config_id as the source of truth for updates/deletes.
• For customer acquisition flows, attach your internal identifiers in the state field. When a customer adds the agent, WeChat sends an event to your callback URL; use state to correlate the new customer with your campaign or landing page.
• Handle callbacks by implementing a controller that verifies the signature, decrypts the XML, and dispatches a queued job to sync the customer/contact way. The bundle may provide helpers—check for Callback or Message classes.
• For bulk or multi-agent rollouts, queue contact-way creation and respect WeChat rate limits. Wrap the bundle service in your own ContactWayService to add logging, retries, and caching.
• In Laravel, bind the bundle classes as singletons in a service provider and expose a facade or typed helper if you use them frequently. Avoid calling the API directly from Blade templates.
• If you need multiple WeChat Work corps, instantiate separate service instances with different config rather than relying on a single global config.

Gotchas and Tips

• Version 0.0.1 is pre-1.0. Expect missing docs, evolving APIs, and possible breaking changes. Pin the version and wrap the bundle behind your own adapter so you can swap it later.
• This is not a Laravel package: no auto-discovery, no facade, no published config. Budget time for a service provider and config mapping.
• Access token management is critical. Confirm whether the bundle caches tokens; if not, add a Laravel cache-backed token provider. WeChat tokens expire every 2 hours and are rate-limited.
• WeChat error codes are terse. Log the full response and map common codes: 40001 invalid secret, 40013 invalid corp ID, 60011 no privilege, 84061 contact way not found. Surface these in your logs with the request payload.
• The contact-way API requires customer contact permissions and a verified WeChat Work corp. Test with a real test corp; there is no public sandbox for this API.
• Callback URLs must be publicly reachable over HTTP/HTTPS. Use ngrok or a tunnel for local development, and make sure token and encoding_aes_key match exactly.
• Debugging: if using Symfony, enable the profiler and inspect the HTTP client panel. In Laravel, use Telescope or log the outgoing request/response in your adapter.
• Extension points are likely limited in 0.0.1. Prefer decorating or subclassing service classes over forking. Check for interfaces before extending concrete classes.
• Store the config_id—you cannot update or delete a contact way without it. Treat it as the primary key for remote state.