API tools

API tools let the brand's AI fetch real-time data from external systems, making responses more accurate and personalized. Unlike the brand's stored knowledge — files, articles and Q&A pairs — an API tool can reach live information like account details, order status, or user preferences.

Where API tools live

Open Brand → (your brand) → Knowledge. The tools sit in the API tools group, described as Endpoints Yaplet calls while answering, for live data like an order status. The group header counts them and shows how many are active (for example 3 tools · 2 active). Add one with Add knowledge → API tool.

Each row shows the tool's name, its method (GET or POST) and the beginning of its description (hover to read all of it). A switch on the row pauses or resumes the tool (its hint reads Pause or Enable); colleagues who cannot manage sources see an Active or Paused badge instead. The row's ⋯ menu offers Edit and Delete. Once the brand has more than ten tools, a search box and an Active / Paused filter appear above the list.

Tools belong to the brand, alongside the rest of its knowledge. Creating, editing, pausing and deleting one all require the Content sources permission — the same one that covers the rest of the brand's AI knowledge.

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
API tools are perfect for:
  • Account information (subscription details, usage limits)
  • Order status and tracking
  • Product availability and pricing
  • User preferences and settings
  • Live inventory data
Tools per brand: the free plan allows 1 API tool per brand, and paid plans allow up to 20 per brand. The allowance counts every tool the brand holds, paused ones included. See Free plan limits for the full breakdown.

Creating Your First API Tool

Basic Configuration

The Add an API tool window (Edit API tool when you edit one) has four tabs — General, User inputs, API connection and Settings — and a Test endpoint button at the far end of its footer. Start with the General tab, which holds the basics that define your tool:

Tool name

  • A unique identifier, which cannot be changed once the tool is saved — 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, and what it must not be used for
  • The tools list shows the beginning of this text beside the tool's name, 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. An accordion called Tips for writing a good description sits above the field.
  • Keep it about that decision. A one-line hint about the reply is fine, but rules about how to present what comes back belong in Response instructions below — the AI reads the description on every turn, whether or not it calls the tool.
  • 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 instructions Optional

  • Rules for presenting what the endpoint returns: which fields to quote and which to leave out, what each status code means, when to hand the conversation to a person.
  • The AI receives this text together with a successful API response, never as part of the tool description. Presentation rules therefore cost nothing on the turns where the tool is not called, and they arrive right next to the data they describe.
  • It applies everywhere the tool runs: a call made during a chat, the answer written after a visitor submits the tool's form, and a call made during a phone call.
  • When a call fails, the When the call fails settings on the Settings tab apply instead and these instructions are not used.
  • Leave it empty and the AI simply answers from the response.
  • Example: "Quote statusText word for word. Decide from statusCode: SHIPPED means handed to the courier, ON_HOLD means hand off to a human. Never invent a delivery date."

Response format

Choose how the tool's response is presented in the chat, with the Response format field on the General tab:

Text Default

  • Yaplet reads the response and answers in its own words. Use this for account details, order status, availability checks — anything Yaplet 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:

Card fieldAlso accepts
titlename, product_name, label
pricesale_price, amount, cost
imageimage_url, image_link, imageUrl, thumbnail, photo
urllink, href, product_url, permalink
descriptionsummary, subtitle, desc

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.

The AI decides which products to show. It only turns the results that are relevant to the question into cards — so a tool that returns ten matches may show just the two the visitor actually asked about, alongside a short written reply. Cards appear in the chat widget and in the agent's inbox view; on voice calls and social channels (Facebook/Instagram) the products are described in text instead.

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

Input fields

On the User inputs tab, press Add input field to add interactive forms that collect user input before calling your API. Each field has arrow buttons to move it up or down and a bin icon to remove it:

Field Types

  • Text: Single-line input (can have dropdown options)
  • E-mail address: An email address
  • Number: Numeric input (can have predefined options)
  • Boolean (Yes/No): Yes/No questions with custom labels (Label for yes and Label for no)

