Skip to main content
Verified Actions are customer-approved tools that let the guide read or change a narrow business object after policy checks. They are not a generic API agent: every action targets one fixed operation, runs server-side, and passes a policy gate before it executes. Every action starts disabled. A workspace owner or admin enables a specific action instance in the dashboard before it can run, and server-side policy still checks the workspace flag, identity requirement, connector state, confirmation, and rate limit on every request.

How a request is gated

Each call walks the same gate. If any check fails, the action does not run and the result is surfaced for workspace review. Connector output is untrusted. The guide normalizes and redacts every result before it is reused in chat or replay, and writes are recorded with idempotency keys and audit logging.

Curated templates

The catalog ships exactly seven curated templates. Each one has a fixed schema, risk class, identity requirement, and confirmation requirement. All seven ship a managed adapter configuration path in the dashboard; an action fails closed until its workspace-specific connector and credential are configured. Run the dashboard connection test before enabling it for production traffic.
Connector credentials live in an encrypted vault and only the last four characters are ever shown back, so you can confirm which secret is stored without exposing it.
Support ticket creation connects to Freshdesk, Front, Help Scout, Intercom, Pylon, ServiceNow, Zendesk, or your own ticket API. The dashboard asks only for the fields required by that provider: a bare instance label where the provider uses one, a Help Scout mailbox ID, a Front inbox ID, and the provider’s documented credential type. Full base URLs are never accepted for a managed provider; your own ticket API takes a bare public https origin (see the ticket API contract below). The write is fixed per provider: Front creates an internal task, Pylon creates an issue with an internal destination, ServiceNow inserts only an incident, and the other adapters create their documented ticket/conversation object. Freshdesk and Pylon HTML fields escape visitor content. A successful receipt includes the remote ticket ID and a provider-origin URL. Connection tests use an authenticated read and never create a ticket. Pylon documents a 10-create-requests-per-minute limit. Puntego reserves that quota per configured action instance, uses an 8-second provider deadline, and does not automatically retry a 429, redirect, timeout, or ambiguous write. Intercom may create a missing contact before opening the conversation; if the conversation step fails, owner reconciliation must check for both objects.

Your own ticket API (generic REST contract)

Choose Your own ticket API when your helpdesk has no managed connector. Give the bare https origin of your service (no path, query, or fragment) and an API token. Puntego sends exactly two requests, both with the token as Authorization: Bearer <token>:
  • GET /health for the dashboard’s connection test. It never creates a ticket.
  • POST /tickets with Content-Type: application/json and an Idempotency-Key header that is the same for every retry of one confirmed write. The body is {"subject", "body", "requester_email", "page_url"}; body holds the subject followed by the visitor’s description of the problem (and the conversation, for the ticket with transcript), page_url is present only when the page is known, and requester_email is the signed-in visitor’s own email, bound on the server.
Answer 2xx with {"ticket_id": "…"} (or {"id": …}); the visitor’s receipt names that reference. Answer 401 or 403 to a token you no longer accept: Puntego treats a missing, revoked, or rejected credential as a permanent condition, tells the visitor plainly that the action can’t be done here (never “try again”), and shows the failure in your dashboard’s issues inbox on the first occurrence. Treat a repeated Idempotency-Key as the same ticket so a lost response can never open a second one.

Account entitlement response contract

The generic REST entitlement connector uses bearer-authenticated GET /health for its connection test and GET /entitlements/{id} for an account read. Passing the health check does not prove that a particular account can be read. The visitor executor resolves {id} from the signed active account, not from an account identifier supplied in the visitor’s question. Use the server-side account identity example to bind the signed-in customer to a currently authorized host workspace. A customer-only token cannot authorize this lookup; missing or unverifiable membership must not mint an account claim. The current answer supports plan and SSO entitlement, not seat usage, quotas, invoices, or permission to administer SSO. Return a nonempty plan (or plan_name / tier) and an explicit boolean, for example:
SSO can also be an explicit boolean in a features or entitlements object. A supported features array is treated as the complete list of enabled feature keys: ["sso"] means included; an empty list or a list without "sso" means not included. Do not return a partial list as if it were complete. Use the explicit boolean when your service cannot guarantee completeness. Missing, malformed, or contradictory SSO data fails with result_schema_invalid; Puntego does not turn unknown data into false. Fix the endpoint response and retry the account read before enabling visitor use. The visitor should receive an unavailable result, not a claim that their plan excludes SSO. Test explicit true, explicit false, omitted SSO, denied access, and the actual signed account separately from service health.

