Skip to main content
Actions

Fetch live data during the call

Let the agent ask your system for an order, a stock level or an account while the caller waits.

With API Tool RAG the agent asks your system for live data in the middle of the conversation — the status of an order, the stock of a product, the details of an account — and answers with it. The agent decides when to call it, from your description.

Set it up​

  1. Add the tool

    Open the agent → Actions → Add Tool → CRM & services → API Tool RAG.

  2. Describe it and point it at your endpoint
    FieldWhat to enter
    Namee.g. Order lookup
    General ConditionWhen to use it, e.g. the customer asks about the status of an order
    API Endpoint URLe.g. https://api.yourshop.com/orders/{order_id} — {placeholders} are filled from the values the agent collects
    HTTP MethodGET, POST, PUT, DELETE or PATCH
    Execution MessageWhat the agent says while it waits, e.g. One moment, I'm checking your order
    Request Timeout (ms)How long to wait for your answer; 5000 by default
    Headers, Query ParametersOptional fixed values, e.g. your API key
  3. Say what the agent must collect

    Body Parameters Schema (JSON) lists the values the agent collects from the caller and sends — see below. If a required value is missing, the agent asks for it first.

tip

Always fill in the Execution Message — silence while the request runs sounds like a dropped call.

The Body Parameters Schema​

It is not the request body itself but a JSON Schema of the values to collect. Where they end up:

CaseWhere the value goes
The URL contains {name}Into the URL
GET, DELETEThe rest as ?key=value
POST, PUT, PATCHThe rest as a JSON body

An order lookup by number:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order number the customer asks about, usually 6 to 10 digits. Ask if not given."
    }
  },
  "required": ["order_id"]
}

A reservation with several values:

{
  "type": "object",
  "properties": {
    "product_id": { "type": "string", "description": "Product ID from a previous search." },
    "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many. Default 1." },
    "delivery_method": { "type": "string", "enum": ["pickup", "home_delivery", "locker"], "description": "How the customer wants to receive it." },
    "customer_email": { "type": "string", "format": "email", "description": "Email for the confirmation. Ask if not given." }
  },
  "required": ["product_id", "delivery_method", "customer_email"]
}

A static endpoint, e.g. opening hours: { "type": "object", "properties": {} }.

Good schemas for voice:

  • Keep it flat: 3–5 values.
  • Write a description for every value, with examples — they guide the agent best.
  • Use enum for fixed choices: the agent maps "the blue one" to blue.
  • Mark a value required only when the request cannot work without it.
  • Use snake_case names that match the {placeholders} in the URL.

Use cases​

  • Order status — "Where is my order 482913?"
  • Availability — check stock or a free table in your own system.
  • Account questions — balance, contract end, open tickets.

Common problems​

ProblemWhat to check
The agent never calls itMake the General Condition name the request
Your endpoint gets empty valuesThe names in the schema must match the {placeholders} exactly
The agent says it couldn't checkYour endpoint took longer than the timeout, or answered with an error
On this page