Skip to main content

Connect external APIs with custom tools

Use Custom Tools to let an Assistant call approved HTTP endpoints during conversations.

When to use Custom Tools​

Custom Tools are best for actions that require live system data, such as:

  • Order lookup
  • Subscription checks
  • Ticket or CRM status reads
  • Internal entitlement checks

Create a Custom Tool​

  1. Open OXVO Assistant → Tools.
  2. Select Add new.
  3. Set a clear tool name and description.
  4. Enter a public HTTPS endpoint.
  5. Choose request method (GET or POST).
  6. Configure authentication.
  7. Define input parameters and save.

Authentication options​

Choose the auth mode that matches your API:

  • None
  • Bearer token
  • Basic auth
  • API key

You can enable or disable a tool at any time without deleting it.

Request and response templates​

Custom Tools support templating for dynamic requests and structured outputs:

  • Request template: Build JSON payloads from tool parameters.
  • Response template: Normalize API responses into AI-friendly text.
  • Parameter schema: Define field names, required flags, and data types.

Tip: Keep tool descriptions explicit so the Assistant knows exactly when to call each tool.

Security and network constraints​

OXVO enforces safety checks before requests are sent:

  • Endpoint must use https://.
  • Localhost, private networks, and internal addresses are blocked.
  • Oversized responses are rejected.

OXVO also attaches metadata headers for request context, including account, assistant, conversation, and contact identifiers.

Operational best practices​

  • Prefer read-only endpoints for first rollout.
  • Add strict server-side validation on your API.
  • Return predictable JSON for easier response templating.
  • Log every tool request in your backend for audits.

📷 Image (optional): Custom Tool form with auth and parameters
Why: Shows the exact fields required to define endpoint, authentication, and parameter schema in one place.
File: docs/images/custom-tool-form-auth-params.png
AI prompt: "Clean product documentation screenshot of OXVO Assistant Tools create form showing fields for title, description, HTTPS endpoint URL, HTTP method dropdown, authentication type selector (none, bearer, basic, api key), parameter rows, and request/response template sections; modern SaaS product UI, neutral background, crisp readable text, OXVO branding only, no personal data, 1600x1000."