Identity and confirmation

Curated reads require a visitor_session, except Account entitlement lookup, which requires account_identity. Identity none is available only for custom read-only actions. Writes always require visitor confirmation in the same request. Writes also carry idempotency, audit logging, and redacted request and result storage, so a confirmed write is never replayed and is always reviewable. A generated card or table row can also offer a button for an enabled visitor action. The button works once, never for a forbidden category or an action that takes a password, a one-time code, or card data, and takes this same identity, policy, confirmation, connector, postcondition, receipt, and audit path. A standard write is approved with one tap in the answer card; one that pays, signs, or deletes something is confirmed with a button that names the consequence (Cancel has the focus and the button counts after a second), and a typed confirmation word only on a target you mark with confirmation_word. See Generative UI for the exact browser boundary. When a visitor clearly asks for what an enabled action does (“open a support ticket about SSO”), the guide prepares it straight away and the visitor reviews and confirms it in the answer card; it does not first ask whether they want it. A support ticket needs a subject and a description: when the visitor gives neither (“I want to open a support ticket”), the answer shows a short form for both; when only one is missing, the guide asks for it in one short question. Each visitor can run up to 10 account reads and 3 writes per minute for each enabled action. Past that, the guide says to wait a moment and ask again; it never guesses the account data in the meantime. When the guide instead points at a control on the page, a button for that same action (the control’s owner target, or a control named for what the action files) is shown beside the ring. The answer’s words never promise a button or a table the card does not show, and never deny the action a button beside them offers.

Actions filed in the visitor’s name

Support ticket creation and meeting booking need the visitor’s own email. Puntego fills it from the identity your server binds: the email trait of a customer identity token, or the contactEmail of signed account facts. The AI model never sees that input or its value, the pending request stores it sealed, and the confirmation card shows it as ”•••• (email)”. For a visitor with no bound identity these actions are not offered at all, so the guide never asks for an email it could not use.

Who an action is for

An owner or admin can restrict an enabled action to part of their audience: signed roles (for example admin), signed plans (for example Growth) or signed features (for example sso). Set it with PUT /api/tenants/{tenantId}/verified-actions/instances/{instanceId}/eligibility and a body such as { "eligibility": { "roles": ["admin"], "plans": ["Growth", "Scale"] } } ({ "eligibility": null } removes it); changing it asks for two-factor authentication like turning an action on. Only signed account facts can meet the rule, and only while their token is valid: the same values reported by the page never do. For a visitor signed in with a customer identity token, a signed role counts only when the token names that same person (userId, see Person); a plan or feature is the account’s. A visitor who does not meet it is not offered the action, and the policy refuses it with eligibility_required if it is requested anyway, including when the signed facts expire before the visitor confirms. Meeting the rule never replaces anything else: the action must still be enabled, its lane on, the plan must include it, and the visitor still confirms every write. If a provider times out after accepting a write, Puntego does not guess and does not redispatch it. The execution enters the Inbox until an owner or admin with recent MFA checks the provider and records either “external action completed” or “no external action occurred.” That immutable decision keeps the original idempotency key consumed in both cases. Cal.com does not document an idempotency key for booking creation. Puntego adds a one-way execution fingerprint to the booking’s documented metadata instead, so an operator can correlate an ambiguous result without exposing the raw key. The fingerprint is a reconciliation aid, not a provider deduplication promise. For POST-based customer proxy and manual endpoints, Puntego sends the same durable key in the Idempotency-Key request header. Proxy implementations should persist that key with the provider outcome and return the original outcome for duplicate requests. Do not derive a new key inside the proxy.

Verify requests from Puntego

