Custom tools & API actions
Beyond searching your catalog and knowledge base, Promptly can call your own APIs during a conversation — to fetch live data (order status, stock, availability) or to trigger an action (send a webhook). These are custom tools, and the planner can include them as steps when answering. See Multi-step reasoning.
🖼️ [Image] — A tool configuration form with the URL template, headers, input schema and response mapping fields.
What a tool can be
Each tool has a type:
- REST API — the bot makes an HTTP request to a URL you define. You supply a URL template, HTTP method, headers, and an optional body template; placeholders in those templates are filled with values the bot extracts from the conversation. You then map the response (via JSON paths) so the bot reads back only the fields it needs.
- Webhook — the bot POSTs a JSON payload to your endpoint to trigger an action. It returns the HTTP status, not data — use this for "do something" rather than "look something up".
- Internal search — the built-in catalog primitives (text search, filtering, sorting, geo search). These power product answers and don't require any setup beyond a connected catalog.
How tools are configured
A tool defines:
- Name / display name / description — the description tells the bot when to use the tool, so write it clearly.
- Input schema — a JSON schema describing the parameters, used to validate what the bot passes in.
- Response mapping — which fields from the API response the bot should read.
- Access rules — optional controls over which widget users may invoke it.
Outbound requests are validated for safety, and every call is logged with sensitive values (tokens, keys, secrets) redacted.
Plan availability
Custom tools are a Grow plan and above feature (internally
text
tool_access🎬 [Video] — A visitor asking "where's my order?" and the bot calling a REST tool to return live status.
Tips
- Write a precise description — it's the main signal the bot uses to decide when to fire the tool.
- Keep response mappings lean: return only the fields the answer needs.
- Use webhook tools for actions (create a ticket, notify a system) and REST tools for lookups.