API request

An API request lets your agent pull data from another system during the call, or write it there: a ticket in your helpdesk, a lead in your CRM, an order status from your ERP.

6:53

How it works

Every enabled API request is offered to the language model as its own tool with typed parameters. The agent recognises the situation, collects the missing details in conversation, calls the API and works with whatever comes back.

Caller  ──▶  Agent recognises the situation
             Agent asks for missing details
             Agent calls your API      ──▶  your system
                                            responds
             Agent continues speaking  ◀──

You create one under Capabilities → Tools → API request → +, in a four-step wizard.

Step 1 — Basics

All three fields are required; the wizard will not advance without them.

The last two are concatenated into one description, and that is what the language model reads. It decides whether the tool gets called at all — so be concrete, not lengthy:

What does the tool do?
Creates a ticket for a general request — not an appointment,
not a transfer.

When should it be used?
Call it as soon as name and request have been captured in full.

Step 2 — API configuration

When should the API be called?

On call start is the same mechanism as caller context, which documents it in full, including the CSV variant that needs no API of your own. For that mode a timeout of 3000 ms is recommended so the caller is not left waiting for the greeting.

Endpoint

For longer workflows raise the timeout — 5 to 15 seconds is realistic. Anything beyond that leaves the caller waiting on the line.

Step 3 — Parameters and headers

Headers

Key/value pairs for authentication and content negotiation. Empty rows are dropped on save.

Dynamic parameters (JSON Schema)

Here you describe, as a JSON Schema, which values the agent should take from the conversation. The schema defines structure, not values — the agent fills those at call time.

{
  "type": "object",
  "properties": {
    "name":    { "type": "string", "description": "The caller's full name" },
    "request": { "type": "string", "description": "What it is about, in one or two sentences" },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "description": "How urgent the matter is"
    }
  },
  "required": ["name", "request"]
}

The dialog offers ready examples (Simple fields, With options, Support ticket), validates your JSON live, and can tidy it via Format JSON.

Fixed parameters

Constant values sent on every call — API keys, tenant IDs, configuration flags:

{
  "apiKey": "your-api-key",
  "source": "phone"
}

What actually gets sent

Three sources are merged, weakest to strongest:

system variables  →  fixed parameters  →  parameters extracted by the agent
   (weakest)                                        (strongest)

On a key collision the value from the conversation always wins. URL placeholders are substituted from the same merged set.

System variables

ScaleTalk supplies these automatically — as parameters and as {{placeholders}} in the URL:

https://crm.example.com/customers/{{fromNumber}}/tickets

Empty system variables are stripped before sending.

Step 4 — Review and test

The final step summarises everything and offers a real test call:

1. Click Test — the wizard pre-fills sample values from your schema
2. Adjust them and click Run test
3. Inspect status code, response body and duration

The test runs server-side through ScaleTalk rather than from the browser, so there are no CORS problems and the call matches production. Requests to localhost and other loopback addresses are blocked, and the test timeout is capped at 30 seconds.

You can save once the name, both descriptions and the URL are set.

Limits

There is no limit on headers or parameters within a single tool.

What the agent gets on failure

Write into the prompt what should happen in these cases — otherwise the agent improvises.

Integrating with n8n

The most common setup in practice is n8n: the automation platform receives the request, processes it and answers. No server of your own, and almost every common system is already connected there.

The flow

1. In n8n add a Webhook node, method POST — it generates a URL
2. Enter that URL as the URL in ScaleTalk
3. The agent triggers the request; ScaleTalk sends the data to n8n
4. n8n processes it — create a ticket, update a CRM, append a row in Google Sheets
5. n8n responds, and the agent uses the response in the conversation

Building the workflow

A typical shape:

Webhook → prepare data → create ticket → Respond to Webhook

The last node must be Respond to Webhook, or the agent gets nothing back:

{
  "success": true,
  "ticket_id": "TK-20260218-042",
  "message": "Ticket created successfully"
}

With that the agent can say: "I've created ticket TK-20260218-042 for you."

n8n webhooks usually need no authentication — the URL itself is the secret. Treat it accordingly.

Referencing it in the prompt

Configuration alone triggers nothing. The system prompt decides when the tool is called:

### When the caller has a general question or wants a callback
### about a new topic:
1. Capture name and request in full.
2. Call the "Create ticket" tool.
3. Read the returned ticket number back to the caller.
4. If the tool fails: promise to pass the request on manually
   and end the call normally.

When it does not work

For debugging, a request inspector like webhook.site makes a good temporary endpoint — you see exactly what ScaleTalk sends.