API tools

Where API tools live

Open Brand → (your brand) → Knowledge and choose the API tools tab in the lower half of the screen. The tab carries a count, so you can see at a glance how many the brand has.

Each row shows the tool's Name, When it is used, its Method (GET or POST), its Status — Active or Paused — and when it was Added. The row menu offers Edit, Enable or Pause, and Delete.

Tools belong to the brand, alongside the rest of its knowledge. Creating, editing, pausing and deleting one all require the Vex AI permission.

How API Tools Work

When a user asks a question, your AI analyzes the conversation and decides whether to call an API tool. If a tool is needed, the AI can:

1. Make direct API calls for static data (no user input required)
2. Show forms to collect additional information from users before making API calls
3. Use visitor data automatically (name, email, plan, etc.)
4. Handle failures gracefully with fallback strategies

Creating Your First API Tool

Basic Configuration

Start with the fundamental settings that define your tool:

Tool Name

• A unique identifier — letters, numbers, underscores and hyphens, up to 64 characters. Names are compared without regard to case, so one brand cannot have both get_order and Get_Order.
• Example: get_customer_data, check_order_status

Description

• Detailed explanation for the AI (minimum 20 characters)
• Include: what the tool does, when to use it, response format
• The tools list shows this text in a column called When it is used, because that is its real job: the AI reads it to decide when to call the tool. Describe the situation the tool is for, not the endpoint behind it.
• Example: "Fetches customer subscription details. Use when user asks about their account or plan. Returns JSON: {plan_name, billing_cycle, usage_limit, current_usage}. Format into a friendly sentence like You're on the Pro plan (monthly) and have used 45% of your limit."

Response Format

Choose how the tool's response is presented in the chat:

Text Default

• The AI reads the response and answers in its own words. Use this for account details, order status, availability checks — anything the AI should explain conversationally.

Product cards

• The response is rendered as rich, visual product cards directly in the chat — image, title, price, and a clickable link. Perfect for product search, recommendations, or "what do you sell?" questions backed by a live catalog or inventory API.

When you choose Product cards, your endpoint should return a products array:

{
    "products": [
        {
            "title": "Barista Pro Espresso Machine",
            "price": "$649.00",
            "image": "https://example.com/img/espresso-pro.jpg",
            "url": "https://example.com/products/espresso-pro",
            "description": "15-bar pump, dual boiler, PID temperature control."
        }
    ]
}

Only title is required — every other field is optional (a card with no image or price still renders). The field names are flexible, so you can usually point a tool at an existing catalog API without reshaping its output. These aliases are all accepted:

The product array can also be at the top level of the response, or under products, items, results, or data.

Give each product a stable id (or external_id, sku, or product_id) so a card keeps the same identity when the tool runs again. If none is present, Yaplet generates one automatically.

For products you upload to Yaplet directly (rather than fetch live from your own API), see AI Data and Products.

Dynamic Input Fields

Add interactive forms that collect user input before calling your API:

Field Types

• Text: Single-line input (can have dropdown options)
• Number: Numeric input (can have predefined options)
• Boolean: Yes/No questions with custom labels

Field Configuration

• Key: Variable name for API calls — letters, numbers and underscores only (order_id and orderId are both fine), and unique within the tool
• Question: What the user sees
• Description: AI guidance for when to prefill values
• Required: Whether user must provide this information

Key, Question and Description must all be filled in. A field missing any of them prevents the tool from being saved, and the error points at the field in question. (Required is a different setting — it controls whether the visitor has to answer, not whether you have to configure the field.)

If the problem is on a tab you are not currently looking at, the dialog jumps to that tab and focuses the offending field, rather than leaving the Save button looking dead.

Dropdown Options For text/numeric fields, you can provide dropdown choices:

• Label: What users see (e.g., "Premium Plan")
• Value: What gets sent to your API (e.g., "premium_plan")
• Multiple Selection: Allow users to pick multiple options

