Custom API tools and API calls
There are two ways to reach your own systems. A custom API tool is something an AI agent decides to call mid-conversation. An API Call step is a request a journey always makes at a set point.
Use a custom API tool when an agent needs live data or needs to take an action while it talks to a customer, for example checking an account status or creating a support ticket. For a tool that reads the customer's own account, Kontakt can fill the request from the customer's verified phone or email. See Look up the customer the agent is talking to. Use an API Call journey step when the request should happen every time a journey reaches that step, for example notifying your CRM after a purchase or fetching a value to put in a message.
| Custom API tool | API Call step | |
|---|---|---|
| Who decides to call it | The AI agent, when a skill allows it | The journey, every time it reaches the step |
| Where you set it up | Settings / Connectors | The journey builder |
| Request | JSON the agent builds from the conversation, as query parameters for GET | A template you write, with Liquid variables |
| Authentication | None, bearer token, or an API key header | None, bearer token, or a custom API key header |
| Signing | No | Optional HMAC SHA-256 |
| Timeout | 5 seconds | Up to 30 seconds |
| Retries | No | Up to 5 attempts |
Custom API tools for agents
Before you start
- A role that can change workspace settings.
- An HTTPS endpoint that accepts a JSON body and returns JSON.
- Optionally, a bearer token your endpoint checks.
Add a tool
Open Connectors
Go to Settings / Connectors and click Connect on the Custom API card.
Describe the endpoint
- Tool name: a short action name, such as
Create ticket. Kontakt builds the tool's ID from it. - Method:
POSTis the right choice for most tools. See How a tool call works for why. - Endpoint URL: the full URL Kontakt calls.
- Authentication: No auth or Bearer token. With Bearer token, paste the Token.
Save
Click Add tool. The tool now appears under Connectors and in AI / Tools.
Tell the agent when to use it
New tools get a generic description and accept any JSON input. Open the tool in AI / Tools and write a clear Description of what it does and when to call it. In Input schema JSON, list the fields your endpoint expects as a JSON Schema object, then click Save Tool. The agent uses both to decide when to call the tool and what to send. See Tools.
{
"type": "object",
"properties": {
"subject": { "type": "string", "description": "One-line summary of the problem" },
"order_number": { "type": "string" }
},
"required": ["subject"]
}Allow it on a skill
Agents only call tools a skill permits. Open the skill under AI / Skills and tick the tool under Permitted Tools. See Skills.
How a tool call works
When the agent calls the tool, Kontakt sends one request:
- Input: the JSON object the agent built, matching your input schema.
GETsends each filled field as a query parameter; other methods send the object as the JSON body. A tool that looks the customer up sends the customer's own phone, email, or ID instead. - Headers:
Content-Type: application/jsonfor methods with a body, plusAuthorization: Bearer <token>for a bearer token, or the API key in the header you named. - Timeout: 5 seconds. If your endpoint is slower or unreachable, the agent gets an error instead of a result and answers without it.
- Response: if your endpoint returns JSON, the agent reads it as is. Otherwise the agent gets the status code and raw text.
curl -X POST https://your-api.example.com/tickets \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"subject": "Order arrived damaged", "order_number": "1042"}'
That is the request your endpoint receives for a ticket tool whose input schema has subject and order_number.
Current limits
GETquery parameters are sent as text, so nested objects and lists needPOST.- Basic auth is not supported. Use a bearer token or an API key header.
- Tool calls are not retried.
Edit or remove a tool
On Settings / Connectors, use Edit to change the name, method, URL, or credentials. Leave the credential blank to keep the saved one. Disconnect removes the tool, and skills can no longer call it.
The API Call journey step
Add the step
Add API Call to your journey
In the journey builder, drag API Call from Actions onto the canvas. Data Lookup in the same group is a preset for fetching data with GET.
Set the request
Choose the method and enter the URL. Add Headers as name and value pairs. For methods other than GET, write the Request Body. The URL, headers, and body all accept Liquid, for example {{customer.email}} or {{trigger.event_properties.order_id}}.
Add authentication
Under Authentication, pick one:
- None (or set headers yourself)
- Bearer token: sends
Authorization: Bearer <token>. - API key header: sends the key in a header you name. The default header is
X-API-Key.
Sign the request (optional)
Under Sign the request, choose HMAC SHA-256 of the body and enter a shared secret. Kontakt signs the exact request body and puts the signature in a header you name, X-Signature by default, with an optional prefix such as sha256=, in hex or base64. Your endpoint recomputes the HMAC over the raw body and compares.
Keys and secrets are stored encrypted and shown masked after saving. Leave the masked value to keep it.
Handle the response and errors
- Response Root Path: keep only part of the response, such as
data.result. Leave it empty to keep the whole response. - Timeout (ms): defaults to 10,000. The maximum is 30,000.
- Retry on Failure: set Max attempts (up to 5) and the First wait, which doubles on each retry up to 10 seconds. Kontakt retries timeouts, network errors,
429, and5xxresponses. - On Error: Continue to next node (store error in context), or Stop the journey and mark it failed.
Use the response in later steps
Later steps can read the result:
{{nodes.<step id>.response}}: the parsed JSON response, or the part at Response Root Path.{{nodes.<step id>.status_code}}: the HTTP status code.{{nodes.<step id>.status}}:success,failed, ortimeout.
The panel shows the exact variable names for the step you are editing. Use a Condition Check on status to branch when a call fails.
How errors behave
- A
2xxresponse setsstatustosuccess. - A
4xxresponse, or a5xxafter the last retry, setsstatustofailedand the journey continues, even with Stop the journey and mark it failed selected. - A timeout or network error after the last retry sets
statustotimeoutorfailed. With Stop the journey and mark it failed, the journey stops for that person.
Troubleshooting
The agent never calls my tool
Check that the tool is ticked under Permitted Tools on a skill your agent uses, and that its Description in AI / Tools says plainly when to use it.
My endpoint receives an empty body
The tool uses GET, which sends the input as query parameters. Change the HTTP method to POST in AI / Tools to receive a JSON body.
My endpoint rejects the tool's credentials
Check the Auth type in AI / Tools. With API key header, enter the key again together with the Header name your endpoint expects.
An API Call step shows a missing or unreadable token
The step's token or signing secret was not saved. Open the step, enter the secret again, and save the journey.