Custom AI Tools

Custom tools let Visito call your backend when the AI needs live business data or needs to trigger an approved action. Common examples include looking up an order status, creating a support ticket, checking loyalty points, or updating a customer profile. All endpoints use the M2M base URL:

https://platform-api.visitoai.com/m2m/v1

Tool Model

A tool describes what the AI can call, the JSON input it should provide, and the HTTP endpoint Visito will invoke.

{
  "name": "get_order_status",
  "description": "Look up the latest status for a customer order.",
  "parameters": {
    "type": "object",
    "required": ["order_number"],
    "properties": {
      "order_number": {
        "type": "string",
        "description": "The customer's order number, for example A-1003."
      }
    }
  },
  "endpoint": {
    "url": "https://example.com/visito/tools/get-order-status",
    "method": "POST",
    "timeoutMs": 10000
  },
  "auth": {
    "type": "bearer",
    "value": "tool_backend_secret"
  },
  "active": true,
  "readOnly": true,
  "allowInPlayground": true,
  "propertyIds": []
}

parameters should be a JSON Schema object. Visito uses it to decide when the tool is relevant and to shape the input sent to your endpoint.

What Visito Sends to Your Endpoint

For a GET tool, Visito converts tool arguments into query parameters. Primitive values are sent as strings; objects and arrays are JSON-encoded.

GET /visito/tools/get-order-status?order_number=A-1003
Accept: application/json

For a POST tool, Visito sends the arguments together with conversation metadata:

{
  "arguments": {
    "order_number": "A-1003"
  },
  "meta": {
    "tenantId": "tenant_123",
    "conversationKey": "tenant_123:whatsapp:525512345678:phone_number_id",
    "conversationId": "conv_123",
    "channel": "whatsapp",
    "eventId": "toolreq_123"
  }
}

Your endpoint should return a JSON object with only the fields the assistant needs. Non-object JSON responses are normalized into an object before the result is returned to the assistant. Configured authentication is added by Visito:

bearer sends Authorization: Bearer <configured secret>.
api_key sends the configured secret in auth.headerName.
Stored secrets are redacted from invocation logs and are never returned by the API.

Create a Tool

POST /m2m/v1/tools HTTP/1.1
Host: platform-api.visitoai.com
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires the tools:write scope.

{
  "name": "get_order_status",
  "description": "Look up the latest status for a customer order.",
  "parameters": {
    "type": "object",
    "required": ["order_number"],
    "properties": {
      "order_number": {
        "type": "string",
        "description": "The customer's order number."
      }
    }
  },
  "endpoint": {
    "url": "https://example.com/visito/tools/get-order-status",
    "method": "POST"
  },
  "auth": {
    "type": "api_key",
    "headerName": "X-Tool-Key",
    "value": "secret_value"
  },
  "active": true,
  "readOnly": true
}

{
  "tool": {
    "toolId": "tool_...",
    "tenantId": "tenant_...",
    "name": "get_order_status",
    "description": "Look up the latest status for a customer order.",
    "parameters": {},
    "endpoint": {
      "url": "https://example.com/visito/tools/get-order-status",
      "method": "POST"
    },
    "auth": {
      "type": "api_key",
      "headerName": "X-Tool-Key",
      "secretLastFour": "alue",
      "configured": true
    },
    "active": true,
    "readOnly": true,
    "allowInPlayground": true,
    "propertyIds": [],
    "createdAt": "2026-07-12T00:00:00.000Z",
    "updatedAt": "2026-07-12T00:00:00.000Z"
  }
}

Secrets are not returned after creation. Responses only include whether auth is configured and the last four characters when available.

Create and Update Rules

name must start with a letter or underscore, contain only letters, numbers, and underscores, and be at most 64 characters.
description is required and can be at most 2000 characters.
parameters must be a JSON Schema object. Visito sets type: "object" and additionalProperties: false when they are omitted.
endpoint.url must be an HTTP or HTTPS URL.
endpoint.method must be GET or POST.
endpoint.timeoutMs, when provided, must be an integer from 500 to 30000.
auth.type must be none, bearer, or api_key.
allowInPlayground defaults to false.
Omitting auth.value during a patch preserves the existing secret. Setting auth.type to none removes it.