Field Configuration

  • Field key (snake_case): Variable name for API calls — letters, numbers and underscores only (order_id and orderId are both fine), and unique within the tool. Four keys are not allowed: visitor_id, external_id, fb_id and insta_id. They are facts about the visitor that the visitor cannot type in themselves, so every request always uses the visitor's own value for them — a field with one of these keys is refused on save
  • Question for User: What the user sees
  • Description for Yaplet: Guidance for when to prefill values
  • Required field: Whether user must provide this information

Field key, Question for User and Description for Yaplet 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 field 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.

Options (for dropdown) For text and number fields, press Add option to provide dropdown choices:

  • Display label: What users see (e.g., "Premium Plan")
  • API value: What gets sent to your API (e.g., "premium_plan")
  • Allow multiple selection: Allow users to pick multiple options

Every option needs both a display label and an API value — an option with either one left blank also prevents saving.

How It Works: When Yaplet calls your tool, it shows a form to the user. Yaplet can prefill values based on the conversation, then the user submits their information before the API call proceeds.Every value is checked against its field before your API is called, whether the AI filled it in or the visitor sent the form: an email field needs an email address, a number field a number, a yes/no field yes or no, and a field with choices one of its choices. If a value does not fit, your API is not called, and the AI asks the visitor for the right value in the chat instead.

When to show the form

Control when forms are shown to users versus automatically submitted based on AI-prefilled values. The When to show the form field sits at the top of the User inputs tab, once the tool has an input field:

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
Prefilling: The AI analyzes the conversation to intelligently prefill form fields. For example, if a user mentions "my order #12345", the AI can prefill an order_id field automatically. The AI also knows the visitor's current date, weekday and local time, so it can turn "tomorrow" or "next weekend" into real dates — say in the field's description which format your API expects, for example YYYY-MM-DD.
A form can be sent once, and it expires. Only a form the AI showed in that chat is accepted, and only once. A late or repeated submit gets the chat message "This form has expired. Please ask your question again." (in the widget's language), and the visitor simply asks again.

API connection

On the API connection tab, configure how your tool connects to external systems:

API endpoint

  • Your API endpoint URL. It must start with https://: the request carries the Signature header and the visitor's details, which must never travel unencrypted. Any other address is refused on save with "The endpoint URL must start with https:// - API tools only call secure addresses."
  • 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. The API connection tab lists them under Available Fields for Interpolation, and a small arrow beside each header and body value inserts one for you.

VariableWhat it holds
{{ visitor_id }}Yaplet's own ID for this visitor
{{ external_id }}Your system's user ID, set by Yaplet.identify()
{{ name }}Visitor's name
{{ email }}Visitor's email address
{{ plan }}Subscription plan, set by Yaplet.identify()
{{ value }}Account value, set by Yaplet.identify()
{{ phone }}Phone number — always set for voice callers, otherwise only if captured
{{ fb_id }} / {{ insta_id }}Facebook / Instagram user ID (those channels only)
{{ country }} / {{ city }} / {{ continent }}Where the visitor is
{{ last_url }}The page the visitor is on right now
{{ session_count }}How many times this visitor has visited
{{ first_seen }} / {{ last_seen }}Date and time, ISO 8601 format
{{ device_type }} / {{ browser }} / {{ os }}Device details

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.

external_id is verified.Yaplet.identify() only succeeds when it carries a signature your server produced with your widget's identity secret, and that signature covers the user ID. {{ external_id }} therefore proves which of your users the visitor is — a visitor cannot forge it. This is what makes it safe for a tool to return account-specific data, as long as the lookup is keyed on {{ external_id }}. The secret is at Brand → (your brand) → Chat widget → Install.Values the AI fills in, and anything a visitor types into the tool's form, only fill the tool's own input fields. They can never replace {{ visitor_id }}, {{ external_id }}, {{ fb_id }} or {{ insta_id }} — so even a visitor who asks the AI to look up someone else's account still sends their own signed user ID. Facts a visitor can type anyway, such as email, still work as input fields: a tool that asks for an email address gets the one given in the conversation.
Everything else is not. The signature covers only the user ID. The other fields an identify() call carries (name, email, plan, value, custom data) and an email a visitor types into the chat themselves all arrive from the browser and could be altered by the visitor. Key your lookups on {{ external_id }} rather than on an email address or a custom field when the answer must never reach the wrong person.

HTTP method

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

Custom headers

  • Press Add header to add authentication headers, content types, or API keys
  • Use interpolation for dynamic values

Request body (POST only)

  • Press Add field to add 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 — and no fallback, 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.

Fallback values: to send a default instead, write it after a pipe (|): {{ order_id | none }} sends none when order_id has no value. In the URL, the fallback is percent-encoded like any other value.

Authentication & Security

Secure Authentication Every request includes a Signature header containing the SHA-256 hash of your secret key. You set the Secret key on the API connection tab, and Generate fills in a new one for you. Your server should verify the header 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" });
}

