Integrations

Custom actions: connecting your own systems

Connectors cover the services we have built in. Custom actions cover everything else: point one at any HTTPS address you control and your agent can call it mid-conversation — book the table, create the ticket, look up the order — using details it has gathered from the caller.

How an action works

An action is a small contract: a name, a description, the details to collect, and the address to send them to. When a call starts, every action enabled for that agent is offered to it as a tool. The description is what the agent reads to decide whether an action fits the conversation — write it the way you would brief a new employee: use when the caller has chosen a time and given their name and email. Once the agent has the details, we send one HTTPS request to your address and read your reply back to the agent, which carries on the conversation with it.

Building one

  • Details to collect. Up to 20, each Text, Number, Yes/no, or One of a list. The agent gathers them in conversation before anything is sent.
  • Constant fields. Values your endpoint needs that the caller never says — a location code, an API version. They ride along on every request, and if a name collides with a collected detail, the constant wins.
  • Confirms first. Switch it on for anything with consequences. The agent must read the details back to the caller and can only fire after they have agreed, on a later turn — it cannot confirm on its own behalf.
  • Holding phrase. Something to say while the request runs, so a slower endpoint does not turn into dead air.
  • Test. The Test button sends a real request to your real endpoint with arguments you type, and shows exactly what was sent, what came back, and what the agent would have said. Test requests carry "source": "Test" so your endpoint can tell them apart.

What your endpoint receives

For POST and PUT, one JSON body:

{
  "action": "book_table",
  "arguments": { "party_size": 4, "date_time": "2026-09-01T19:00" },
  "call": {
    "id": "<call id>",
    "tenantId": "<your account id>",
    "agentId": "<agent id>",
    "from": "+15551234567",
    "source": "Call"
  },
  "timestamp": 1735689600
}

For GET and DELETE there is no body: the collected details are appended to your URL as query parameters, and the call context travels in headers instead (X-TeleAgent-Call, X-TeleAgent-Tenant, X-TeleAgent-Agent, X-TeleAgent-From, X-TeleAgent-Source).

Every request also carries X-TeleAgent-Timestamp, X-TeleAgent-Signature and X-TeleAgent-Delivery — plus your own secret header, if you set one.

Proving the request is really ours

There are two ways, and you can use either or both.

The easy way: a secret header. In the action's How do we prove it's us? fields, name a header and give it a value only you know. We send it on every request for that action and never show the value again after you save it. Your endpoint just checks that the header matches. This works in every no-code tool, but the secret travels with each request — anyone who ever sees one has it.

The strong way: the signature. Your account has a signing secret (it starts with tas_), shown on the Actions page. We never send it. Instead, each request carries a code your endpoint can recompute:

  1. Take the value of X-TeleAgent-Timestamp and the raw request body, joined with a dot: timestamp.body.
  2. Compute HMAC-SHA256 over that string, keyed with your signing secret, as lowercase hex.
  3. Compare the result to X-TeleAgent-Signature after its v1= prefix, and reject the request if the timestamp is more than five minutes old.

For GET and DELETE there is no body, so the signed string is the timestamp, the method and the full URL including its query, joined by newlines. A matching signature proves the request came from us, was not altered on the way, and is not a replay of an old one. Rotating the secret takes effect immediately — the old one stops verifying the moment you do.

What happens with your reply

  • Success (any 2xx status). The agent reads your response body and uses it in the conversation — return the confirmation number, the price, the opening hours. Keep it short and factual; an empty body simply reads as done.
  • An error status. The agent is told the action failed, with the status and the start of your response, and levels with the caller rather than pretending.
  • Too slow. Each action has a timeout of 1–20 seconds (6 by default). Past it, the agent tells the caller the action did not respond.
  • Never twice. We never retry a request — a booking that timed out may still have gone through, and sending it again could double it. Every request carries a unique X-TeleAgent-Delivery id, so if your endpoint ever does see the same request twice, it can use that id to ignore the copy.

Good to know

  • HTTPS only, public addresses only. Your secret header should never travel in the clear, so plain http is refused — as are private and internal network addresses. Redirects are not followed.
  • Actions live in a library. Build one once, then tick it on each agent that should have it. An account can hold up to 20 custom actions.
  • Everything is on the record. Every attempt — sent, failed or blocked — appears in the action's history with what was sent and what came back. Your secret header value is never stored there.