Every request Puntego sends to your own endpoints is signed: customer proxy and manual endpoints, the generic REST connectors (your own ticket, order status, inventory and entitlement APIs), custom read-only actions, and the test calls Puntego makes when you add or check one. Verify the signature on your server and refuse anything else, so only Puntego can call those endpoints even if their URL leaks. Each v1 is the hex HMAC-SHA256, with your request signing secret, of these six lines joined by \n: puntego-request-v1, the timestamp, the nonce, the method in capitals, the path and query exactly as sent (/v1/orders?id=7), and the body’s SHA-256. To accept a request:
  1. Compute the SHA-256 of the raw body, before any JSON parsing, and the HMAC of the six lines.
  2. Compare it in constant time with each v1; accept if any matches.
  3. Refuse a timestamp more than five minutes from your clock.
  4. Refuse a nonce you already saw. Keep each one until five minutes after its timestamp, not after you received it: a request may arrive with a timestamp up to five minutes ahead of your clock.
@puntego/react/server does all four:
It returns ok: false with a reason (missing_signature, malformed_signature, stale_timestamp, body_mismatch, signature_mismatch, replayed or invalid_configuration). rememberNonce stores a nonce until expiresAt and returns false for one it already holds; without it, use the returned nonce yourself. The secret is per workspace. Find it in Dashboard → Guides → Actions → Request signing: Puntego creates one with the first request to your endpoints, and an owner or admin creates or rotates it there to get a copy (shown once, with two-factor authentication). After a rotation, requests carry the previous secret’s signature too for 24 hours, so you can deploy the new one without a gap; pass both to secret while you switch. If a secret leaked, rotate, then choose Stop old secrets now. A redirect to another origin never receives a signature. If Puntego cannot sign a request, it does not send it.

What the guide does on your pages

By default the guide acts on any control of your pages when a visitor asks it to, unless you ruled that control out. It reads the page as the visitor sees it and detects the risk of each control itself (see Auto-detect under Plan availability).
  • Moving around (scrolling to a section, opening or closing a section, switching tabs, opening a menu or a panel, following a link on your site): done directly.
  • Fields, selects and checkboxes: filled directly when the visitor gave the value, with a receipt and Undo. A value the guide inferred is proposed in the field first. The guide never types a password, a card number, a CVV or a one-time code.
  • A button the visitor asked for by name (“choose the Growth plan”, “save the security settings”): pressed directly, and the receipt says what happened. A button that pays, signs or can’t be undone is pressed after a 3-second countdown on the card (“Pressing “Confirm upgrade” in 3 s · Cancel”); tapping Cancel, or saying “stop”, stops it.
  • Something the guide suggests on its own (the visitor answered “do it” to a recommendation): one tap, or a spoken “yes”. If it pays, signs or can’t be undone, the armed button.
  • A request in parts: the guide does what it can now, and in the same answer asks only for what is missing or says, with the reason, what it did not do.
  • Another page: “change my phone to …” asked from another page takes the visitor there and fills the field, in the same request.
  • Passwords: the guide presses Save on a form that has a password field only when nobody typed a password there during this visit. If the visitor typed one, they press Save themselves.
You control it in Dashboard → Guides → Actions → Guide autonomy:
  • Only what I declared: the guide acts only on the controls you declared in AI walkthroughs, and only points at everything else.
  • No AI on a control: the guide never presses, fills or opens it. It can still point at it and say why.
  • Always confirm on a control: the guide asks first, even when the visitor asked for it.
  • Risk on a control: replaces the automatic detection for that control.
  • No-AI zones: an area of your pages where the guide never acts.
To name a control or an area, choose Pick on your site: the page opens in its own window, and clicking the control (or an empty part of the area) fills it in. You can also type its data-gp-id or a CSS selector. Each change saves as you make it. They are stored in your Guide Action Contract: autonomy: "declared_only", a target with no_ai: true (No AI: the guide can still point at it; allowed_actions: [] also rules out the point) or always_confirm: true, and no_ai_zones. The plan rules below still apply, and turning off Visible click or Visible form fill in Governance still turns those kinds of action off everywhere.

What a save keeps

