Docs

Connections

Let the AI agent read a customer's account

With customer actions, your website agent looks up a signed-in customer's own records, such as jobs or invoices, through one signed endpoint on your server.

In Nuteq, customer actions let your website agent look up information about the signed-in customer who is chatting, such as their recent jobs or an invoice. You declare a few read-only actions, host one signed endpoint on your server, and Nuteq calls it when the customer asks. Your server decides what each customer may see.

What do I need before I start?

  • Recognition is on. Customer actions only work for a signed-in customer, so set up website customer recognition first. Guests never trigger an action.
  • A public HTTPS endpoint. Nuteq posts to one URL on your server. It must be https, on a public domain name, and must not redirect.
  • Node 22 or newer if you use the @nuteq/server package below. Any language works if you verify the signature yourself.
  • The widget's install key. It is the same string as the data-key on your widget script tag, and the endpoint receives it as install_key in every request body.

The widget's Sign in button is covered in website customer recognition.

How do I set it up in the dashboard?

The owner and the developer each have a part. The owner opens the Website tab in Connections and sees a short checklist.

  1. Recognize signed-in customers. Turn on sign-in first. The checklist shows one step at a time, and a finished step collapses behind a check.
  2. Your developer connects your server. The owner chooses Send to your developer, which copies a link to the developer page. The developer saves the endpoint URL there and creates the signing secret. Nuteq shows the secret once, so copy it into NUTEQ_ACTIONS_SECRET on your server, then choose I've stored it and confirm. If you lose it, rotate the secret to get a new one. The secret is never part of the owner's page or the link. No developer? Customer actions need someone who can change your website's server. Your agent works without them.
  3. Test and turn on. Nuteq asks your server for its list of actions and shows each one with the example a customer can ask. Run a test as the test account. Each action shows Tested or Not tested. Once a test passes, Turn on appears right under the result and reads "Turn on 1 tested action"; actions you have not tested stay off until you test them. Action switches appear after you turn actions on.

If something goes wrong during setup, the card shows Needs your developer and names what failed and why: your server returned an error, took too long to answer, couldn't be reached, sent an answer Nuteq can't read, or rejected the signature. The developer page shows the same cause in technical terms, including the HTTP status code your server answered with. Fix the server, then choose Check for new actions on the developer page or the owner card. Later changes to your actions show up the same way. An action your server stops listing is removed.

Each action becomes a tool the agent can use in the website chat, named account_ plus the action name. When a refresh finds a new action while actions are already on, the action is added switched off and marked New with "Test it, then switch it on." under its title, and its own test opens. Each action card has a Test button once actions are on. If a switched-on action fails, its card turns red with the time and cause and a Switch off button, the banner names the cause and says whether your other actions keep answering, and your team gets an email unless email alerts are off. The card shows On, No actions on, Paused or Failing (only for actions that were on and stopped), the host it is connected to, and View activity, which lists recent requests by action and outcome, never the values. The full server address is on the developer page and under Copy server address in the menu.

What does the manifest look like?

Nuteq reads this list from your server. The @nuteq/server handler answers it when you pass the manifest as manifest, so you do not upload anything. If you do not use the package, answer the nuteq.describe request yourself (see the golden fixture describe.json): Nuteq posts {"version":2,"install_key":"wk_…","action":"nuteq.describe","arguments":{}} with no customer attached, and you answer {"manifest":{"version":1,"actions":[…]}}, or a 404 not_found error body when you have no list, or paste or upload the file under Paste or upload an actions file instead on the developer page. The manifest is a JSON file named nuteq-actions.json. Each action has a lowercase name, a description the AI reads, an optional example (up to 140 characters) such as what a customer might say, and up to 8 arguments. An argument can also have an example (up to 100 characters), a real sample value that prefills the dashboard test. Do not declare an argument for the customer: Nuteq adds the identity itself. An action can also list hidden_fields (up to 32 keys of its result, such as an internal note). Nuteq removes them before the agent, the activity list or the dashboard test sees the answer; the test only says which fields are hidden.

{
  "$schema": "https://nuteqai.com/schemas/nuteq-actions.v1.json",
  "version": 1,
  "actions": [
    {
      "name": "get_account_summary",
      "description": "Show the signed-in customer's plan, credit balance and renewal date."
    },
    {
      "name": "list_recent_jobs",
      "description": "List the signed-in customer's most recent jobs with their status.",
      "arguments": [
        { "name": "status", "type": "enum", "required": false, "description": "Only jobs in this status.", "values": ["queued", "running", "done", "failed"] }
      ]
    },
    {
      "name": "get_job",
      "description": "Show one of the signed-in customer's jobs by its ID.",
      "example": "Where is my job J-1042?",
      "hidden_fields": ["internal_note"],
      "arguments": [
        { "name": "job_id", "type": "string", "required": true, "description": "The job ID the customer gives.", "max_length": 64, "example": "J-1042" }
      ]
    }
  ]
}

