HTTP tools: connect the agent to your API
An HTTP tool is a request the agent makes to your API during the call. The agent decides when to make it, based on the conversation. You set the address, the method, the headers and the data.
Use it to look up an order, create a support ticket or update a record in your software. This page says only what Atendia does today.
Set up with the Builder
The console Builder can create and edit an HTTP tool for this agent through a card. You review it and apply it.
- It asks what it needs and which program you already use, and proposes the easiest way to connect that works: Atendia's ready-made connection, if there is one, then Make (or n8n, if you already use it), then a direct HTTP tool.
- It reads the program's public documentation and fills in the card. The address comes from what you wrote in the conversation or from a page of that documentation. It explains how to use the tool, using the steps in this guide.
- It tests on its own, without a click, a tool that only reads (a GET request) and needs no key. It sees only a summary of the reply: its shape, the numbers and short error messages.
- It fills in the system values on its own, from a closed list: the call id, the channel, the agent id, and the date and time in the agent's time zone.
What stays with you:
- The address, when it comes neither from the conversation nor from the documentation.
- Header values and fixed values (secret fields on the card).
- The tests that need a key: you press «Try it» on the card. A request that writes data is not tried on the card; test it afterwards in «Tools», on the agent's page. Request signing stays in «Settings».
- Dynamic variables with values (Tools tab).
The request
- The address must start with
https://. Withhttp://, the request is refused when the agent tries to make it. - It only reaches public destinations. Local or private addresses are refused, and so are addresses with a user name and password.
- Redirects are not followed. If your API answers with a 3xx, the request fails. Use the final address.
- By default, Atendia sends
Accept: application/json. When there is a body, it also sendsContent-Type: application/json. You can replace both in the tool headers; write the name exactly as here, with the capitals. - The headers
Host,Content-Length,Transfer-Encoding,Connection,UpgradeandProxy-*are not accepted. - Store keys and tokens as secrets (the "Secrets" menu). They are encrypted and the console does not show them again. If your API returns the value of a secret, Atendia replaces it with
[REDACTED]before the agent reads it. - Parameters go in the query (
?name=value), in the path (/orders/{number}) or in the JSON body. A path parameter cannot change the address's domain. - A GET does not send the body. The body is always JSON.
- Each body parameter can have a position in the JSON, for example
customer.phone. Without a position, the parameter name is the key, at the top level. See "Paths". - On a request that is not GET, the «Confirm before sending» option makes the agent say the data to the caller and send the request only after the caller confirms. A new tool made by the Builder comes with it on. On a request that only looks up data, you can turn it off.
The request data
Each parameter has a value type:
LLM Prompt: the agent fills in the value from the conversation. It is the only type the agent sees.Static Value: the same value in every request. Atendia stores it encrypted. Whoever can edit the tool still sees it.Dynamic Variable: the value of a dynamic variable of the tool or of the call.- Each parameter is text, number or boolean. You can limit the allowed values and mark the parameter as required. An optional parameter with no value is not sent.
system__contact_numberis a reserved variable. Atendia fills it with the phone number of the call's contact. The agent does not choose it and cannot change it. If Atendia cannot confirm the contact, the request is not sent.
Privacy: the contact's number is personal data and goes to your API. Use it only if your API needs it and may receive it.
System variables
Atendia fills in these variables on the server. The agent does not choose or change them. Use them in a parameter of type Dynamic Variable, like system__contact_number.
system__call_id: the call identifier.system__call_channel:inbound(incoming call),outbound(call made by Atendia),widget,preview(console preview) ortest. If Atendia cannot tell the origin, the variable has no value and a required parameter fails.system__agent_id: the agent identifier.system__now: date and time in the agent time zone, ISO 8601 with the offset, for example2026-11-03T14:30:05+00:00.system__date: the date,YYYY-MM-DD.system__time: the time,HH:MM. They save you formattingsystem__nowon your side.system__timezone: the agent time zone (IANA name), for exampleEurope/Lisbon. If the agent time zone is invalid, Atendia usesEurope/Lisbon.- The console test has no call and no agent. The values are test values:
system__call_idistest_and a random identifier, the channel istest,system__agent_idistest_agentand the time zone isEurope/Lisbon. The time is the time of the test.
Times and sizes
- Request timeout: 1 to 300 seconds. The default is 30.
- Your API's response can be up to 256,000 bytes. Above that, the request fails. The body Atendia sends has the same limit.
- The agent reads up to 4000 characters of the result, which has the form
{"status": 200, "data": ...}. The count is made after you pick the response fields, if you pick any. - Above 4000 characters, the agent receives
{"truncated": true, "data": "..."}with the text cut. Pick fields so the response fits. - Fields named like
token,password,secret,cookieorauthorizationreach the agent as[REDACTED]. Numbers that look like payment cards are hidden too. - A response that is not JSON is read as text. An empty response counts as
{}.
Responses and errors
The agent never sees the body of an error from your API. It hears a fixed sentence, depending on the case:
| What happens | What the agent hears |
|---|---|
| Your API answers 200 to 299 | It receives the result. |
| It answers 3xx (redirect) | The service redirected the request and the redirect was not followed. |
| It answers 401 or 403 | The service refused the authentication. |
| It answers 404 | The service did not find the requested resource. |
| It answers 429 | The service limited requests for now. Wait before trying again. |
| It answers another 4xx | The service refused the request data. |
| It answers 5xx | The service returned an error. It does not retry by itself; it says the confirmation is pending. |
| It does not answer within the timeout | The request exceeded the time limit. It does not retry by itself; it says the confirmation is pending. |
| The connection fails midway | The connection failed. It does not retry by itself; it says the confirmation is pending. |
| The response goes over 256,000 bytes | The response exceeded the limit. It does not retry by itself; it says the confirmation is pending. |
| The destination is refused, or the server name does not exist | The destination is not authorized, or it could not be found. The request was not sent. |
| A required parameter is missing, or a value is not allowed | The data sent is not valid. The request was not sent. |
Writes and repeats
Anything that is not a GET counts as a write. During the same call, Atendia does not send the same write again with the same data. If the agent asks for it again, it hears that it was already done, or that it is still pending.
If you change one value, it is a different request. If the first one was left unconfirmed, the agent does not repeat it either.
On your API's side
- Answer 2xx only when the work is done.
- Use different codes for different errors (401, 404, 429, 5xx). The code decides what the agent hears.
- Answer fast. A write that takes longer than the timeout leaves the result unconfirmed.
- Return only what the agent needs, or pick fields in the tool.
- When the tool stops working on real calls, the organization's owners get an e-mail: right after a refused key (401 or 403), or at the third network or server failure (5xx) in a row. They also get one, once, when the key expires within the next 7 days. At most one e-mail per tool per day. Tests and 404 replies do not count.
Request signing
Atendia can sign HTTP tool requests and the post-call webhook. This way your API knows the request came from Atendia. The signature follows the Standard Webhooks standard, which has official libraries.
- It is optional and per organization: one secret serves all tools and the post-call webhook. Without a secret, requests go out as before, unsigned.
- The secret starts with
whsec_. Create it in the console, in «Settings» → «Request signing». API keys cannot create it. It is shown only once; store it as a secret in your system. - If you lose it, use «Create new secret»: the new one replaces it (see «Rotating the secret»).
What arrives
webhook-id: the request identifier (see «Request id and duplicate key»).webhook-timestamp: the send time, in Unix seconds.webhook-signature:v1,and a base64 signature. During a secret rotation there are two, separated by a space.- What is signed is
webhook-id, a dot,webhook-timestamp, a dot and the body, exactly as sent. In a request without a body (a GET), the body is empty text. The algorithm is HMAC-SHA256, with the key equal to the base64-decoded text afterwhsec_. - The address and the other headers are not signed.
How to verify
- Read the body as text, as it arrived, before parsing it as JSON. A rewritten body no longer matches the signature.
- Accept only requests whose time is within 5 minutes (either way). This is the tolerance of the official libraries.
- Check the start of
webhook-id. For a tool, it isatd_tool_and the id of your tool, followed by_. For the post-call webhook, it isatd_postcall_and the agent id, followed by_. Without this, a request signed for another tool of the same organization would also pass. The tool id is shown in the console. - If verification fails, answer 401 and do nothing with the request.
- Start by also accepting unsigned requests, and log them. Only when you see requests arriving signed, start refusing those without a signature.
- The libraries read the body as JSON. For a request without a body (GET), use the by-hand example.
Examples
The Node and Python examples were run against requests signed by Atendia code: they accept a valid request and refuse a changed body, a time outside the tolerance, another secret and another tool id. Install the library with npm install standardwebhooks or pip install standardwebhooks.
Node, with the library
import { Webhook } from "standardwebhooks";
// The whsec_... secret, shown once when you created it.
const webhook = new Webhook(process.env.ATENDIA_SIGNING_SECRET);
// rawBody: the body text exactly as received, before any JSON parsing.
// headers: the request headers, names in lower case.
export function verifyAtendia(rawBody, headers, idPrefix) {
// Throws if the signature is wrong or the timestamp is more than 5 minutes off.
const data = webhook.verify(rawBody, headers);
// Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
if (!headers["webhook-id"].startsWith(idPrefix)) throw new Error("unexpected id");
return data;
}
Node, by hand
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyAtendia(secret, rawBody, headers, idPrefix) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) return false;
// 5 minutes either way. "!(x <= 300)" also refuses a timestamp that is not a number.
if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300)) return false;
// Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
if (!id.startsWith(idPrefix)) return false;
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();
// During a rotation there are two entries; one match is enough.
return signatures.split(" ").some((entry) => {
const [version, value] = entry.split(",");
if (version !== "v1" || !value) return false;
const received = Buffer.from(value, "base64");
return received.length === expected.length && timingSafeEqual(received, expected);
});
}
Python, with the library
import os
from standardwebhooks import Webhook
# The whsec_... secret, shown once when you created it.
webhook = Webhook(os.environ["ATENDIA_SIGNING_SECRET"])
def verify_atendia(raw_body: bytes, headers: dict, id_prefix: str) -> None:
# Raises WebhookVerificationError if the signature is wrong or the
# timestamp is more than 5 minutes off. raw_body: the bytes as received.
webhook.verify(raw_body, headers, json_parse=False)
# Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
if not {k.lower(): v for k, v in headers.items()}["webhook-id"].startswith(id_prefix):
raise ValueError("unexpected id")
Python, by hand
import base64
import hashlib
import hmac
import time
def verify_atendia(secret: str, raw_body: bytes, headers: dict, id_prefix: str) -> bool:
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not (msg_id and timestamp and signatures):
return False
try:
age = abs(time.time() - float(timestamp))
except ValueError:
return False
if not age <= 300: # 5 minutes either way; also refuses nan
return False
# Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
if not msg_id.startswith(id_prefix):
return False
key = base64.b64decode(secret[len("whsec_"):])
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
expected = hmac.new(key, signed, hashlib.sha256).digest()
# During a rotation there are two entries; one match is enough.
for entry in signatures.split(" "):
version, _, value = entry.partition(",")
if version != "v1" or not value:
continue
try:
received = base64.b64decode(value)
except ValueError:
continue
if hmac.compare_digest(received, expected):
return True
return False
Rotating the secret
- Use «Create new secret» to create another. The old one keeps signing for 24 hours, and each request carries both signatures in the same header (
v1,... v1,...). The libraries accept it if either one matches. - In that window, put the new secret in your system. Requests do not fail.
- If you create another new secret before the 24 hours are up, the oldest stops signing at once: there are never more than two.
- «Stop accepting the previous one» cuts the old secret at once (for example, if it was exposed). «Turn off signing» deletes all secrets and requests go back to being unsigned.
What the signature proves
- It proves the request came from Atendia, with your organization configuration.
- It does not prove that the values the agent filled in from the conversation are true. Validate them as you would validate what a user types.
- Anyone in your organization with permission to edit tools can make Atendia sign a request to the address and with the body they choose, including through the console test. The id prefix only tells you which tool the request comes from; the signature trusts whoever configures the tools.
Request id and duplicate key
- With signing, each tool request carries a new
webhook-id:atd_tool_, the tool id,_and 22 random characters. Two identical requests have different ids. The id is for checking the origin, not for catching duplicates. - For duplicates, the tool has the «Avoid repeated requests» switch. When it is on, Atendia sends the
Idempotency-Keyheader (atd_and 32 characters) in every request that is not a GET. It works with or without signing. A new tool starts with the option on; tools that already existed stay off. - The key is computed from the call, the tool, the method, the address and the body. The same write, with the same data, in the same call, always carries the same key. The key does not reveal the data.
- Limit: different data gives a different key. If the agent repeats the write with a different value (another time, another name), Atendia sends it as a new request, with another key. Also check duplicates by the data, for example by the time and the contact.
- Your API has to store the key and, on seeing it again, return the stored result. Not every API handles this header; if yours ignores it, the key does not protect.
- The names
webhook-id,webhook-timestamp,webhook-signatureandidempotency-keybelong to Atendia. You cannot set them in the headers of a tool or of the post-call webhook (saving is refused), and when sending Atendia replaces any header with that name by its own.
Testing in the console
- The test sends a real request to your API.
- For a request that is not a GET, the console asks you to confirm before sending, because it may change data.
- There is a limit of 10 tests per minute per organization.
- If the tool uses the contact's number, the test uses the sample number you give.
- The test shows the full response, with secrets hidden, and "What the agent receives": the result after the fields are picked and cut as in a call. The agent reads it as text.
- After a rejected key (error 401), Atendia waits 1 minute before sending another request to that service. The test shows how many seconds are left.
Import from an API example (cURL)
Paste a curl command from your API documentation and the console fills in the tool. Nothing is run, sent or saved until you save the tool. If the tool is already filled in, the console asks for confirmation before replacing it.
What is accepted
- The address and the options
-X/--request(GET, POST, PUT, PATCH, DELETE),-H/--header,-d/--data/--data-raw/--data-binary/--jsonwith a JSON body,-G/--getand-u/--user. Single and double quotes and\at the end of a line work. - Without
-X, the method is GET; with a body, it is POST. With-G, the-ddata goes into the query.--jsonadds the JSONContent-TypeandAcceptheaders. - The options
-s,-S,-v,-i,--compressed,-Land-kare ignored, with a note. Atendia does not follow redirects (-L) and always checks the certificate (-k). - The JSON body becomes parameters with a fixed value, each with its «Position in the JSON» (see «Paths»), up to 50 values. The query becomes query parameters with a fixed value.
Credentials
- A header with a credential name (
Authorization,X-Api-Key...) and-u(which becomesAuthorization: Basic) are kept as a header of type «Secret». - A query or body parameter with a credential name (
token,password...) becomes aDynamic Variableparameter linked to a dynamic variable of type «Secret». - When you save, these values are stored securely. No credential stays in clear text in the tool.
What is refused
The console refuses the whole command, with a message, and imports nothing. It refuses:
- Any other option.
- Shell constructs:
$(...), backticks,$VARIABLEoutside single quotes,;,|,&,<and>. -b/--cookie,-K/--config,--oauth2-bearer,--data-urlencode,-F/--form,@file, a user and password in the address (https://u:p@...).- A body that is not JSON, a body on a GET and the Atendia reserved headers.
Paths
Response paths
In "Response fields" you give each field a name and a path (up to 20 fields). The agent receives only those fields, in data. Paths are read like the response variables of the start webhook.
a.b.cgoes down through keys.items[0].namereads the first element of a list.- If the response is a list, start with
[0]. Do not use$[0]. $is the whole value.$.ais the same asa.items[*].namegives the list of the names of all elements, up to 100. Elements without the field are left out. Ifitemsis not a list, the result isnull.- A key that exists exactly as written, like
"a.b", wins over step-by-step reading. [01]is the same as[1].a[0]bis the same asa[0].b. Spaces around the path are ignored.- A path that cannot be read is refused when you save: an empty segment (
a..b,a.), an unclosed bracket (a[0) or an index that is negative or not a number. A valid path with no value in the response, such as an index outside the list, arrives asnull. - Only keys of the response itself are read.
lengthortoStringdo not exist. - Up to 8 steps and 200 characters.
__proto__,prototypeandconstructorare refused. An index with digits other than 0 to 9 is refused on save. - A field name has letters, digits and
_, starts with a letter or_and has up to 64 characters. Names the cleaning would hide (token,password,secret…) are refused, because the agent would only see[REDACTED]. - The cleaning runs before the picking. If the path goes through a
[REDACTED]text, the field arrives as[REDACTED].
Position in the body
- Form:
customer.phone,items[0].id. Each name uses letters, digits and_ $ @ : -, up to 64 characters. The index goes from 0 to 99. - Up to 8 steps and 200 characters. No leading
$and no[*]. - On save, Atendia refuses repeated positions, a position that is both a value and a parent (
aanda.b), a node that is both a list and an object (a[0]anda.b) and list indexes that do not start at 0 or skip. - An object or list only appears in the body if it has at least one value. In a list, elements with no value are dropped and the next ones move up.
- Only body parameters have a position. Query and path are always flat.
Post-call webhook
At the end of the call, Atendia makes a POST to the agent post-call webhook address, with the result as JSON. Answer 2xx quickly: Atendia waits 10 seconds and any answer that is not 2xx counts as a failure. The same delivery can arrive more than once: keep what you have handled and ignore the repeat.
The body
- Always:
callId,agentId,startedAt,endedAt,durationSeconds,direction,callerIdandextractedData. transfer(state, and when they existreasonandhumanSeconds): only if the call attempted a transfer.transcript: a list ofrole,messageandtimestamp, only if you turned on the transcript in the webhook.audioUrl: the recording address, only if you turned on the audio in the webhook.
Headers and signature
Content-Type: application/jsonand the headers you configured in the webhook. The Atendia reserved names (see «Request id and duplicate key») are not accepted.- With a signing secret, the webhook carries
webhook-id,webhook-timestampandwebhook-signature, verified as in the «Request signing» section. The signed body is the exact text Atendia sends. - The
webhook-idisatd_postcall_, the agent id,_and the call id. A repeated delivery carries the same id: keep the ids you have handled and discard a repeated delivery. Check that the id starts withatd_postcall_and your agent id. For an outbound call that ends without a call log, the id carries theoutboundIdand the status, and the result that arrives later with the call log carries another id; see «Make calls from your program». - The call-start webhook is not signed yet.
Two examples
Look up an order (GET)
The tool, with its response fields:
Method: GET
Address: https://api.shop.example/orders/{number}
Header: Authorization = (secret)
Path parameter: number (LLM Prompt, text, required)
Response fields:
status <- order.status
delivery <- order.delivery.date
items <- lines[*].nameYour API answers:
{"order": {"status": "shipped", "delivery": {"date": "2026-11-03"}},
"lines": [{"name": "Chair", "price": 49.9}, {"name": "Table", "price": 120}]}The agent receives:
{"status": 200, "data": {"status": "shipped", "delivery": "2026-11-03", "items": ["Chair", "Table"]}}Create a support ticket (POST)
The tool, with positions in the body:
Method: POST
Address: https://api.shop.example/support-tickets
Body parameters (name -> position):
name -> customer.name (LLM Prompt)
phone -> customer.phone (Dynamic Variable: system__contact_number)
subject -> no position (LLM Prompt)
priority -> details.priority (Static Value: normal)The body sent:
{"customer": {"name": "Ana Reis", "phone": "+351900000000"},
"subject": "Late delivery",
"details": {"priority": "normal"}}Your API answers {"id": "A-1042"} and the agent receives:
{"status": 201, "data": {"id": "A-1042"}}Send an SMS
The agent can send an SMS during the call, through your own account with an SMS provider (for example, LOX24), using an HTTP tool. The messages go out from your account and you pay the provider.
How to set it up
- Open an account with an SMS provider that has an API.
- Create the API key. In LOX24: «Settings» → «API Settings», with the role «API v2: messaging».
- Ask the Builder, for example: «I want the agent to send an SMS confirming the booking». The Builder prepares the tool and you type the key into the secret field. With LOX24, type your account number, a colon and the key (
<account number>:<key>). - On the card, the LOX24 destination address is
https://api.lox24.eu/sms.
What the agent does
- It asks first and only sends after the person on the call confirms. The tool has «Confirm before sending» turned on.
- It always sends to the number of the person on the call. On an outbound call, that is the number the agent called.
- As a rule, it sends only one SMS per call.
- The text test does not send an SMS.
The SMS text
- No accents and up to 160 characters. Above that, it counts as 2 SMS. Write «€» as «EUR».
- The sender is the business name: up to 11 letters, no accents.
- For a health business, we recommend a neutral text: date, time and business name. The decision is yours.
If the key is wrong
- After a rejected key, Atendia waits 1 minute before sending another request to that service. On calls, the same key stays paused for 15 minutes.
- Fix the key and test the tool in «Tools».
- Why: some providers block requests from everyone after several wrong keys.
What is kept
What the agent reads out to confirm the SMS stays in the call transcript and summary, like the rest of the conversation. The text sent stays in your account with the SMS provider.
Other providers
If you already use BulkGate, the Builder has its steps too. With another provider that has an API, the path is the same as for any API: import the provider's example, then change the number by hand to the number of the person on the call, and set the text to be filled in by the agent. See Import from an API example (cURL).
Current limits
- No OAuth2. Use a fixed token in a header, stored as a secret.
- No variable-length lists. The agent does not choose how many elements to send. A fixed-length list is built with indexes (
services[0].id,services[1].id). - In the body, a key with
.can only be sent without a position, at the top level. Inside an object it is not supported. - JSON bodies only. No forms and no files.
- Only
https://, no redirects and no private destinations.