This guide explains how to build HTTP Request tools for Talkative Voice AI. Tools allow your bot to connect to external systems in real time — fetching customer data, performing lookups, validating identities, making bookings, and more. Understanding how tools are structured, authenticated, and evaluated will help you build reliable integrations that work seamlessly within a voice conversation.
1. Authentication
Before your tools can access external systems, they need to be authorised. There are three common authentication patterns used with Voice AI HTTP Request tools.
1.1 Static API Token
The simplest form of authentication. You add a static API key directly to the tool's request headers. The key is fixed and does not change between calls.
How it works: Store your API token in Talkative's Private Credential Store, then reference it in the Authorization header of your HTTP Request tool. Every call to that tool will automatically include the token without it ever appearing in interaction logs.
Example header:
Authorization: Bearer {{MY_API_TOKEN}}💡 Always use the Private Credential Store rather than pasting raw tokens into your tool configuration. Stored credentials are never exposed in interaction logs, call recordings, or to Talkative staff. See Voice AI: Private Credential Storage for setup instructions.
Best used for: Straightforward API integrations, read-only lookups, or any system that issues a single long-lived API key.
1.2 OAuth Token via an Authentication Tool
Some APIs require a fresh bearer token for each session, obtained by exchanging credentials for an access token. In this pattern, you create a dedicated authentication tool that fetches the token first, and the LLM carries that token forward into subsequent tool calls.
How it works:
- Create an authentication tool (e.g. "Get Access Token") that calls your token endpoint with your client credentials passed as headers or in the request body.
- The endpoint returns a bearer token in its response.
- The LLM reads and remembers the token from that response.
- The LLM then passes the token as a parameter into subsequent tools, which reference it as
{{authToken}}in theirAuthorizationheader.
Example two-tool flow:
- Auth Tool →
POST /oauth/tokenwithclient_idandclient_secret→ Returns{ "token": "eyJh..." }
- Data Tool →
GET /customer/infowithAuthorization: Bearer {{authToken}}
Writing the auth tool prompt: Be explicit. Tell the LLM to call this tool first and hold onto the result. For example:
"Use this tool at the start of any interaction, before calling any other tools. Remember the token it returns — you will need to pass it into all subsequent tool calls."
Best used for: Microsoft Graph APIs, Salesforce, and other enterprise systems using OAuth 2.0 client credentials.
1.3 Customer Verification Token
This pattern is essential when your tools need to access personal customer data — account balances, order history, policy details, or any information scoped to an individual. A verification step confirms the caller's identity before any sensitive data is returned.
How it works:
- The bot collects a personal identifier from the caller during the conversation (e.g. date of birth, account number, telephone banking PIN).
- A verification tool sends the caller's identifier — along with a system identifier such as their phone number or a customer ID — to your verification endpoint.
- Your system validates the credentials and returns a short-lived session token.
- All subsequent tools use that session token. Your API uses it to scope every response to that specific customer's data, without the bot needing to pass account IDs in each call.
Real-world example — telephone banking:
- Caller provides their account number and telephone banking PIN.
- The verification tool sends
{ "accountNumber": "12345678", "pin": "1234" }to your verification endpoint.
- Your API confirms the credentials and returns a session token valid for that call.
- Subsequent tools (e.g. Check Balance, List Recent Transactions) pass that token, and your API automatically returns only that customer's data.
This pattern provides two critical benefits:
- Identity verification — the caller is confirmed as who they say they are before any data is shared.
- Automatic data scoping — every tool call is implicitly tied to the verified customer, reducing the risk of data leakage and simplifying your tool logic.
⚠️ The token returned by your verification endpoint should be short-lived and session-scoped. Never return a long-lived API key from a verification tool.
2. Input & Output
2.1 Configuring the Request (Input)
Each HTTP Request tool gives you full control over how the outgoing request is structured.
HTTP Method
Choose the appropriate verb for your API operation:
Method | When to use |
GET | Retrieve data (no request body) |
POST | Send data or trigger an action |
PUT | Update an existing resource |
PATCH | Partial update of a resource |
DELETE | Remove a resource |
Headers
Configure any headers your API requires — authentication, content type, API keys, or custom values. Headers can include template parameters, so you can pass dynamic values like a session token:
Authorization: Bearer {{authToken}}
Content-Type: application/json
x-api-key: {{MY_API_KEY}}Request Body & Template Parameters
The request body is where the LLM's intelligence comes in. You define a JSON body template containing {{parameterName}} placeholders, and define each parameter so the LLM knows what value to fill in.
For each parameter you define:
- Name — a
camelCasevariable name, e.g.accountNumber,postcode,startDate
- Type — almost always
string. Even numeric values should be typed as strings and let your API handle conversion
- Description — a clear, specific prompt telling the LLM exactly what value to provide and how to format it
Example body:
{
"customerId": "{{customerId}}",
"startDate": "{{startDate}}",
"timezone": "{{timezone}}"
}Example parameter description for startDate:
"The start date for the search in ISO 8601 format, e.g. 2026-06-05T09:00:00. Ask the caller for their preferred date before calling this tool and convert their answer to this format."
The more precise your parameter descriptions, the more accurately the LLM will populate the request. Include format examples wherever the expected format is non-obvious.
2.2 Designing the Response (Output)
The response your API returns is injected directly into the LLM's context window. The bot reads it and uses it to formulate its next spoken response. Response quality has a direct impact on conversation quality — an over-engineered response is just as harmful as one that's missing data.
The golden rule: return only what the bot needs to say.
Every unnecessary field adds noise, increases processing time, and raises the risk of the bot misinterpreting or over-sharing data. Strip your API responses down to the minimum.
Use human-readable values wherever possible. The bot will often read values near-verbatim. A status of "Active" is always better than a status code of 2. If your API returns internal codes, transform them in a middleware layer before the response reaches the bot.
Avoid values that require computation. If the bot needs to compare a date field against today's date to determine whether a payment is overdue, that calculation could go wrong. Return a plain "paymentStatus": "Overdue" instead.
Example — what to avoid vs. what to aim for:
❌ Over-engineered response:
{
"accountId": "ACC-001",
"statusCode": 2,
"lastUpdated": "2026-01-15T08:43:12Z",
"internalFlags": ["FLAG_A", "FLAG_C"],
"balance": 1245.50,
"availableCredit": 754.50,
"pendingTransactions": 3,
"riskScore": 72
}✅ Voice AI-optimised response:
{
"status": "Active",
"balance": "£1,245.50",
"paymentStatus": "Up to date"
}The second response gives the bot exactly what it needs to speak to the caller clearly, with nothing left to infer.
3. How Tool Evaluation Works with S4TS
Understanding how the LLM decides when and how to call tools helps you write better tool prompts and design more reliable integrations.
The diagram below shows the full tool evaluation loop.
Step-by-step breakdown:
- Customer Message — The caller speaks. Their voice is transcribed and passed to the LLM along with the full conversation history.
- Tool Matching — The LLM evaluates all available tools against the customer's message and the current conversation context. It uses each tool's prompt field to decide whether that tool is relevant. This is why clear, specific tool prompts matter.
- JSON Generation — For each matched tool, the LLM generates the JSON request payload, populating all template parameters based on what has been said in the conversation so far.
- Tool Execution — The Talkative harness executes all matched tools. Independent tools are run in parallel to minimise latency.
- Context Injection — The response from each tool is appended to the LLM's context window, alongside the original customer message.
- Re-evaluation — The LLM processes the enriched context. If it determines that additional tool calls are still required (for example, the auth token from step 3 is now available and a data lookup tool can now be called), the loop repeats from step 2.
- Response Generation — Once no further tools are needed, the LLM generates the spoken response and it is delivered to the caller.
Key design implications
Chain-dependent tools work through state. The LLM carries information from one evaluation cycle to the next. An auth tool can run in cycle 1, and a data tool that depends on the resulting token will run in cycle 2. Guide this behaviour explicitly in your tool prompts.
Tool prompts drive matching. The LLM uses the prompt you write for each tool to decide whether to call it. A vague prompt leads to missed or incorrect tool calls. Be specific about when the tool should — and shouldn't — be used.
Minimise evaluation cycles. Each additional cycle adds latency. Where possible, design your tools so that a single cycle is sufficient — group related data into a single API response rather than requiring multiple sequential calls.