AI custom tools Planned

Define function-calling tools the AI can invoke during a chat, call, or ticket. The AI reasons about which tool to call from the function name and description, then we sign the request and call your endpoint. Use this to ground answers in your order DB, Shopify Admin, CRM, or anything else with an HTTP API.

Defining a tool

A tool is a name, a description (the model reads this to decide when to call it), a JSON schema for the args, and an HTTP endpoint you control. We never reach into your systems directly; you publish an HTTPS endpoint, we POST to it with HMAC.

// POST /api/v1/ai/tools
{
  "name": "lookup_order",
  "description": "Look up an order by number or by customer email. Use when the visitor asks about order status, tracking, or contents.",
  "endpoint": {
    "url": "https://api.acme.com/orders/lookup",
    "method": "POST",
    "auth": { "type": "bearer", "secretRef": "acme_internal_api_key" }
  },
  "schema": {
    "type": "object",
    "properties": {
      "orderNumber": { "type": "string" },
      "email": { "type": "string", "format": "email" }
    },
    "required": []
  },
  "writeScope": false,
  "requireAgentApproval": false
}

How invocation works

// Conceptual flow inside the AI turn:
// 1. Visitor: "Where's my order #4567?"
// 2. AI plans: { tool: "lookup_order", args: { orderNumber: "4567" } }
// 3. We HMAC-sign and POST to your endpoint:
POST https://api.acme.com/orders/lookup
X-Message-Signature: sha256=...
{ "orderNumber": "4567", "conversationContext": { ... } }

// 4. You respond:
{ "status": "shipped", "carrier": "UPS", "tracking": "1Z...", "eta": "2026-05-15" }

// 5. AI uses your response to compose the reply.

1. AI plans the call based on the visitor message and the tool description.
2. We validate the args against your JSON schema.
3. We HMAC-sign the body and POST to your endpoint.
4. Your endpoint responds with structured JSON.
5. AI uses your response to compose the reply (or escalate).

Authentication on your side

We support three auth types out of the box. The bearer token or basic-auth credentials are stored encrypted in our database and rotated per workspace.

• HMAC signature only. We sign the body with the per-tool secret you provide. You verify the signature.
• HMAC + Bearer token. Add an authorization header. The token is stored encrypted at rest.
• OAuth client credentials. For systems that prefer a token-refresh flow.

Read vs write

Every tool declares whether it mutates state. Read tools (lookup an order, check inventory) usually fire without confirmation. Write tools (refund, cancel, schedule) prompt for an agent approval by default. You can opt-out per tool by setting requireAgentApproval: false, but we strongly recommend keeping the human-in-the-loop for any irreversible action.

Conversation context

Every tool call includes a conversationContext object with the visitor record, current conversation ID, message excerpt, and channel. Use this to scope responses to the visitor (for example, only return orders that belong to the email on the visitor record).

Errors and retries

• Non-2xx responses are retried twice with exponential backoff.
• Timeouts default to 10 seconds; configurable per tool, max 30.
• Persistent failure puts the conversation into "tool failed" mode and AI politely escalates to a human.
• Errors surface in the conversation timeline as an internal note for the agent to see.

Pre-built tool catalogue

You do not have to start from scratch. Many common integrations ship as pre-built tool packs that the AI loads automatically once you connect the upstream service.

• Shopify Admin tools. Order lookup, inventory check, refunds, customer history. Auto-installed by the Shopify app.
• WooCommerce tools. Same surface, WP-side. Installed by the WordPress plugin.
• Stripe tools. Customer lookup, subscription status. OAuth into your Stripe account.
• Calendar tools. Availability check, booking. Google Calendar, Microsoft 365, and Cal.com supported.

Testing tools

The dashboard ships a tool playground. Type a prompt; watch the AI plan, see which tool it picks, inspect the args, see the response. Useful during development to catch bad descriptions (the most common reason a tool is never called).

Common pitfalls

• Vague descriptions. "Tool for orders" is not enough. "Look up order status, tracking, and items by order number or customer email" lets the model decide reliably.
• Schemas that are too strict. Marking everything required forces the AI to ask the visitor for inputs it could infer. Make fields optional when the backend has fallbacks.
• No HMAC verification. Always verify the signature on your endpoint. We sign every request with the per-tool secret you provided; an unsigned request is suspicious.