Skip to main content

​
What HTTP Tools do

HTTP Tools are a Power Tool add-on that lets you wire your AI agent to your own HTTPS endpoints. When the AI decides one is the right move during a call, it calls your endpoint, reads the response, and continues the conversation with that answer in hand. Use them for:
  • Routing decisions, “Which extension should I transfer this caller to right now?”
  • CRM lookups, “Is this caller already a customer? What’s their last order?”
  • Availability checks, “Is this Saturday slot still open?”
  • Quote / pricing fetches, “What’s the current quote for SKU X?”
  • Anything only your backend knows that the agent needs mid-conversation.
A configured HTTP Tool appears to the AI as a regular function, separate name, description, and JSON Schema for its arguments. You can wire as many as you want.
HTTP Tools is a paid add-on. Add Power Tools (a rate on request) from your Account → Billing screen to unlock the tool manager.

​
How it fits with everything else

  1. The caller talks to your AI agent on the phone.
  2. The AI decides a HTTP Tool is the right next move (based on its description).
  3. We POST a signed JSON payload to your endpoint.
  4. You return whatever data the AI needs (plain text, JSON, HTML, your call).
  5. The AI uses that response in its next reply.
Existing transfer mechanisms (PBX transfer, SIP REFER, voicemail drop) stay exactly as they are. The AI chains: HTTP Tool lookup → transfer to extension X.

​
What’s in the box

Quick start

Configure your first tool in under 5 minutes.

Request & response shape

What we send you and what we expect back.

Signature verification

Verify every request is really from us using HMAC-SHA256.

Error codes

Every failure mode, what it means, and how to fix it.

Rate limits

Per-tenant and per-tool token-bucket budgets.

Security restrictions

Why we block private networks, redirects, and binary responses.

Best practices

Designing endpoints the AI can use well.

Code samples

Drop-in handlers for Node.js, Python, PHP, and Go.

Troubleshooting

Common failures and how to debug them from the dashboard.

​
Guarantees and limits

Two body modes. By default a tool runs in envelope mode: we wrap the arguments in a canonical JSON body, add X-SmartAlex-* headers, and sign it with HMAC (see Signature verification). If your endpoint is a third-party API that doesn’t understand our envelope, switch the tool to passthrough mode: you supply a flat JSON body template with ${vault.token} and ${arg.name} placeholders, and we POST it as-is with no envelope, no signature, and no X-SmartAlex-* headers. Passthrough tools carry their credential inside the template, so the auth scheme is fixed to “none”. Passthrough tools can also opt into a short response cache (cache_ttl_ms) to skip repeat calls for identical inputs.
Everything else, schema authoring, signing-secret rotation, test fires, invocation replays, happens in the dashboard. You should never need to ping support to wire a new tool up; if you do, tell us so we can fix the gap.

​
Trust model and data handling

Every invocation forwards caller_number, tenant_id, agent_id, call_id, the LLM-provided arguments, and a timestamp to your endpoint. Your endpoint runs in your infrastructure under your privacy policy, once data crosses that boundary it’s yours to handle. The body you return is passed verbatim to the AI (subject to a 64 KB cap and a small obfuscation pass on the dashboard preview only, never on the wire). Prompt-injection inside the response body is the customer’s responsibility, don’t put untrusted free-form text in tool_result without sanitization on your side.