Every option needs both a Label and a Value — an option with either one left blank also prevents saving.

Form Display Mode

Control when forms are shown to users versus automatically submitted based on AI-prefilled values:

Display Mode Options

Always Show Form

• Visitors always see the form, even if the AI has prefilled some values
• Users must manually submit the form to proceed
• Best for: Critical information that users should always review

Auto-submit if Required Fields Prefilled

• Skip showing the form if all required fields are prefilled by the AI
• Show the form only when required information is missing
• Best for: Most use cases where you want efficiency but ensure required data

Auto-submit if All Fields Prefilled Default

• Skip showing the form only when ALL fields (required and optional) are prefilled
• Show the form if any field is empty
• Best for: Simple forms where you want maximum automation

Auto-submit if Any Field Prefilled

• Skip showing the form if ANY field is prefilled by the AI
• All required fields must still be prefilled to actually submit
• Best for: Identifying an order based on either email address or order ID

API Configuration

Configure how your tool connects to external systems:

Endpoint URL

• Your API endpoint URL
• Use {{ field }} syntax to include dynamic data:
  • Visitor data: {{ email }}, {{ external_id }}, {{ last_url }} — full list below
  • User input: {{ order_id }}, {{ plan_type }}
• Example: https://api.yourcompany.com/customers?id={{ external_id }}&order={{ order_id }}

Values placed in the URL are automatically percent-encoded, so a name or ID containing characters like & or ? stays a single value instead of altering the request. Headers and the request body are sent as-is.

Visitor variables

These come from the visitor's record. Anything never captured for a given visitor has no value and drops out of the request — see Empty and missing values below.

The same variable list is used everywhere: the live call the AI makes during a conversation, the call made after a visitor submits the tool's form, and the Test Endpoint button.

Your own custom fields

Anything you pass to Yaplet.identify() that isn't one of the fields above is kept as custom data and becomes available with a custom_ prefix:

Yaplet.identify(
    "user_12345",
    {
        name: "Ada Lovelace",
        customData: { order_ref: "A-4417", tier: "gold" },
    },
    userHash, // HMAC of the user ID, computed on your server
);

That gives you {{ custom_order_ref }} and {{ custom_tier }}.

Only top-level plain values (text, numbers, true/false) become variables — nested objects and lists are skipped. Up to 50 custom fields are exposed, each truncated to 512 characters.

HTTP Method

• GET for retrieving data
• POST for sending data or complex queries

Custom Headers

• Add authentication headers, content types, or API keys
• Use interpolation for dynamic values

Request Body (POST only)

• JSON key-value pairs for POST requests
• Supports the same interpolation syntax as URLs and headers

Empty and missing values

When a {{ placeholder }} has no value — an optional input field the user left blank, or a visitor field that was never set — that piece is left out of the request entirely instead of being sent as an empty string or the literal text undefined:

• URL — empty query parameters are removed. ?order={{ order_id }} simply disappears when order_id has no value.
• Headers — a header whose value resolves to empty is not sent.
• Request body — a body field that resolves to empty is omitted from the JSON.

Design your endpoint to treat these fields as optional and possibly absent. Values the user did provide — including false and 0 — are always sent.

Authentication & Security

Secure Authentication Every request includes a Signature header containing the SHA-256 hash of your secret key. Your server should verify this to authenticate requests.

// Example verification in your API
const crypto = require("crypto");
const expectedSignature = crypto.createHash("sha256").update(YOUR_SECRET_KEY).digest("hex");

if (request.headers.signature !== expectedSignature) {
    return res.status(401).json({ error: "Invalid signature" });
}

Secret Key Management

• Generate unique keys for each tool
• Rotate keys periodically for security
• Never expose keys in client-side code

Reliability Settings

Ensure your tools are resilient in production:

Timeout

• How long to wait for API responses (1,000-30,000ms)
• Default: 5,000ms

Retry Logic