Call ID header Every request also carries an X-Yaplet-Call-Id header with a unique ID for that one call: the AI's tool call, the submit of the tool's form, the Test endpoint button, and a workflow's Call an API step. A retry of the same call sends the same ID, so your server can remember the IDs it has handled and ignore a duplicate. This matters most for tools that change data.

Secret Key Management

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

Redirects

If your endpoint answers with a redirect, the call follows it. When the redirect leads to a different host, or from https to plain http, the request continues without its body and without any header that looks like a credential: Authorization, Cookie, the Signature header, and any header whose name has a part such as Key, Token, Secret, Auth, Pass or Access (for example X-Api-Key or X-Shop-Token). They are not added back later, even if a further redirect returns to your host. An upgrade from http to https, or a different port on the same host, keeps everything. The safest setup is to point the tool straight at the final address.

Reliability Settings

These settings are on the tool's Settings tab.

This call

Tells Yaplet whether a call that failed may safely be sent again:

  • Reads data — a lookup, such as order status, prices or availability. A failed call may be retried.
  • Changes data — the call creates or changes something, for example cancels an order or changes an address. It is never retried, not even after a failure, so one request can never run twice. The Retries field is hidden for it.

Tools made before this choice existed open as Reads data and keep their retry count.

SettingWhat it does
Timeout (ms)How long Yaplet waits for your API's answer, in milliseconds: 1000 to 30000, default 5000. A slower answer counts as a failed call.
RetriesReads data only. When a call fails (no answer in time, an error answer or no connection), Yaplet sends it again right away this many times. 0 = one try only, at most 5. Each try gets the full timeout.
Rate limit per minuteTotal for this tool, all visitors together, at most 100. 0 uses the standard limit of 60 calls a minute.
Calls per visitor per hourHow many times one visitor may make Yaplet call this tool in an hour. 0 = no limit, at most 1000.
When a visitor's hourly calls are used up, the tool is not called and its form is not shown either: the tool's On failure handling applies instead. A signed-in (identified) visitor is counted by their user ID, so a fresh browser session does not reset the count.

Who can use this tool

Switch on Only for identified visitors for a tool that reads or changes one user's own account, such as their orders or subscription. It is off by default, and nothing changes until you switch it on.

  • Identified visitors are visitors in your website chat widget whom your site signed in through Yaplet.identify, with a signature made from the widget's identity secret (Brand → Chat widget → Install tab → Identity verification). Facebook, Instagram, email and phone visitors never count, because a sender or a phone number can be faked. Setup: Identity Verification.
  • Everyone else: your API is not called. Instead, the AI tells the visitor your brand's sign-in text, in its own words and in the visitor's language. You write that text in the Message to unidentified visitors field, under How visitors get identified on the Answers page of Brand → AI agent (see Answers). Left empty, the AI uses the standard sentence "To use this, please sign in to your account on our website and open the chat from there, then ask again." The AI still knows the tool exists, so the visitor learns that signing in unlocks it. On a phone call the voice agent says that text.

