Laravel Trengo Guidelines

Laravel Boost guidelines and an agent skill for Trengo REST API development in Laravel.

Installed alongside Laravel Boost, this package ships:

• A concise guideline, loaded upfront into your AI context file (CLAUDE.md, AGENTS.md, etc.) — core Trengo conventions for authentication, rate limiting, webhook signature verification, and the standard app/Trengo/ file structure.
• A focused trengo-development skill, activated on-demand — complete patterns for the HTTP client, resource classes, pagination, the webhook pipeline, error handling, and testing.

Your AI coding agent (Claude Code, Cursor, and others supported by Boost) gets the right context at the right moment: foundational rules always available, deep implementation detail only when the task is Trengo-related.

Why a guidelines package?

Without guidelines, AI agents treat every Trengo integration as a blank canvas: different folder layouts per project, inconsistent error handling, webhook signatures verified against re-encoded bodies, rate-limit issues that only surface in production. This package captures the conventions once and makes them auto-loadable across any Laravel project.

Requirements

• PHP 8.2 or higher
• Laravel 11, 12, or 13
• Laravel Boost installed in your application

Installation

composer require dvolkering/laravel-trengo-guidelines --dev

If Boost is not yet configured in the project, run the installer:

php artisan boost:install

If Boost is already installed, let it discover the newly installed guidelines and skill:

php artisan boost:update --discover

Boost will detect dvolkering/laravel-trengo-guidelines, merge the guideline into your AI context file, and publish the skill to .ai/skills/trengo-development/SKILL.md.

What gets installed

The guideline (always-on)

Shipped at resources/boost/guidelines/core.blade.php, loaded by Boost into your project's AI context file. Covers:

• Base URL, authentication, and header conventions
• The 120 req/min rate limit and how to structure calls to respect it
• Webhook signature verification rules and the Trengo-Signature format
• The standard app/Trengo/ file structure
• A minimal Http::macro('trengo') client registration
• When to use a Controller versus a Job

It is deliberately short — most depth lives in the skill.

The skill (on-demand)

Shipped at resources/boost/skills/trengo-development/SKILL.md, activated by the agent when the current task touches Trengo code. Covers:

• The full HTTP client with 429 + 5xx retry handling that respects the Retry-After header
• Resource class patterns (TicketsResource, ContactsResource, MessagesResource, LabelsResource)
• A pagination generator for safe iteration over large result sets
• The complete webhook pipeline: signature verification middleware, async dispatch, idempotency, mapping Trengo events to Laravel events
• All Trengo webhook event types grouped by category
• Error handling with TrengoException and TrengoNotFoundException, plus central exception rendering in bootstrap/app.php
• Testing patterns with Http::fake() and self-generated webhook signatures
• Common pitfalls and how to avoid them

Project setup after installation

Add the required environment variables to your .env:

TRENGO_API_TOKEN=your-personal-access-token
TRENGO_WEBHOOK_SECRET=your-webhook-signing-secret

Add the services entry to config/services.php:

'trengo' => [
    'token'          => env('TRENGO_API_TOKEN'),
    'base_url'       => env('TRENGO_BASE_URL', 'https://app.trengo.com/api/v2'),
    'signing_secret' => env('TRENGO_WEBHOOK_SECRET'),
    'timeout'        => 15,
],

From that point on, ask your AI agent for any Trengo-related task and the trengo-development skill will be consulted automatically. Example prompts that trigger it:

• "Add a webhook handler for TICKET_ASSIGNED that notifies our internal Slack."
• "Create a Job that closes all tickets labelled resolved older than 30 days."
• "Set up the TrengoClient with rate-limit-aware retries."

How it works

Laravel Boost auto-discovers resources/boost/guidelines/ and resources/boost/skills/ in any installed Composer package. On boost:install or boost:update --discover, Boost merges guideline files into your project's AI context files and publishes skill folders to .ai/skills/.

Local overrides are respected: if you publish the skill and then edit .ai/skills/trengo-development/SKILL.md in your project, Boost preserves your edits on subsequent boost:update runs.

Versioning

Semantic versioning (semver.org). Guideline and skill content target the Trengo v2 REST API as published at developers.trengo.com/reference.

Contributing

Issues and merge requests are welcome at gitlab.com/dvolkering/laravel-trengo-guidelines.

Before opening a merge request, please verify that any updated code examples reflect the current Trengo API — the reference at developers.trengo.com is the source of truth.

License

MIT — see LICENSE.