Build an order-status action endpoint

This backend powers the Connect a system walkthrough. It implements Visito → your endpoint using Node.js built-in modules, synthetic orders, and no database or extra packages.

Run the example

Download order-status-server.mjs, save it locally, and start it with Node.js:

TOOL_DEMO_SECRET=local-demo-only node order-status-server.mjs

The default endpoint is http://127.0.0.1:4191/visito/order-status. local-demo-only is an intentionally public sample token for a restricted local demo. Use a private secret and HTTPS before exposing a real service. The sample does not verify customer identity and must not serve real order data unchanged. The server has two fixture records:

const orders = new Map([
  ['A-1003', {
    status: 'shipped', carrier: 'Demo Courier', tracking_number: 'DEMO1003',
    estimated_delivery: '2026-10-03',
    last_update: 'Package left the distribution center.'
  }],
  ['A-1004', {
    status: 'processing', carrier: null, tracking_number: null,
    estimated_delivery: '2026-10-06', last_update: 'Your order is being prepared.'
  }]
]);

The lookup is selected dynamically from the supplied number; the records themselves are fixed demo fixtures. Replace the dates when reusing the example. Nothing connects to a carrier or sends a real package.

Follow the request through the server

This annotated excerpt highlights the controller flow. Authentication, body limits, and failure handling remain in the complete downloadable source.

Order controller: parse the number, validate, look up the record, and return a result.

1. Check the route and authentication

The server accepts only POST requests to /visito/order-status. It checks Authorization: Bearer ... against TOOL_DEMO_SECRET before looking up any order. Other routes return 404; missing or incorrect credentials return 401.

2. Read a bounded JSON body

The sample reads at most 4 KiB. Oversized requests return 413, invalid JSON returns 400, and server request/header timeouts are 10 seconds. Its logs record only the synthetic order number, whether it matched, and the source; they do not print the authorization header.

3. Extract the parameter

For POST, Visito sends the action’s input inside arguments. The relevant code is:

const number = body?.arguments?.order_number;
if (typeof number !== 'string' || !/^A-[0-9]{4}$/.test(number)) {
  return reply(400, { error: 'invalid_order_number' });
}

order_number comes from the customer through the action input schema. It is not read from the URL path or from body.order_number. The sample accepts A- followed by four digits. Validate again server-side even when the schema declares a required string.

4. Look up and return the record

if (number === 'A-5000') {
  return reply(503, { error: 'order_service_unavailable' });
}
const order = orders.get(number);
return reply(200, order
  ? { found: true, order_number: number, ...order }
  : { found: false, order_number: number });

For a real integration, replace orders.get(number) with an authorized query or provider call. Check the requester’s access before returning the record. Keep provider credentials on your server. Missing orders and unavailable providers are different outcomes; do not report an outage as found: false.

5. Let Visito use the result

Visito reads the JSON response and returns it as the tool result to the model. The model continues the same conversation with those facts and writes the customer-facing answer. This is why a clear status, an explicit estimate, and a separate found field are useful. HTTP 200 alone does not establish a business outcome.

Check the request and response

In a second terminal:

curl --fail-with-body http://127.0.0.1:4191/visito/order-status \
  -H 'Authorization: Bearer local-demo-only' \
  -H 'Content-Type: application/json' \
  --data '{"arguments":{"order_number":"A-1003"},"meta":{"source":"developer_test"}}'

Expected HTTP 200 body:

{
  "found": true,
  "order_number": "A-1003",
  "status": "shipped",
  "carrier": "Demo Courier",
  "tracking_number": "DEMO1003",
  "estimated_delivery": "2026-10-03",
  "last_update": "Package left the distribution center."
}

Variation	Result
`A-1004`	200, processing, null carrier and tracking number
`A-9999`	200, `found: false`
`A-5000`	503, `order_service_unavailable`
Missing number, numeric value, or invalid format	400, `invalid_order_number`
Malformed JSON	400, `invalid_json`
Missing or incorrect token	401, `unauthorized`
More than 4 KiB	413, `request_too_large`