The help card beside the switch shows your brand's current text, with an Edit this text link and a link to the identity secret.

Only the user ID is verified, so let your server look users up by {{ external_id }}. When the switch is on but the address, headers and body never use {{ external_id }}, the editor warns that the tool never sends it, so your server cannot tell which user is calling.

Editing an existing tool

Editing a tool needs the same Content sources permission as creating one, and every edit is checked exactly the same way — the name rules, the https:// address, the input field keys, the timeout, the retry count and the rate limit are all validated and clamped on save.

With the Yaplet assistant or a connected AI app

The Yaplet assistant and AI apps connected to Yaplet through the MCP server (Claude Desktop, Cursor, VS Code and others) can also create, change and delete API tools, under the same Content sources permission and the same checks as the dashboard. A few things work differently there, so that your codes never pass through the AI:

  • The Secret Key is never shown back. If the AI creates a tool without one, a key is generated for you — read it at Brand → (your brand) → Knowledge → API tools → (the tool) and set your endpoint to check it.
  • Custom Header values read as "(set)". The AI sees which headers have a value, never the value itself. When it saves the tool, a header left at "(set)" keeps its stored value.
  • Moving a tool to another server needs new codes. If the AI changes the endpoint to a different host, the change is refused unless it also sends a new Secret Key and a new value for every stored header, so your old codes never reach the new server. Changing the address in the dashboard works as usual.
  • Deleting needs the tool's exact name as confirmation.

See Chatbot Tools for what the AI connection can do with your brand's AI agent.

When the call fails

On the Settings tab, the When the call fails section defines what happens when API calls fail. Choose it in the On failure field:

Failure actions

Show custom message to user Display a user-friendly message when the API is unavailable. You write it in Message to show user.

Request human agent with message Escalate to human support with a custom message, written in Message before requesting agent. 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 to user.

Try to answer with 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:

  • No AI agent needed. Your API tools (and your workflows that can run on the phone) are offered to the brand's phone agent whether or not the brand also has an AI agent.
  • 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.
  • Same timeout. A tool on a call uses its own Timeout (ms) setting (default 5 seconds), exactly as in the widget. While it runs, the phone agent keeps listening and talking: it says a very short line, in the language being spoken, that it is still on it.
  • Request human agent with message behaves like Show custom message to user. 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

A failed Reads data call is retried up to your Retries setting; a Changes data call is never retried. When the last attempt fails too, your failure action runs. A call counts as failed when:

  • It times out, or a network error occurs
  • Your API returns an error (4xx/5xx)
  • The response can't be read — for example, it says it is JSON but isn't
  • The response is larger than 5 MB

Testing Your Tools

Before going live, thoroughly test your API tools:

Test endpoint button

  • Click Test endpoint at the far end of the window's footer to validate your configuration. It stays grayed out until the API endpoint and the Secret key are filled in
  • For tools with input fields, an Enter test values window asks for test values; press Run test
  • View the actual API response, shown in an API response window, 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

API Design: Structure your API responses for easy AI processing. Use consistent JSON formats with clear field names.
Error Messages: Provide descriptive error responses. The AI can relay these messages to users when tools fail.
Rate Limiting: Protect your API with rate limiting on your own server, so a busy period cannot overwhelm it.
Monitoring: Regularly check tool performance and usage patterns in your analytics.
Security First: Never include sensitive data in URLs or logs. Use POST bodies for sensitive information and ensure proper server-side validation.

Advanced Usage

Automatic hand-off to a person

Your API can programmatically request human agent assistance by including special flags in the response. The API connection tab carries a reminder of this under the same title:

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
Automatic Escalation: When request_agent: true is detected, the system immediately requests a human agent, bypassing normal failure handling logic.

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. Put the rules for that transformation in the tool's Response instructions, not in its description, so they reach the AI only when there is a response to transform.

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.

© 2026 Yaplet. All rights reserved.