List and Read Tools

GET /m2m/v1/tools HTTP/1.1
Authorization: Bearer visito_m2m_...

Requires tools:read.

{
  "tools": [
    {
      "toolId": "tool_...",
      "name": "get_order_status",
      "active": true,
      "readOnly": true
    }
  ]
}

Read one tool:

GET /m2m/v1/tools/{toolId}

Update or Delete a Tool

Update one or more fields:

PATCH /m2m/v1/tools/{toolId}
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires tools:write.

{
  "active": false,
  "endpoint": {
    "timeoutMs": 15000
  }
}

Delete a tool:

DELETE /m2m/v1/tools/{toolId}
Authorization: Bearer visito_m2m_...

{
  "ok": true,
  "toolId": "tool_...",
  "changed": true
}

Test a Tool

Use the test endpoint before enabling a tool in production conversations.

POST /m2m/v1/tools/{toolId}/test HTTP/1.1
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires tools:execute.

{
  "input": {
    "order_number": "A-1003"
  }
}

{
  "ok": true,
  "output": {
    "order_number": "A-1003",
    "status": "delivered",
    "estimated_delivery": "2026-07-10",
    "tracking_url": "https://example.com/orders/A-1003"
  },
  "durationMs": 248
}

Execution Logs

Use logs to audit AI tool calls and diagnose backend failures.

GET /m2m/v1/tools/logs?toolId=tool_...&limit=25
Authorization: Bearer visito_m2m_...

Requires tools:logs:read.

{
  "logs": [
    {
      "logId": "log_...",
      "toolId": "tool_...",
      "toolName": "get_order_status",
      "conversationId": "conv_...",
      "status": "completed",
      "method": "POST",
      "url": "https://example.com/visito/tools/get-order-status",
      "responseStatus": 200,
      "durationMs": 248,
      "startedAt": "2026-07-12T00:00:00.000Z",
      "completedAt": "2026-07-12T00:00:00.248Z"
    }
  ]
}

Read one log:

GET /m2m/v1/tools/logs/{logId}

Endpoint Requirements

Your endpoint must be reachable from Visito’s backend.
Supported methods are GET and POST.
Return JSON whenever possible.
Return a 2xx response for success. A non-2xx response is recorded as custom_tool_http_error.
Keep tool responses concise and structured for AI use.
Use readOnly: true for lookup tools that should never mutate state.
Use tool-specific auth secrets instead of broad internal credentials.
Make mutating endpoints idempotent using a business identifier from arguments or meta.eventId.
Do not rely on the assistant to hide sensitive fields returned by your endpoint; omit secrets and unnecessary personal data from the response.

Production Checklist

Create the tool with active: false.
Test representative success, validation, timeout, and upstream-failure cases.
Confirm request headers are redacted in Build → Tool calls → Logs.
Keep the response small and stable so the assistant can interpret it reliably.
Set readOnly: false for mutations and require your own authorization and idempotency checks.
Enable the tool, then review invocation logs after the first real conversations.

Build With Visito

AI Coding Assistants

Tool Model

What Visito Sends to Your Endpoint

Create a Tool

Create and Update Rules

List and Read Tools

Update or Delete a Tool

Test a Tool

Execution Logs

Endpoint Requirements

Production Checklist

​Tool Model

​What Visito Sends to Your Endpoint

​Create a Tool

​Create and Update Rules

​List and Read Tools

​Update or Delete a Tool

​Test a Tool

​Execution Logs

​Endpoint Requirements

​Production Checklist

Tool Model

What Visito Sends to Your Endpoint

Create a Tool

Create and Update Rules

List and Read Tools

Update or Delete a Tool

Test a Tool

Execution Logs

Endpoint Requirements

Production Checklist