API calls

An API call action gives the agent a tool that calls an HTTP endpoint of yours — an order lookup, a stock check, an appointment search. The agent decides when to call it from the description you write, fills in the parameters from the conversation, and answers from the response. Add one on the agent’s Actions page with Add action → API call. It is one of several action types.

Fields

Field	What it is
Tool name	What the agent calls the tool, e.g. `look_up_order`. 3–40 characters of lowercase letters, digits and underscores, starting with a letter, and not one of the reserved names.
When should the agent call this?	The description the agent reads to decide when to use it. Required, up to 500 characters. Be specific: “When the customer asks where their order is and gives an order number.”
Method	`GET`, `POST`, `PUT`, `PATCH` or `DELETE`.
URL	Must be `https`. Parameters go in as `{{name}}`, URL-encoded: `https://api.example.com/orders/{{order_number}}`
Params the agent fills in	Each one has a key, a description, and whether it is required. The agent will not call the tool without the required ones. Up to 10.
Request body	For `POST`, `PUT` and `PATCH`. `{{name}}` placeholders are filled in as-is, and it is sent as `application/json`. Up to 4,000 characters.
Response fields	Optional. Dotted paths into the JSON response, such as `data.url` or `items.0.name`, up to 10. When you list any, the agent gets only those values instead of the whole response.
Authentication	None, Bearer token, or X-Api-Key header, using a saved API key.
Channels	Which of voice, chat and email the action is available on.

Every {{placeholder}} in the URL or body must be a declared param; saving fails otherwise.

Example

A GET order lookup:

URL      https://api.example.com/orders/{{order_number}}
Params   order_number — "The customer's order number, e.g. 10482" (required)
Auth     Bearer token

When a customer asks “where is order 10482?”, the agent calls:

GET /orders/10482 HTTP/1.1
Host: api.example.com
Authorization: Bearer <your saved credential>

The agent gets back the HTTP status code and the response body, and answers from them.

Keep the response to what the agent needs

Some APIs answer with more than the agent should see: an access token, internal ids, or details of other customers. List Response fields and the agent gets only those values, by path into the JSON:

Response fields   data.claim_url, data.expires_at

{ "status": 201, "fields": { "data.claim_url": "https://…", "data.expires_at": "2026-10-20T…" } }

The rest of the response never reaches the agent or the Action log. A path that isn’t in the response is left out. If the response isn’t JSON, the agent is told so and gets no fields.

Example: build a visitor their own trial agent

If you sell to businesses, such as an agency or a software company, your agent can build a visitor a working agent from their website in the middle of a chat, and give them a link where they try it and claim it free. The action calls the Wiredesk API:

Tool name         build_trial_agent
Method, URL       POST https://wiredesk.ai/api/v1/onboarding
Params            website_url — "The visitor's business website, e.g. acme.com" (required)
Request body      {"website_url": "{{website_url}}", "agent_name": "Your company"}
Response fields   data.claim_url
Authentication    Bearer token, with a full-access API key from Developers → API keys
Channels          Chat

Then add a line to the agent’s instructions under Instructions:

When someone wants to try us, ask for their website address, call build_trial_agent with it,
and give them the data.claim_url it returns, exactly as returned, as a link.

In a Preview chat, ask “Can I try this on my own website?”, give a website, and you get the link back in a few seconds. The Action log shows the call with only data.claim_url in its result. The full recipe, with the limits, is in Agent-first onboarding.

API keys

Add the key under Authentication while setting up the action, rather than pasting it into the URL: choose Add a new key… under API key and enter a label and the secret. It is stored encrypted, never shown again, and never given to the agent — it is only attached to the request. Saved keys can be reused by other actions. They are listed under API keys on Actions › Connections, by label and last four characters, where you can delete them. If your API expects the key somewhere other than a header, put {{credential}} in the request body and the saved key is filled in there. It is never allowed in the URL. Deleting a key stops every action that uses it until you attach a new one.

Limits

Timeout: 5 seconds on a phone call, 30 seconds on chat and WhatsApp, and 15 seconds on email. On a call, the agent says a short holding line before calling.
Response size: the agent reads the first 1,500 characters of the response on a call and the first 4,000 on chat and email. Return a small JSON object with just what the agent needs, or list response fields.
Redirects are not followed. Point the URL at the final address.
Addresses: the URL must be https, use a hostname rather than an IP address, and not point at a private network or localhost. This is checked again against the actual URL after parameters are filled in.
Only the parameters you declared are filled in. The agent cannot add others.

An action can call the Wiredesk API itself, for example to build a trial agent from a visitor’s website. If the call times out or fails, the agent is told and offers to follow up or take a message, and the conversation carries on.

Designing the endpoint

Return errors the agent can say out loud: {"error": "No order 10482 — check the number on the confirmation email."}.
Treat every parameter as untrusted input from the public. The agent fills them from what a customer typed or said.
Scope the credential to read-only access on what the action needs.

Checking it works

Every call appears in the Action log under Inbox → Extra fields, with the tool name, ok or failed, how long it took, and a link to the conversation. failed means the request did not complete — a timeout, a redirect, a refused address. A response with an error status such as 404 still shows as ok, because your endpoint answered; read the conversation to see what the agent made of it. Ask your agent a question that should trigger the action, then look there.

Get started

Concepts

Agents

Knowledge

Instructions

Actions

Handoff

Integrations

Channels

Chat widget

Your workspace

Account and billing

Reference

Troubleshooting

Fields

Example

Keep the response to what the agent needs

Example: build a visitor their own trial agent

API keys

Limits

Designing the endpoint

Checking it works

​Fields

​Example

​Keep the response to what the agent needs

​Example: build a visitor their own trial agent

​API keys

​Limits

​Designing the endpoint

​Checking it works

​Related

Fields

Example

Keep the response to what the agent needs

Example: build a visitor their own trial agent

API keys

Limits

Designing the endpoint

Checking it works

Related