Custom actions

A chatbot API integration that books, orders and confirms first

Point an action at your booking or order API and the AI gathers the details, can read them back for a yes, makes the call and sends back what your system returns, like a return label.

  • GET, POST, PUT, PATCH or DELETE with bearer, API key or basic auth
  • Requires approval holds the call until the customer says yes
  • PDFs and images from your API arrive as chat attachments
  • Google Sheets, Docs, Meet and Send email built in
Start an exchange
create_exchange
HTTP request
POSThttps://api.yourstore.com/orders/{{order_id}}/exchange
order_id string · requirednew_size string · required
Requires approvalThe AI will pause and ask the user to confirm before executing.
I can swap order #5132 for the 12 inch Sage planter. Shall I go ahead?
AI · 02:18 PM ✓✓
Yes please
02:18 PM
Done. Your exchange is booked and the return label is attached.
return-label-5132.pdf
AI · 02:19 PM ✓✓

A yes only covers the values it was given

With Requires approval on, the AI reads the booking back, say a cleaning on Thu, Oct 8 at 3:00 PM, and parks the call. A plain yes runs it with exactly those values. “Yes, but make it 4:30” drops the pending booking and confirms the new time from scratch, and a side question gets the confirmation asked again rather than lost.

Details the channel already has are filled in

A parameter can be auto-filled from the conversation, such as Customer phone on WhatsApp, Customer name or Detected language, or from a verified web chat login. When the channel supplies the value, that value is used and can't be changed from the chat, so nobody talks the AI into booking under another number. Turn on “Ask the user if the channel can't provide it” and web chat visitors, who have no sender phone, are asked for one.

Your API's reply is trimmed before the AI reads it

Data access can be Full or Limited, with allow and deny paths, so fields like internal notes or insurance member IDs never reach the model. Anything over the size cap you pick, from 5 KB to 1 MB, is cut before the AI reads it. With Send it as a file set, a PDF or image your API returns goes to the customer as an attachment and never passes through the AI.

Two actions behind one booked cleaning

In this example, Alex K. asks a dental clinic on WhatsApp about Delta Dental and picks a time for a cleaning. This is what the clinic set up so the AI could do that.

  1. Write the cue in When to use

    get_open_slots gets the line “Use when a patient wants to book or move a visit and needs open times.” That text becomes the AI's description of the tool, so it is how the AI decides when to run the action. The display name turns into the machine name the AI calls, in snake case.

  2. Read open times from the clinic's system

    get_open_slots is a GET to the clinic's scheduling API with {{date}} in the URL and a bearer token kept as an encrypted secret. Its Response kind is List, so each open time comes back as its own option, and the AI offers Thu, Oct 8 at 3:00 PM or Fri, Oct 9 at 10:30 AM instead of guessing at the list.

  3. Carry the chosen slot into the booking

    book_appointment lists get_open_slots as a prerequisite with Require fresh data on, so if the open times are more than 10 minutes old the AI has to fetch them again before it can book. It books the slot ID of the time Alex chose from that list, and Alex's phone number is auto-filled from WhatsApp, so the AI never has to ask for it.

  4. Ask, book and keep a record

    Requires approval is on, so the AI asks “Shall I go ahead?” and books only after a yes. Every call lands in the action's history with its inputs, the response and a status: Success, Failed, Timeout, Denied or Awaiting approval.

Actions on this bot
get_open_slotsGEThttps://api.yourclinic.com/slots?date={{date}}
book_appointmentPOSThttps://api.yourclinic.com/appointmentsRequires approval
Alex K.WhatsApp
Do you take Delta Dental? I'm overdue for a cleaning.
01:10 PM
Yes, we're in-network with Delta Dental PPO. I have Thu, Oct 8 at 3:00 PM or Fri, Oct 9 at 10:30 AM. Which works better? [Source: Insurance and fees]
AI · 01:11 PM ✓✓
Thursday at 3 works
01:13 PM
I'll book a cleaning for Thu, Oct 8 at 3:00 PM. Shall I go ahead?
AI · 01:13 PM ✓✓
Slots and bookings come from the clinic's own scheduling system, through actions set up during onboarding.

Custom action settings: request, auth, parameters and limits

What you set on a bot's Actions tab, using the labels from the app.

Custom actionsIn the Risolva app
Configuration type
HTTP request, which calls any REST endpoint you configure, or Provider operation: Google Sheets, Docs or Meet on a connected Google account, or Send email, which needs no account
Request
GET, POST, PUT, PATCH or DELETE to a URL template such as https://api.yourclinic.com/slots?date={{date}}, plus headers, query parameters and, for POST, PUT and PATCH, a JSON body template. Public addresses only: private networks and localhost are blocked.
Authentication and secrets
No auth, Bearer, ApiKey (an X-API-Key header) or Basic. Secrets are referenced as {{secret:token}}, encrypted at rest, and write-only once saved.
Parameters
Types string, integer, number or boolean, required or optional, with allowed values, min and max length, a format such as email address or date, a pattern, or a minimum and maximum. Each is supplied by the AI, auto-filled, or given a default.
Behavior
Requires approval; Signed-in user only (web chat visitors your site verified with a signed JWT or HMAC user hash); Runs in host page (the call runs in the visitor's browser through Risolva.registerTools())
Runtime and usage limits
Timeout from 1 to 120 seconds (15 by default), Max response size from 5 KB to 1 MB (20 KB by default), and Max calls per conversation, where empty means unlimited and failed or timed-out calls don't count
What happens to the response
Response kind None, List, Object or Scalar; save values such as slot_id for later steps; or Send it as a file from a binary body, a base64 field or a remote URL (binary bodies and downloads are capped at 16 MB), with a filename and caption template
Send email
Sent from [email protected] to up to 5 recipients you pin, with a subject and body you write, filled in from details the AI collected. The AI can't change the address or write the message, and a workspace can send 30 recipient emails an hour.
The full guide · 4 min readCustom actions for AI chatbots: examples and safe setupWhat custom actions let an AI chatbot do in a conversation, from starting an exchange to sending a return label, with examples and the guardrails to set first.Read the guide

Before you connect your chatbot to an API

You need an endpoint on the public internet for your booking, order or account system, and the credentials to call it. The chatbot API integration itself is a form in Risolva covering the method, URL, auth, parameters and what to do with the response, so there's no code to write. Our team often builds the first action with you during onboarding.

Bring one endpoint to the demo

Book a demo and show us the booking, order or account task your team handles by hand most often. We'll sketch the action with you, from the When to use cue to the file it sends back, and point out where Requires approval belongs.