$schema is optional. The same schema ships in the package as @nuteq/server/nuteq-actions.v1.json for editor validation. kind is optional and can only be "read".

Argument types are string, integer, number, boolean, enum and date. A string needs max_length. An integer or number can set minimum and maximum, for example { "name": "limit", "type": "integer", "required": false, "description": "How many jobs, 1 to 10.", "minimum": 1, "maximum": 10 }. Nuteq tells the AI the range and refuses a value outside it before your server is called. Bounds must be between -2^53 and 2^53, and whole numbers for an integer. Names that refer to the user, such as user_id, email or account_id, are refused, because identity never comes from an argument. job_id is fine.

How do I write the endpoint in Next.js?

Install the package, then add a route. nextRoute reads the raw request body, which the signature covers, so do not parse the body yourself.

The package is not on npm. Build it from the Nuteq repository and install the tarball. Do not copy src/ into your project: the sources use .js import suffixes that test runners such as Jest cannot resolve. The tarball holds built ESM, CommonJS and type files, so it works in a bundler, in Jest and in plain Node.

cd sdks/server-node && npm pack   # builds, then writes nuteq-server-0.2.0.tgz
cd your-app && npm install ../nuteq/sdks/server-node/nuteq-server-0.2.0.tgz
// app/api/nuteq/actions/route.ts
import { createActionHandler, nextRoute, NotFound } from '@nuteq/server'
import { db } from '@/lib/db'
 
const secret = process.env.NUTEQ_ACTIONS_SECRET
 
const unavailable = () => Response.json({ error: { code: 'unavailable', message: 'Customer actions are not configured.' } }, { status: 503 })
 
export const POST = !secret ? unavailable : nextRoute(createActionHandler({
  secret,
  actions: {
    get_account_summary: async ({ identity }) => {
      const account = await db.account.findUnique({ where: { userId: identity.userId } })
      if (!account) throw new NotFound()
      return { plan: account.plan, credits: account.credits, renews_on: account.renewsOn }
    },
    list_recent_jobs: async ({ identity, arguments: { status } }) => {
      const jobs = await db.job.findMany({
        where: { userId: identity.userId, ...(status ? { status } : {}) },
        orderBy: { createdAt: 'desc' },
        take: 10,
      })
      return { jobs: jobs.map((j) => ({ job_id: j.id, status: j.status, created_at: j.createdAt })) }
    },
    get_job: async ({ identity, arguments: { job_id } }) => {
      const job = await db.job.findUnique({ where: { id: job_id } })
      if (!job || job.userId !== identity.userId) throw new NotFound()
      return { job_id: job.id, status: job.status, created_at: job.createdAt }
    },
  },
}))

The handler checks the signature, the timestamp and the request ID before your code runs. It also adds the user_id echo Nuteq requires to every success response. Pass the parsed manifest as manifest: Nuteq reads your actions from it, and the handler also refuses undeclared actions and re-checks argument types, including minimum and maximum. Without it, discovery fails with "not an actions list". If Nuteq says your server's package is out of date, update @nuteq/server and check again.

createActionHandler throws a ConfigurationError when the secret is missing or empty, so a deploy without it fails at startup instead of on the first request. The route above checks first, so a preview deploy without the variable answers Nuteq with a clean unavailable (503) instead of crashing with a 500. Answer unavailable for any server misconfiguration. Reserve denied for a customer who may not do something: the agent tells the customer they are not allowed.

How do I try the endpoint without the dashboard?

createSignedTestRequest signs a request exactly the way Nuteq does, and the package ships a small command that sends one. Put the secret in an environment variable, not on the command line.

NUTEQ_ACTIONS_SECRET=nqa_... npx @nuteq/server test-request \
  --url http://localhost:3000/api/nuteq/actions \
  --action get_job --arguments '{"job_id":"job_123"}' --user-id usr_1042

It prints the status and body, and exits with a non-zero code on anything but a 2xx answer. Add --install-key and --session-id to match your data, --secret-env NAME to read a different variable, or --dry-run to print the signed request without sending it. In tests, call createSignedTestRequest({ secret, url, action, arguments, userId }) and send the returned headers and body yourself. The dashboard's test request still checks the deployed URL.

What session_id should I use if I have no server sessions?

Nuteq needs a stable string per sign-in. It is not a secret and does not have to be a server session. Pick one you can recompute or look up when the customer signs out:

  • JWT or Cognito apps: use an ID that survives token refreshes, such as the token's origin_jti, or a hash of sub and auth_time. A plain jti changes on every refresh and will not match later.
  • Any app: issue your own random ID at sign-in and keep it in an httpOnly cookie, or in your database next to the user.

Do not use a random per-tab or per-page ID: you could never revoke it. The same ID must go into the identity you sign for the widget, and it is what the actions endpoint receives as identity.sessionId.

How do I revoke a session when the token is already gone?

Revoke from your server, with the session ID you stored or can recompute, not from the browser. If the sign-out code has already cleared the token, keep the session ID server-side at sign-in so the revoke route can look it up from your own cookie or database. If you cannot find it, revoke by user ID instead: that ends every widget session for that customer, on every device.

