Guides

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://. With http://, 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 sends Content-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, Upgrade and Proxy-* 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_number is 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) or test. 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 example 2026-11-03T14:30:05+00:00.
  • system__date: the date, YYYY-MM-DD. system__time: the time, HH:MM. They save you formatting system__now on your side.
  • system__timezone: the agent time zone (IANA name), for example Europe/Lisbon. If the agent time zone is invalid, Atendia uses Europe/Lisbon.
  • The console test has no call and no agent. The values are test values: system__call_id is test_ and a random identifier, the channel is test, system__agent_id is test_agent and the time zone is Europe/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, cookie or authorization reach 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 happensWhat the agent hears
Your API answers 200 to 299It receives the result.
It answers 3xx (redirect)The service redirected the request and the redirect was not followed.
It answers 401 or 403The service refused the authentication.
It answers 404The service did not find the requested resource.
It answers 429The service limited requests for now. Wait before trying again.
It answers another 4xxThe service refused the request data.
It answers 5xxThe service returned an error. It does not retry by itself; it says the confirmation is pending.
It does not answer within the timeoutThe request exceeded the time limit. It does not retry by itself; it says the confirmation is pending.
The connection fails midwayThe connection failed. It does not retry by itself; it says the confirmation is pending.
The response goes over 256,000 bytesThe 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 existThe 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 allowedThe 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 after whsec_.
  • The address and the other headers are not signed.

How to verify

  1. Read the body as text, as it arrived, before parsing it as JSON. A rewritten body no longer matches the signature.
  2. Accept only requests whose time is within 5 minutes (either way). This is the tolerance of the official libraries.
  3. Check the start of webhook-id. For a tool, it is atd_tool_ and the id of your tool, followed by _. For the post-call webhook, it is atd_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.
  4. If verification fails, answer 401 and do nothing with the request.
  5. Start by also accepting unsigned requests, and log them. Only when you see requests arriving signed, start refusing those without a signature.
  6. 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

javascript
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

javascript
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

python
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

python
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-Key header (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-signature and idempotency-key belong 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 / --json with a JSON body, -G / --get and -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 -d data goes into the query. --json adds the JSON Content-Type and Accept headers.
  • The options -s, -S, -v, -i, --compressed, -L and -k are 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 becomes Authorization: Basic) are kept as a header of type «Secret».
  • A query or body parameter with a credential name (token, password...) becomes a Dynamic Variable parameter 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, $VARIABLE outside 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.c goes down through keys. items[0].name reads the first element of a list.
  • If the response is a list, start with [0]. Do not use $[0].
  • $ is the whole value. $.a is the same as a.
  • items[*].name gives the list of the names of all elements, up to 100. Elements without the field are left out. If items is not a list, the result is null.
  • A key that exists exactly as written, like "a.b", wins over step-by-step reading.
  • [01] is the same as [1]. a[0]b is the same as a[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 as null.
  • Only keys of the response itself are read. length or toString do not exist.
  • Up to 8 steps and 200 characters. __proto__, prototype and constructor are 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 (a and a.b), a node that is both a list and an object (a[0] and a.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, callerId and extractedData.
  • transfer (state, and when they exist reason and humanSeconds): only if the call attempted a transfer.
  • transcript: a list of role, message and timestamp, 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/json and 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-timestamp and webhook-signature, verified as in the «Request signing» section. The signed body is the exact text Atendia sends.
  • The webhook-id is atd_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 with atd_postcall_ and your agent id. For an outbound call that ends without a call log, the id carries the outboundId and 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:

tool
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[*].name

Your API answers:

json
{"order": {"status": "shipped", "delivery": {"date": "2026-11-03"}},
 "lines": [{"name": "Chair", "price": 49.9}, {"name": "Table", "price": 120}]}

The agent receives:

json
{"status": 200, "data": {"status": "shipped", "delivery": "2026-11-03", "items": ["Chair", "Table"]}}

Create a support ticket (POST)

The tool, with positions in the body:

tool
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:

json
{"customer": {"name": "Ana Reis", "phone": "+351900000000"},
 "subject": "Late delivery",
 "details": {"priority": "normal"}}

Your API answers {"id": "A-1042"} and the agent receives:

json
{"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

  1. Open an account with an SMS provider that has an API.
  2. Create the API key. In LOX24: «Settings» → «API Settings», with the role «API v2: messaging».
  3. 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>).
  4. 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.