Chatbot tools and actions: call your own APIs

Tools & actions

Tools let IotaBot take real action by calling your own or third-party APIs. You define a tool once — its method, URL, parameters, and how the AI should use it — and the assistant invokes it automatically when a visitor's request matches. Each tool is scoped and purpose-built, so the assistant only does what you allow.

Anatomy of a tool

• Method — GET (fetch/read data) or POST (create/perform an action).
• URL template — your endpoint, with double-brace placeholders (like an orderId token) the AI fills from the conversation.
• Parameters — each declares where it goes: path, query, body, or header.
• Headers — static or secret values (e.g. an API key referenced securely, never hard-coded in the browser).

Example — GET (track an order)

A read-only lookup. The AI extracts the order number from the chat and fills the order-id path placeholder:

GET  https://yourwebsite.com/api/orders/{{orderId}}

Parameters:
  orderId   in: path     (from the conversation, e.g. "10482")

Headers:
  Authorization: Bearer <your-secret-api-key>

Example call:
  GET https://yourwebsite.com/api/orders/10482
  -> 200 { "status": "shipped", "eta": "today 6 PM" }

Example — POST (create a support request)

A write action. The AI collects values from the visitor and sends them in the request body:

POST https://yourwebsite.com/api/support/tickets

Parameters:
  email     in: body
  subject   in: body
  message   in: body

Body template:
  {
    "email":   "{{email}}",
    "subject": "{{subject}}",
    "message": "{{message}}"
  }

Example response:
  201 { "id": "SUP-3391", "status": "open" }

Placeholders take two braces on each side, as shown above, and their values are URL-encoded before the request is sent. One brace is the most common mistake: {orderId} is never substituted, so the request goes out with that text still in the path and your API answers 404. The dashboard refuses to save a tool whose placeholders and parameters do not line up.

Point tools at any base URL — your own backend (https://yourwebsite.com/api/…) or a third-party service.

Rich cards

A tool's answer does not have to be a sentence. Switch on Allow rich cards and IotaBot will design a card for that tool — your layout, your colours, your product images — and render it in the chat instead of prose.

• Paste a real response (or press Run tool now and we will call your API once and capture it). The card is built from the shape of what your API actually returns.
• The AI designs the card from that response, using your brand colour and logo.
• Refine it by chat — “show the image on the left”, “make the total bigger” — with a live preview beside it.

The values are never written by the AI. It designs the layout once, and every value is read from your API at the moment the card is sent. A card cannot show a status, a total or a tracking link your API did not return — which is exactly what you want when the card is telling a customer where their order is.

Card buttons

A card can carry up to three kinds of button:

• Link — opens a URL from your data in a new tab. Only rendered when your API actually returns one.
• Message — puts text into the chat as if the visitor typed it (e.g. Cancel order 10482), so the assistant picks it up and carries on.
• Postback — sends a value to the assistant silently, without the visitor seeing it. Useful for confirmations.

Card markup is sanitised before it is ever shown, and each card renders in its own isolated container, so its styling cannot affect your page and nothing in it can execute.

Cards appear in the chat widget. On WhatsApp, Instagram and email — which cannot render them — the assistant's written answer is sent instead.