import { signRevocation } from '@nuteq/server'
 
const { payload, userHash } = signRevocation({ install_key: process.env.NUTEQ_WIDGET_KEY!, session_id: sessionId }, process.env.NUTEQ_WIDGET_IDENTITY_SECRET!)
// or { install_key, user_id } to end all of the customer's sessions
await fetch('https://api.nuteqai.com/v1/public/text/identity/revoke', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ key: process.env.NUTEQ_WIDGET_KEY, revocation: { payload, user_hash: userHash } }),
})

The SDK returns userHash in camel case, and the wire name is user_hash. Sending the SDK envelope as is gives a 400. Run identify(null) in the browser as well, then call your revoke route.

What does Nuteq send and expect back?

Nuteq sends one POST to your endpoint URL. The action is in the JSON body, so there is one URL for every action.

PartValue
Bodyversion, install_key, action, arguments, and identity with method: "signed_in", user_id and session_id
X-Nuteq-Request-IdA new UUID for every attempt. Reject one you have already accepted.
X-Nuteq-TimestampUnix seconds. Reject a request more than 300 seconds from your clock.
X-Nuteq-Signaturev2=<hex>, with a second v2= entry during a secret rotation. Each is an HMAC-SHA256 over the method, the path as received, the timestamp, the request ID and the SHA-256 of the raw body.

A success is a 2xx application/json object with user_id (the same ID Nuteq sent) and a result object. An error is {"error":{"code":"…","message":"…"}} with one of these codes.

CodeUse it whenFallback status
not_foundThe record is missing or belongs to someone else404
deniedThe customer may not do this401, 403
invalid_argumentsThe arguments are wrongother 4xx
rate_limitedYour server wants the agent to slow down429
unavailableYour server cannot answer now5xx, 3xx

An error body wins over the status. If the user_id echo is missing or different, Nuteq treats the answer as denied and drops it. The exact bytes are pinned by the golden fixtures in sdks/fixtures/customer-actions-v2 in the Nuteq repository.

How do I keep customers' data safe?

  • Never trust arguments for identity. Use identity.userId from the verified request. The model chooses the arguments and can be tricked.
  • Return not_found for other people's records. Return the same answer for a missing record and a foreign one, so a visitor cannot probe for other customers' IDs.
  • Keep the secret on the server. Store it in an environment variable. It must never reach browser code, a repository or a log.
  • Rotate with the overlap. After you rotate, both secrets sign for 24 hours. Pass both to secret as an array if you deploy in stages, then remove the old one.
  • Do not change the path. Nuteq signs the escaped path of your configured URL. A proxy or basePath that rewrites it breaks verification, so configure the URL your server receives.
  • Know what the replay cache covers. See the next section.

What does the replay cache protect on serverless?

Every request has a new ID, and the handler refuses an ID it has already accepted. The default cache lives in memory, so each serverless instance keeps its own. Without a shared cache, someone who captured a signed request could replay it once on each instance during the 300-second window. They cannot change it, because the signature covers the whole request. For read-only actions this is low risk. It matters more once write actions arrive, so share the cache if you can.

A shared cache is any object with claim(requestId, ttlSeconds) that returns true the first time it sees an ID and false after. For example with Upstash Redis:

import { Redis } from '@upstash/redis'
import { createActionHandler, type ReplayCache } from '@nuteq/server'
 
const redis = Redis.fromEnv()
const replayCache: ReplayCache = {
  claim: async (requestId, ttlSeconds) => (await redis.set(`nuteq:rid:${requestId}`, '1', { nx: true, ex: ttlSeconds })) === 'OK',
}
// createActionHandler({ secret, replayCache, actions })

If the cache throws, the handler does not run your action and the request fails closed.

What limits apply?

  • Up to 20 actions per website agent, each with up to 8 arguments.
  • Nuteq waits 5 seconds in total for your answer and does not follow redirects.
  • Responses over 32 KiB are refused. Text over 2 KiB per value is cut, and the agent is told.
  • Per signed-in customer, 60 calls per hour. Per chat, 30 calls and 3 per turn.
  • Only read actions are available.

By Nuteq AI TeamPublished Updated 10 min read

Was this page helpful?

Keep reading

Frequently asked questions

Can the AI agent read another customer's records?
No, as long as your endpoint checks ownership. Nuteq sends the signed-in customer's ID with every request, and your code must return not_found for any record that belongs to someone else. The model cannot choose or change that ID.
Can customer actions change data on my side?
No. Only read actions are available today. The agent can look things up for the signed-in customer, but it cannot create, edit or delete anything through your endpoint.
What happens when I rotate the signing secret?
Nuteq signs each request with both the new and the previous secret for 24 hours. Deploy the new secret to your server inside that window, then drop the old one.

Ready to stop missing calls?

Nuteq AI answers every call and text, books appointments, and captures every lead — 24/7.