• Number of retry attempts on failure (0-5)
• Uses exponential backoff

Rate Limiting

• Maximum calls per minute (0-100)
• Prevents API quota exhaustion

Editing an existing tool

Editing a tool needs the same Vex AI permission as creating one, and every edit is checked exactly the same way — the name rules, the timeout, the retry count and the rate limit are all validated and clamped on save.

Failure Handling

Define what happens when API calls fail:

Failure Actions

Show Custom Message Display a user-friendly message when the API is unavailable.

Request Human Agent Escalate to human support with a custom message. On phone calls there is no live-agent handoff — the configured message is spoken to the caller and the call continues, just like Show Custom Message.

Fallback to Other Context Continue the conversation using the brand's other knowledge.

Phone-call behavior

When an API tool runs during a voice call, a few things behave differently from the widget:

• The brand needs a Vex AI agent. On a call, your API tools (and your scripted workflows) are only offered to the voice agent if the brand also has a Vex AI. A brand with a phone agent but no Vex can still answer from the brand's knowledge, but cannot call an API tool during a call. Creating a voice agent on a brand that already has Vex links the two automatically, so most customers never meet this restriction.
• No form rendering. If the tool's input fields aren't all pre-filled, the AI asks the caller in conversation, just like Facebook/Instagram. There is no visual form to render over a phone line.
• Tighter timeout. Voice caps the API timeout at 4 seconds (the widget default is 5). Slow APIs become voice-incompatible by SLA — keep handlers fast or expect spoken filler ("One moment.") to fill the gap.
• REQUEST_AGENT degrades to SHOW_MESSAGE. Voice has no path to transfer a call to a human agent, so any failure or API-flag escalation simply speaks the configured message and lets the conversation continue.

Error Scenarios

• Network timeouts → Retry based on your settings
• API errors (4xx/5xx) → Trigger failure action
• Invalid responses → Fallback behavior
• Rate limits exceeded → Respect rate limiting settings

Testing Your Tools

Before going live, thoroughly test your API tools:

Test Endpoint Button

• Click "Test Endpoint" to validate your configuration
• For tools with input fields, provide test values
• View the actual API response to ensure correct data format
• The test builds its request from the same visitor-variable list a real call uses, so what you see here is what your endpoint will receive
• For Product cards tools, the test also confirms how many products were detected and previews the cards — a successful call that returns no recognizable products is flagged, so you catch a wrong response shape before going live

Test Scenarios

• Success cases: Valid requests returning expected data
• Error handling: Invalid inputs, timeouts, API failures
• Edge cases: Missing data, unusual responses
• Authentication: Verify signature validation works

Best Practices

Advanced Usage

Automatic Agent Request

Your API can programmatically request human agent assistance by including special flags in the response:

Triggering Agent Requests Include {"request_agent": true} in your API response when your system determines it cannot fulfill the user's request and needs human assistance.

{
    "error": "Account requires manual review",
    "request_agent": true,
    "request_agent_message": "Your account needs special attention from our support team."
}

Custom Messages Optionally include request_agent_message to specify a custom message the AI will send before connecting to an agent:

{
    "status": "requires_approval",
    "request_agent": true,
    "request_agent_message": "Your request needs approval from our team. Let me connect you with someone who can help."
}

Use Cases

• Complex account issues requiring manual review
• High-value transactions needing verification
• Technical problems beyond automated handling
• Escalation based on business rules or risk assessment

Complex Workflows

Chain multiple tools together by having the AI call different tools based on user responses and previous API results.

Conditional Logic

Design your API to handle different scenarios based on input parameters, allowing one tool to serve multiple use cases.

Data Transformation

Use the AI's natural language capabilities to transform raw API data into conversational responses.

API tools bridge the gap between the brand's stored knowledge and dynamic, real-time data, making your AI a powerful interface to your business systems. With proper configuration and testing, they can provide personalized, accurate responses that stored knowledge alone cannot achieve.