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:
- Make direct API calls for static data (no user input required)
- Show forms to collect additional information from users before making API calls
- Use visitor data automatically (name, email, plan, etc.)
- Handle failures gracefully with fallback strategies
- Account information (subscription details, usage limits)
- Order status and tracking
- Product availability and pricing
- User preferences and settings
- Live inventory data
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_orderandGet_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 field | Also accepts |
|---|---|
title | name, product_name, label |
price | sale_price, amount, cost |
image | image_url, image_link, imageUrl, thumbnail, photo |
url | link, href, product_url, permalink |
description | summary, 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.
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_idandorderIdare both fine), and unique within the tool. Four keys are not allowed:visitor_id,external_id,fb_idandinsta_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.
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
YYYY-MM-DD.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 theSignatureheader 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 }}
- Visitor data:
- 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.
| Variable | What 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.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 whenorder_idhas 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.
| Setting | What 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. |
| Retries | Reads 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 minute | Total for this tool, all visitors together, at most 100. 0 uses the standard limit of 60 calls a minute. |
| Calls per visitor per hour | How many times one visitor may make Yaplet call this tool in an hour. 0 = no limit, at most 1000. |
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.
{{ 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
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
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.