Skip to main content
For general configuration, start with the API setup guide. This page walks through one practical example. A customer asks, “Where is my order?” The agent asks for the order number, calls your server, and explains the returned shipping status and delivery estimate. Create a custom API system to group this action and its shared connection. This walkthrough uses a temporary local server and synthetic orders. The developer guide includes the runnable server and explains its lookup code. Creating the action does not create your backend or connect directly to your database.

Choose the right connection pattern

Use Knowledge for general policies and FAQs. Use this action for facts that depend on the supplied order number and a current server lookup. Keep refunds, cancellations, and other mutations in separately authorized actions.

1. Prepare the server

Use a test workspace, administrator access, a reachable endpoint, and synthetic orders. The demonstrated server accepts POST /visito/order-status, checks a Bearer token, reads arguments.order_number, and returns one of these results: The fixtures are examples, not real deliveries. Replace dates and records when reusing the demo. The backend URL must be reachable from Visito’s server, not merely your browser. The server can run locally, but hosted Visito cannot reach a local Docker hostname. The new setup screenshots use a placeholder HTTPS host; replace it with your reachable test endpoint. See the network setup.

2. Create the action

Open Connectors → Add your own system → API-based. In Add your system, name the connector Order system and configure the shared connection before defining its action. Order system setup with a shared base URL and order lookup action. Use a clear purpose in When and how the AI should use it:

Define the information to collect

Paste this into Parameters JSON schema:
This is an input definition, not the HTTP body itself. The agent fills order_number from the conversation. required tells it the value is needed; your server must still validate the request. Order-number schema, Read only, and Playground-only mode.

Choose a mode

  • Off: unavailable to the agent.
  • Playground only: test in Playground without enabling customer channels.
  • Active: available in eligible customer conversations and Playground.
The new setup screenshots use Playground only. The conversation screenshots retain an earlier controlled local Webchat test that used Active mode. Read only describes the operation; it does not stop your server from making changes if you implement it incorrectly. Playground sends real requests to the configured endpoint, so use test data. Select Create system. The action belongs to Order system → Actions. Use Add action in that connector to create more later. When editing, leave Secret blank to retain the saved credential. For API key authentication, configure the exact header name expected by your backend. A Visito API key is for calls to Visito; it is not the credential for this sample order server. The saved action inside Order system.

3. Understand what is sent to the server

When the customer says “My order number is A-1003,” the generated action input is:
For POST, Visito puts this input inside arguments and adds conversation metadata. A representative body is:
The server reads body.arguments.order_number, validates it, looks up that key, and returns facts. The demo uses an in-memory map. In your application, that lookup would query an authorized database record or call your order provider.
Visito returns this structured tool result to the model while continuing the conversation. The model then explains the facts in natural language. The description controls when to use the action; it should not contain the current shipping status. That status comes from the server response. GET uses query parameters instead. This server expects the default POST envelope. For a different API, Request options also supports a direct JSON input object and declared path parameters such as orders/{order_number}. Make the path value a required schema input and list it in URL path parameters; do not change the body mode for this demo server. See the request contract.

See the controller

The illustration below follows the essential code in the downloadable server: extract body.arguments.order_number, validate it, look up the record, and return JSON. It is an annotated code excerpt, not a dashboard screen; the full server also handles authentication, bounded bodies, timeouts, and failures. Annotated controller excerpt showing the incoming order number, lookup, and JSON result.

4. Test the conversation

Start a new conversation in your test channel. In Playground, use Playground-only mode. For a controlled Webchat test, explicitly use Active with a synthetic backend.
  1. Ask “Where is my order? Has it shipped yet?” The agent should ask for the order number without calling the lookup with an invented number.
  2. Supply A-1003. Check that the answer says shipped, uses Demo Courier and DEMO1003, and presents October 3 as an estimate.
  3. Ask for A-9999. The agent should say it could not find that order and ask you to check the number.
  4. Ask for A-5000. The agent should explain that it could not check the status, without inventing delivery details.
English Webchat with an order-number request and the returned shipment information. Unknown-order response asking the customer to check the number. Simulated service failure and an honest response that the status could not be checked. These screenshots were captured from the local test. They do not validate production connectivity or production handoff rules. The local planner was disabled during this isolated test. Test your actual routing before release.

5. Review Activity and conversation details

Go to Connectors → Activity, select the environment and action, and open an execution. Match the timestamp and order number to your conversation. Review Parameters, Saved request data, Saved request headers, and Response. The saved request data may contain only the action arguments, not the entire transmitted POST wrapper. Do not mistake { "order_number": "A-1003" } in this panel for the complete body your endpoint must parse. Authentication details are hidden or redacted. HTTP response received means the request completed. It does not mean the order was found or delivered: inspect found and status. An unknown order can correctly return HTTP 200 with found: false. HTTP 503 represents a failed lookup, not a missing order. Expand Technical details for action and execution identifiers. Select Open conversation to follow the execution to the customer exchange. Expand the receipt next to the answer to see the outcome, integration, start time, and duration. Conversation details showing the supplied order number, completed action receipt, and answer grounded in the returned fields. The full JSON lives in Connectors → Activity; the receipt in the conversation summarizes the operation. The conversation sidebar’s History tab is a separate activity history. Depending on the channel, customers may see a compact activity label, but should receive a useful answer rather than raw diagnostic data.

6. Troubleshoot and go live

Before using real orders, your server must verify which records the requester may access. An order number or conversation metadata alone is not proof of ownership. Return only necessary customer-safe information. Keep production credentials on the server and in the shared connection’s authentication settings, never in prompts. To stop future calls, set the action to Off; that does not undo an in-flight request. At the end of the demonstration, turn it off before stopping the temporary server. Preserve the history for review. For API management and tests, use Actions and execution history. Stable HTTP IDs use http:<toolId>. Discovery, management, diagnostics, and customer-parameter access have separate scopes; existing Tools clients remain compatible. Old Developer Tools links redirect to Actions. The same lookup pattern works for stock: collect sku, return available and quantity_available, and explain the result. A stock lookup does not reserve inventory. See the current Activity filters and diagnostics.