The captured local verification checked known/unknown orders, numeric input, missing authentication, and the simulated provider failure directly. Webchat checked missing-number collection, a known order, an unknown order, and the provider failure. Other table rows describe the sample’s validation paths, not additional captured Webchat tests. Live conversation metadata can include tenantId, conversationKey, conversationId, channel, and eventId. The direct Visito test endpoint uses tenantId and source: "developer_test"; do not require a live conversation ID for those tests. Metadata provides context, not proof of order ownership.

Make the endpoint reachable

Runtime	URL and access
Host process calling another host process	The loopback URL can work
Local Visito in Docker	Use a reachable service name or host address; container localhost is the container itself
Hosted Visito	Use an authenticated HTTPS endpoint reachable by Visito; it cannot call your laptop’s localhost

The captured test ran the server on the same local Docker network as the tool gateway. For a similar local Compose setup, replace YOUR_LOCAL_NETWORK with the actual network, then run from the folder containing the downloaded file:

docker run --rm --name visito-order-status-docs \
  --network YOUR_LOCAL_NETWORK \
  -p 127.0.0.1:4191:4191 \
  -e HOST=0.0.0.0 -e TOOL_DEMO_SECRET=local-demo-only \
  -v "$PWD/order-status-server.mjs:/demo/server.mjs:ro" \
  node:20 node /demo/server.mjs

Use http://visito-order-status-docs:4191/visito/order-status in the local action. The published port is restricted to host loopback; the server is also reachable on the chosen Docker network. Do not reuse this hostname in hosted Visito. No public tunnel was used for the captured run. If your existing provider accepts GET, Visito sends action inputs as query parameters. POST sends { "arguments": { ... }, "meta": { ... } }. Dynamic provider paths, different bodies, or OAuth refresh belong in an adapter. See the full contract.

Test the saved definition

Configure it under Actions → Connect a system, with POST, Bearer authentication, an 8-second timeout, and Read only enabled. Use Playground-only mode for a Playground test, or Active for an explicitly controlled Webchat test. For a direct API test, obtain the stable action ID http:<toolId> from Action configurations. You can keep the action Off for this explicit test. The Visito API key needs actions:http:execute; listing definitions additionally requires action_configurations:read.

curl --fail-with-body \
  "https://platform-api.visitoai.com/m2m/v1/actions/http:YOUR_TOOL_ID/test" \
  -H "Authorization: Bearer $VISITO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"input":{"order_number":"A-1003"}}'

This sends a real request and creates a log. Check ok, output, and error; an HTTP 200 from the test API can still contain ok: false. A repeated test is another invocation. For write actions, never blindly repeat a request whose outcome is uncertain. The Visito API key is separate from the endpoint’s TOOL_DEMO_SECRET.

Inspect and clean up

Use Actions → History to inspect the input, response, HTTP status, method, endpoint, and timing. The Saved request data panel may show only the action arguments; it is not a complete wire capture. The POST wrapper above remains the contract.

History showing saved input data, headers with sensitive information omitted, and the server response.

Select Open conversation and compare the returned fields with the reply. The successful local lookup took 17 ms for HTTP and 26 ms total; a synthetic local lookup is not representative of a production provider’s latency. When finished, set the demo action to Off, then stop the host server with Ctrl+C or the named Docker container with docker stop visito-order-status-docs. Retain history for diagnosis. Before production, add customer authorization, real source data, restricted responses, and tested failure/routing behavior. No production endpoint was deployed by this demonstration.

Build With Visito

AI Coding Assistants

Build an order-status action endpoint

Run the example

Follow the request through the server

1. Check the route and authentication

2. Read a bounded JSON body

3. Extract the parameter

4. Look up and return the record

5. Let Visito use the result

Check the request and response

Make the endpoint reachable

Test the saved definition

Inspect and clean up

​Run the example

​Follow the request through the server

​1. Check the route and authentication

​2. Read a bounded JSON body

​3. Extract the parameter

​4. Look up and return the record

​5. Let Visito use the result

​Check the request and response

​Make the endpoint reachable

​Test the saved definition

​Inspect and clean up

Run the example

Follow the request through the server

1. Check the route and authentication

2. Read a bounded JSON body

3. Extract the parameter

4. Look up and return the record

5. Let Visito use the result

Check the request and response

Make the endpoint reachable

Test the saved definition

Inspect and clean up