Saving the Guide Action Contract never drops or changes anything without saying so. PATCH /api/tenants/{tenantId}/customization answers with the stored contract and, beside it, guide_action_manifest_report: how many entries of each kind were stored (accepted), each entry that was not, with its position in the array you sent, its id and a reason (dropped), and each stored entry that differs from what you sent, with the field and why (modified), plus the limits applied (100 targets, 100 actions, 50 forms of up to 12 fields, 50 No-AI zones, 20 record pages). Nothing is cut where a cut would change its meaning: an ID over 120 characters, or a selector, data-gp-id, link or route over its limit, drops the entry instead. A repeated ID keeps the first entry, and an unknown field is reported as ignored. Send "guide_action_manifest_mode": "strict" to store nothing unless every entry is stored exactly as sent: otherwise the save answers 422 customization/manifest_rejected with the same report. The dashboard and the recorder always save in strict mode and list the rows to fix.

Plan availability

On-page writes (a click, prefill, selection, checkbox, or fill plan on a control of your page you did not rule out) run on every plan. Each write the guide completes counts as one agent action against the plan’s monthly allowance, and a tour or fill plan counts once however many steps it has: Free 35, Starter 200, Growth 1,000, Scale 4,000, Business 10,000, and a contracted amount on Enterprise. When the allowance is spent, the guide points at the control instead of acting on it. A form fill whose every value the visitor wrote in their own message, on standard fields, is written at once, in view, with a receipt and Undo; a value the guide inferred, a field that pays, signs, or can’t be undone, or a fill that also submits still asks the visitor first, in the field itself. A fill that mixes both is split: the standard fields the visitor gave are written at once, and the rest is a step of its own below that receipt. A proposed value never looks entered: the field keeps its current value struck through, the proposal follows it with a dotted underline, a dashed outline and a Suggested tag mark the field, and a checkbox says Will be checked instead of showing a tick. In a form that applies its fields only when it is saved, a field that pays or signs is prepared (marking it changes nothing yet): directly when the visitor asked for it by name, with one tap otherwise, and its consequence is said on the form’s Save. A field that can’t be undone is never left for the Save, because the page may apply it as soon as it is marked: when the visitor asked for it by name it is marked after the 3-second countdown on the card, otherwise with the armed button. After a fill the receipt says whether the form is saved yet. When the visitor asked to save it (“…and save it”), or asked for what only saving does, the guide presses Save itself (after the 3-second countdown when saving pays, signs or can’t be undone, unless that countdown already ran on the field); otherwise the receipt offers Save in one tap. It never presses Save on a form where the visitor typed a password during this visit. A write to a target whose Consequence is financial, contractual, or irreversible needs Growth or higher. On Free and Starter the guide points at that control instead of acting on it. On Growth and higher, when the visitor asked for it by name, the guide does it after a 3-second countdown that one tap or “stop” cancels; when the guide suggests it, the visitor confirms it with a button that names the consequence: Cancel has the focus and the button counts only after a second. To ask for a typed confirmation word on a particular target (a large payment, say), set confirmation_word: true on that target in your Guide Action Contract. A spoken “yes” can approve preparing a form or a one-tap Save, never one of these. On every plan, the guide offers a write to a financial target only when the visitor’s own message names that action: the control’s name on the page, the target’s label, a form field’s label, or the action’s outcome label or description, in English, Spanish, or Portuguese. A one-word button name such as “Save” counts only when you have not given the action a longer name, and asking to turn something off never names turning it on. Otherwise it doesn’t offer that action: it explains, and points at the control the visitor did name when the page shows one, so a request to turn on instant payouts rings Instant payouts and never stages a bank-details save. An answer that says the guide can’t do what was asked never carries an action or a Verified Action confirmation; when that action needed your approval, no approval request is created and you are not notified. When the answer does offer it, the request reaches your Inbox, Slack and email only after the answer is sent. A target left on Auto-detect gets the same treatment when it looks like one of those controls: paying, buying, booking, checking out, subscribing, upgrading, adding a card, or moving money (financial); deleting, removing, closing an account, canceling a subscription, or revoking access (irreversible); signing or accepting an agreement or terms (contractual). Puntego reads the control’s accessible name, role, form, and nearby headings in English, Spanish, and Portuguese, and the Guide Action Contract editor shows what it detected. Set a target to Not elevated to keep it a standard write, or choose its class yourself. Your choice always wins over detection. A field that no target names is judged the same way when the guide types into it; to keep one standard, add it as a target and set Not elevated, naming it by its id (#amount) or data-gp-id so Puntego can match it to the live control. Server-side Verified Actions need Growth or higher for curated templates and governed custom writes, and Scale or higher for custom read-only actions.

Custom read-only actions

You can add a manually scoped read-only action when no curated template fits. A custom read-only action calls one fixed operation against one host, so it stays as narrow as a curated template. A custom read-only action requires:
string
required
Stable key that identifies the action instance.
string
required
Human-readable name shown to owners.
GET | POST
required
The single HTTP method the action uses.
string
required
One fixed base URL. The action cannot call any other host.
string
required
One fixed path on that base URL.
JSON Schema
required
Schema for the inputs the action accepts.
JSON Schema
required
Schema the connector output is validated against.
number
required
Per-minute cap on calls to this action.
object
required
A sample input used to test the action when you create it.
array
Optional redaction map applied to the connector output. The action works without it, but add it whenever the response can include sensitive fields.
OpenAPI and Swagger import is not supported. You cannot upload an API document to generate tools; each custom action is scoped by hand to one host and one path.

Showing a custom read to visitors

A custom read-only action is not offered to visitors until you say so. Each one has its own Visible to visitors switch in Dashboard → Guides → Actions, off by default. While it is off the guide never offers the action in chat, and a visitor’s request for it is refused as disabled. Turn it on and the guide can run the action in chat when a visitor asks for what it does, as long as the action is enabled and the custom-read lane is on for your plan. Everything else still applies on every request: the action’s identity requirement (none, visitor_session, or account_identity), any audience rule you set, the page-target map, the rate limit, and the redaction of its output. You can also set it with PUT /api/tenants/{tenantId}/verified-actions/instances/{instanceId}/visitor-visibility and a body such as { "visible_to_visitors": true, "expected_updated_at": "<the action's updated_at>" }. Turning it on asks for the revision you reviewed and for two-factor authentication, like turning an action on; turning it off asks for neither. Each change gives the action a new revision. Replacing the action’s endpoint keeps this choice, like its audience rule.

Governed custom writes

Custom visitor-confirmed writes are production features limited to reversible or low-risk categories: creating a lead, creating a ticket, booking a meeting, adding to cart, applying a coupon, or updating a non-sensitive preference. Before you can create a custom write, the dashboard requires explicit risk acknowledgment, and you must provide the target system, the visitor confirmation copy, and reversal or handoff instructions. A write that falls outside the allowed categories needs owner or human handoff instead of direct execution.
These write categories are always forbidden and can never be enabled:
  • Refunds
  • Cancellations
  • Access changes
  • Role changes
  • Password, API-key, or security changes
  • Payment or billing changes
  • Contractual acceptance
  • Broad exports
  • Arbitrary webhooks or emails
  • Regulated decisions

Skills: see, try, then turn on

Dashboard → Guides → Skills lists everything the guide can do for a visitor: the presses and fills you allow on your pages and the Verified Actions you added. Each skill is grouped by the part of your product it acts on and shows:
  • its verb (Create, Save, Fill in, Look up) and what it does, in your words;
  • its consequence in plain language, from the same classification the guide enforces: whether it can be undone, moves money, signs, or starts work that can’t be called back, and whether visitors approve it with one tap or confirm its consequence first;
  • After this, expect…: what your page shows once a press worked (the page changes to a path, an element appears, or a field is filled in). After pressing, the guide checks it and the visitor’s receipt says “Verified on this page” when it appears, or “Sent, not confirmed here” when nothing confirms it. Add these checks per action in Guides; free-text notes are kept but never checked;
  • an on/off switch. A skill does nothing for visitors until you turn it on, and a press or fill you add in Guides starts off. Turning a Verified Action on still needs your second factor.
Try it opens the skill in the preview (Dashboard → Guides → Preview), in test mode, before you turn it on. The real widget shows exactly what a visitor gets: the confirmation (one tap in the answer card, or the dialog that names the consequence for a skill that moves money, signs, or can’t be undone), the press on a stand-in for your control, and the receipt. A Verified Action runs against a simulated connection that answers like yours would, never against your production system. A trial applies the same rules as a visitor’s turn (your plan, your workspace settings, sensitive and password fields, and who an action is for), writes nothing live, and does not count against your usage.

Rollout checklist

Bring actions online one at a time and verify each gate before you widen traffic.
1

Enable only the lanes you need

Turn on just the action lanes required for the customer workflow. Leave everything else disabled.
2

Enable curated templates one at a time

Enable a single curated template, connect its managed adapter, and verify connector health before any production traffic.
3

Review custom read-only actions

Add custom read-only actions only after reviewing the fixed base URL, fixed path, input and output schemas, and the redaction map.
4

Confirm identity sources

Confirm every read that exposes personal data has a visitor_session (or stricter identity) before launch.
5

Keep custom writes off until reviewed

Leave custom writes disabled until an owner reviews the risk acknowledgement and confirms the action is reversible or low-risk.
6

Run replay QA

Replay one allowed action, one declined confirmation, and one blocked forbidden category, plus one stale-credential case, and confirm output redaction in each.
7

Review before widening

Review Inbox items and audit logs for correct redaction before enabling the next action.

Action Health contract

Workspace members can open Actions → Action Health to inspect bounded operational evidence for both on-page Guide actions and governed server-side Verified Actions. The reporting window is explicit (24h, 7d, 30d, or 90d) and stored in the URL. The outcome buckets are intentionally distinct:
  • completed is a terminal completion recorded by the applicable executor.
  • pending_verification is reserved for a browser action whose owner-declared observable condition has not settled.
  • dispatched means a browser click was sent without a machine-verifiable condition, or a governed server action is still in its dispatched state. It is not called a verified completion.
  • failed is a known terminal failure.
  • review_required means a provider dispatch may have happened but its effect is unknown. It is excluded from failed until an owner or admin reconciles it.
Guide latency measures the duration reported by the browser result envelope. Verified Action latency measures queue-to-provider-dispatch time only; the dashboard does not present it as end-to-end provider completion latency. Reconciliation decision time measures from the original execution creation to the operator decision and may therefore include execution age from before the selected decision window. The dashboard API returns counts, percentiles, fixed failure categories, owner-controlled action identifiers, and last-observed timestamps only. It does not return visitor or conversation identifiers, target data, request/result payloads, provider references, or raw failure reasons. Detailed evidence remains in the existing permission-gated, redacted Audit Log and Inbox reconciliation flow.

Create and replace custom actions

Creating a custom action never overwrites an existing action_key. A collision returns verified-actions/action_key_exists. Choose another key or review the existing action’s Replace safely flow. Creating or replacing leaves the action disabled until explicitly enabled. Replacement submits the complete reviewed configuration, including replace_existing with instance_id and updated_at from the current action record. A stale revision or changed action returns verified-actions/replacement_conflict or verified-actions/invalid_replacement; read current status and review the retained draft before submitting again. Do not drop the replacement precondition to force an overwrite. If the action no longer exists, the editor can retain the draft for explicit creation under a newly chosen key. After a response is lost, inspect current status before creating another action. A request timeout is not proof that nothing was saved. The current API does not return the complete saved custom configuration, so a status read alone cannot verify that every configuration field matches a draft.

Deployment notes

  • Keep actions server-side. Never expose connector secrets to the browser, prompts, logs, or model-visible context.
  • Keep the write consequence and recovery copy visible in-product and require acknowledgment for every creation flow.
  • Treat stale credentials, schema failures, failed writes, and policy blocks as Inbox items.
  • Roll back by disabling the action instance or its lane. Do not widen workspace-wide policy to make a single action pass.

Next steps

Authentication

How visitor sessions are minted and how programmatic API keys are scoped.

API reference

Endpoints, request shapes, and responses for the worker.

Privacy and PII

What is redacted before model and connector calls run.

Errors

Error namespaces and status codes you will see when a gate blocks a request.