Download the PHP package helfentalk/laravel-plugin without Composer

HeflenTalk Connect — Laravel plugin

helfentalk/laravel-plugin lets a HeflenTalk tenant securely expose their own data to their chatbot without the data ever leaving their server. HeflenTalk calls signed endpoints inside your app; the plugin verifies each request, applies your role rules, and reads or modifies only what you allow — per role, per table, per operation (view / create / edit / delete).

Writes go through your own Eloquent models, so your soft-deletes, observers, validation and approval workflows all run — the chatbot can never bypass them.

Install

Then set your Connect secret (from the HeflenTalk dashboard → API Keys / Connect) in .env:

Configure

config/helfentalk.php:

• allowed_tables — the only tables the plugin will ever touch ('all' or a list). Columns are auto-discovered; you never register endpoints per table.
• role_rules — row scope per role (own / team / all).
• models — required for writes; writes call your model so your own rules run.
• capabilities — the per-role × per-table action matrix (view is the base).
• writable_columns / guarded_columns — exactly which columns may change.

Finally, in HeflenTalk (Bot settings → Connect — data actions): set your endpoint URL, enable Connect, and tick Enable data actions to allow writes:

How it works

The signature covers "{timestamp}.{rawBody}" with HMAC-SHA256 using your HELFENTALK_KEY. The same secret signs the user-context JWT that identifies who is chatting — and the plugin can mint that JWT for you (see below), so you write no signing code.

User-context token — zero signing code (recommended)

Your chat UI must tell HeflenTalk who is chatting, as a short-lived JWT signed with your Connect secret. Instead of signing it yourself, the plugin exposes:

Your front-end calls it while the user is logged in, then sends the token to HeflenTalk's chat API as user_context.token. The JWT carries user_id (from auth.key), name, role and optionally department — HS256-signed with HELFENTALK_KEY.

Front-end wiring (the whole integration):

Prefer to sign it yourself? Set 'enabled' => false and issue an HS256 JWT with the same claims and secret.

Request (from HeflenTalk → plugin)

Response

Actions menu — let the chatbot run YOUR controllers (recommended)

The cleanest way to let the chatbot do things is to point it at your own controller methods. You list the actions it may perform; each one runs through your controller, so your validation, authorization (policies/gates), if/else logic and approval flows all execute exactly as they do for a normal web request. The chatbot can only ever do what is on the list, and can never bypass your rules.

How it decides which controller to run

You write a small menu in config — a plain-English label for each action and the controller method it maps to. The AI reads the labels (never your code) and picks the one that matches what the user asked. Anything not on the menu simply does not exist to the bot.

That's the whole mapping. With this, "make Ahmad inactive" becomes: the bot looks up Ahmad's id, matches the "Change a worker's status" action, shows you a preview ("set worker 1 to inactive — confirm?"), and only on your yes calls WorkerController@update — where your validation and approval run for real.

Three rules that make it work

1. Point at methods that DO the work and RETURN data — update, store, destroy — not the form-rendering edit / create / show (those return a page and write nothing).
2. Declare inputs with your real field/column names. The AI fills inputs from the conversation and sends exactly those keys. If your column is employment_state, name the input employment_state (not status) — otherwise your controller never sees the value and nothing changes.
3. Put enforceable logic where the controller runs it — in the controller, a Form Request, a Policy/Gate, or a model observer. If a rule lives somewhere the update/store/destroy call doesn't reach, it won't fire. (Approval that currently lives only in a different controller action should move into the model/observer, or just leave that action off the menu.)

What the bot returns to the user

• Validation fails (e.g. status not active/inactive) → the bot relays the exact validation message; nothing is written.
• Policy/authorization denies → the bot says you're not allowed; nothing is written.
• Not on the menu / typo'd controller → the bot can't do it (safe failure); it never guesses a different action.

Every run and preview is recorded in the audit log.

List and count through your controllers (read & count actions)

The actions menu isn't only for writes — point it at your index/list methods to let the bot find, list and count records through your own controller, so your company/tenant scopes, soft-deletes, policies and API Resource all apply. These run immediately (no confirm — they change nothing).

• read / count — read returns the list as a clickable table; count returns only the paginator total (your authoritative, already-scoped count — no rows, so the app shows a plain number). Both run immediately and never write.
• view_route — a deep-link template; {placeholders} are filled from each row's own fields, so clicking a row opens its page in your app.
• inputs — OPTIONAL filters your index() understands; the bot may omit them to list everything.
• params — fixed request params ALWAYS sent to your controller (the bot can't set or override them) — e.g. a larger per_page so a list fills a table, or a forced sort.

Your index() should return JSON — a paginated API-resource collection ({ "data": [...], "meta": { "total": N } }) or a bare list. The plugin unwraps the envelope, attaches a view_url to each row, and surfaces meta.total as the count.

Reads through your controllers, too. Because index actions already apply your scopes and soft-deletes, you can leave the generic-CRUD capabilities empty ([]) and route everything — reads, counts and writes — through your own controllers. This is the most locked-down setup: the plugin never touches the database directly.

Data actions via generic table CRUD (alternative)

If you'd rather not wire controllers, you can instead map models and grant capabilities, and HeflenTalk can let the chatbot find, count, create, edit, change status and delete records through the model layer — all within the limits you set. Two more signed endpoints power both this and the actions menu (same HMAC contract):

• POST /helfentalk/manifest — tells HeflenTalk what the user's role may do (tables, capabilities, writable columns), so it only ever offers permitted actions. The plugin still re-enforces everything on every action.
• POST /helfentalk/action — executes one action:

Confirm before write. With confirm: false (the default) the plugin only previews — it returns the matched count and the exact change and commits nothing. The chatbot shows that to the user and only re-sends with confirm: true after they agree. Nothing is written until you (the end user) say yes.

Your process is law. Deletes call $model->delete(), so a model using SoftDeletes is soft-deleted, and any deleting/saving observers or approval workflows you have run normally. If your delete needs approval, the chatbot cannot skip it.

Clickable rows from generic queries. To turn rows from the generic query operation into deep links too, add a view_routes map — the same per-row view_url that read actions produce:

Security

• Every request is HMAC-verified before any DB access; missing, stale (> tolerance), or invalid signatures are rejected with 401.
• The allowed_tables whitelist is enforced strictly — the plugin never touches a table outside it.
• Rows are always scoped by role: own filters by user_column = user_id, team by team_column = team_id; an unknown role falls back to own (never leaks everything).
• The plugin recomputes the scope and capabilities from its own config and never trusts anything HeflenTalk sends.
• Writes are gated four ways: the role must have the capability, the table must map to a model, only writable_columns (minus guarded_columns) may be set, and a single update/delete may not exceed max_write_rows.
• Writes run through your Eloquent models inside a transaction — never raw SQL — so soft-deletes, observers and approval flows always fire.
• Every write (and preview) is recorded in the audit log (helfentalk_audit_logs).

Test

Sibling plugins for other stacks: helfentalk-express (Node) and helfentalk-django (Python) follow the same signed-request contract.