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.
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 barehttps 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 /healthfor the dashboard’s connection test. It never creates a ticket.POST /ticketswithContent-Type: application/jsonand anIdempotency-Keyheader that is the same for every retry of one confirmed write. The body is{"subject", "body", "requester_email", "page_url"};bodyholds the subject followed by the visitor’s description of the problem (and the conversation, for the ticket with transcript),page_urlis present only when the page is known, andrequester_emailis the signed-in visitor’s own email, bound on the server.
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-authenticatedGET /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:
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 avisitor_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: theemail 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 exampleadmin), 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:
- Compute the SHA-256 of the raw body, before any JSON parsing, and the HMAC of the six lines.
- Compare it in constant time with each
v1; accept if any matches. - Refuse a timestamp more than five minutes from your clock.
- 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:
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.
- 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.
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 isfinancial, 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: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.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.
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:
completedis a terminal completion recorded by the applicable executor.pending_verificationis reserved for a browser action whose owner-declared observable condition has not settled.dispatchedmeans 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.failedis a known terminal failure.review_requiredmeans a provider dispatch may have happened but its effect is unknown. It is excluded fromfaileduntil an owner or admin reconciles it.
Create and replace custom actions
Creating a custom action never overwrites an existingaction_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.