Skip to content

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 toolAPI Call step
Who decides to call itThe AI agent, when a skill allows itThe journey, every time it reaches the step
Where you set it upSettings / ConnectorsThe journey builder
RequestJSON the agent builds from the conversation, as query parameters for GETA template you write, with Liquid variables
AuthenticationNone, bearer token, or an API key headerNone, bearer token, or a custom API key header
SigningNoOptional HMAC SHA-256
Timeout5 secondsUp to 30 seconds
RetriesNoUp 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: POST is 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. GET sends 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/json for methods with a body, plus Authorization: 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

  • GET query parameters are sent as text, so nested objects and lists need POST.
  • 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, and 5xx responses.
  • 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, or timeout.

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 2xx response sets status to success.
  • A 4xx response, or a 5xx after the last retry, sets status to failed and the journey continues, even with Stop the journey and mark it failed selected.
  • A timeout or network error after the last retry sets status to timeout or failed. 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.