Connect your own API system

Use a custom API system when your agent needs current information or an operation from software you control: find a customer, check an order, or create a lead. The connector groups the system’s actions; its connection holds the shared base URL and authentication. You need administrator access, a reachable HTTPS API, and the credentials it requires. Creating a connector does not create a server or give Visito direct database access.

1. Add your system

Open Connectors → Add your own system → API-based. The Add your system modal contains the shared connection and all the actions you want to create now.

API-based and Visito-hosted choices under Add your own system.

Give the system a recognizable name such as My CRM and, optionally, a description. This name becomes its entry in Installed.

2. Configure the shared connection once

Setting	Example or meaning
API base URL	`https://api.example.com/v1/` — the shared HTTPS origin and path prefix
Authentication	None, Bearer, or API key, as required by your API
Secret	The endpoint credential; for Bearer, omit the `Bearer` prefix
API key header	The exact header name your endpoint expects, such as `X-API-Key`

The API base URL and Bearer credential shared by the system's actions.

The connection is created as Primary. All actions in this setup use it. Keep credentials here, rather than in AI instructions or the input schema. A Visito API key authenticates calls to Visito; use your external system’s credential for this connection. To edit the shared settings, open the saved connector’s Connections tab and click Primary. The right drawer lets you change its base URL, authentication, credential, and enabled state. Leave the secret blank to keep the saved credential. Changes apply to actions using this connection. To add another system, return to Connectors → Add your own system.

3. Define one or more actions

Each action describes one operation. Select Add action to add another in the same modal; you can create 1–20 at once. Expand an action to edit its settings.

Shared by the connection	Set separately on each action
API base URL and authentication	Name and AI usage instructions
Credential and API key header	GET or POST, relative path, request options, and timeout
Connection availability	Input schema, business scope, Read only, and mode

For a customer lookup, use:

Field	Example
Action name	Find customer
Method	GET
Relative path	`customers/search`
Timeout (ms)	8000
Read only	Selected

The resulting endpoint is https://api.example.com/v1/customers/search. Enter a path relative to the base URL, rather than another full URL.

Explain when and how the AI should use it

Write instructions that cover intent, missing inputs, confirmation, and the returned result. For example:

Use when a customer asks about their account. Search using their email address;
ask for it if missing. Explain only the details returned by the CRM.
If no customer is found, ask them to verify the email.
If the request fails, say the account could not be checked.

A second action, Create lead, could use POST with path leads. Its instructions should ask for the required details, obtain confirmation before requesting a follow-up, and confirm success only when the CRM returns a lead ID.

Define the inputs

In Parameters (JSON Schema), define the information the agent must supply. Use clear types, descriptions, formats, and required fields:

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "Customer email address."
    }
  },
  "required": ["email"],
  "additionalProperties": false
}

The agent can reuse details already shared and ask for missing values. Your API must also validate the inputs and enforce record access. Return concise, customer-safe facts that the agent can explain.

Choose how inputs are sent

GET sends inputs as query parameters. For POST, expand Request options → Request body:

Option	Use when
Inputs and Visito context (default)	Your endpoint reads `arguments` and optionally uses the conversation `meta`
Inputs as direct JSON	Your endpoint expects the input fields at the top level

Default body, with an example email input:

{
  "arguments": { "email": "guest@example.com" },
  "meta": {
    "tenantId": "workspace_example",
    "conversationKey": "conversation_example",
    "conversationId": "conversation_example",
    "channel": "whatsapp",
    "eventId": "event_example"
  }
}

The default body wraps inputs in arguments and includes conversation context.

Direct JSON body for the same input:

{ "email": "guest@example.com" }

Direct JSON selected, with an example of the transmitted body.

Context values vary by conversation; direct action tests use test context. The input schema defines the input object, not an arbitrary body template. If your provider needs additional transformation, rotating OAuth, or several API calls, provide an adapter endpoint. For a dynamic path such as customers/{customerId}, add customerId to URL path parameters (optional) and make it a required scalar input in the schema. Separate multiple parameter names with commas. Use each placeholder as a complete path segment. Visito encodes the value into that segment and removes it from the remaining query or body inputs.

Set scope, Read only, and mode

Choose the businesses where the operation belongs. Use All businesses only when the same data and behavior apply throughout the workspace. Read only means the action retrieves information without changing data. Select it for Find customer or Check order status. Leave it unchecked for Create lead, changing a booking, deleting a record, or sending a message. This is a declaration of the operation’s behavior; it does not prevent your server from making changes. Your API must enforce that behavior.

Per-action schema, business scope, Read only explanation, and Playground-only mode.

New actions start in Playground only. Off prevents new agent calls; Active makes the action available in eligible customer conversations and Playground. Each action can use a different mode.

4. Save the system

Review the shared connection and each action, then select Create system. The connector, its connection, and its initial actions are saved together. If validation fails, correct the highlighted settings and retry.

Two actions grouped under one shared connection before creation.

You land on the new system’s Actions tab, and the system appears once in Installed. Select Add action here to create another action within the same connector. The shared connection is selected automatically when it is the sole enabled connection. Older setups with several saved connections retain their explicit selection.

Saved CRM connector with two actions and an Add action button.

The detail page adds actions only. In Connections, click the shared connection row to open its settings in the right drawer. Use the edit icon beside the connector name to change the system name and description. New connectors are created from Connectors home.

The connector's shared Primary connection.

Clicking the shared connection opens its base URL and authentication settings in the right drawer.

Existing standalone HTTP actions retain their saved configuration. Creating a new connector does not automatically move older actions into it.

5. Test, inspect, and activate

API actions in Playground send real HTTP requests. Use synthetic records and a destination where the permitted operations are safe to test. Test a complete request, missing inputs, invalid values, no match, and a server failure. For writes, verify the actual destination record as well as the conversation. Select View activity to inspect the action’s parameters, response, status, and timing. Saved request data can differ from the complete transmitted POST wrapper; authentication is hidden or redacted. A completed request is not proof of a successful business operation. See Test and debug actions. After the conversation and destination checks pass, set the intended action to Active. Set it to Off to prevent future calls; this does not undo a request already in progress.

Order status example

Collect an order number, send it to a server, explain the result, and trace the execution.

For programmatic configuration and supported direct tests, see the Actions API. The single-modal dashboard flow does not imply that every API or MCP client has the same bulk setup operation.

Getting Started

Direct access

Work

Setup

Best Practices

Administration

1. Add your system

2. Configure the shared connection once

3. Define one or more actions

Explain when and how the AI should use it

Define the inputs

Choose how inputs are sent

Set scope, Read only, and mode

4. Save the system

5. Test, inspect, and activate

Order status example

​1. Add your system

​2. Configure the shared connection once

​3. Define one or more actions

​Explain when and how the AI should use it

​Define the inputs

​Choose how inputs are sent

​Set scope, Read only, and mode

​4. Save the system

​5. Test, inspect, and activate

Order status example

1. Add your system

2. Configure the shared connection once

3. Define one or more actions

Explain when and how the AI should use it

Define the inputs

Choose how inputs are sent

Set scope, Read only, and mode

4. Save the system

5. Test, inspect, and activate