Advanced
Custom Procedures with JavaScript and API calls
Version 1.0 · Last updated 2026-05-27
The standard Procedure types (follow-up, redirect, component, switch topic, live chat) cover most cases. When they do not, custom JavaScript and API call Procedures let the agent take any action your stack supports without leaving the conversation.
Key concepts
Custom JavaScript Procedures
Run any JavaScript when the customer clicks the Procedure. Manipulate the DOM, call your in-page JS API, do anything the browser allows. Useful for tightly integrating with the surrounding product.
API call Procedures
Call an endpoint on your backend. Send configured headers and input fields. Receive a JSON response the agent can use directly, or transform with a small JavaScript snippet.
MCP server connections
For broader integrations beyond a single endpoint, connect your own MCP (Model Context Protocol) server. The agent reads and acts through MCP the same way it does through any other connector. See Living Context for the setup pattern.
Variables
Both types collect variables from the customer first if the agent does not have them. Variables can depend on previous answers.
Response handling
For API calls, the JSON response feeds back into the conversation. Common patterns: success and error messages, customer-facing text, follow-up Procedures.
Authentication
API call Procedures support custom headers, bearer tokens, and per-tenant secrets. Manage secrets in your account.
What you can do here
- Build a Procedure that runs custom JavaScript on click
- Build a Procedure that calls your backend and uses the response
- Collect variables from the customer before running
- Transform API responses with JavaScript
- Set custom success and error messages
- Manage authentication credentials
When to use it
- The standard Procedure types do not cover your need
- You need to call your own backend (account lookup, status check, billing query)
- You need deep integration with your in-page product
- You need to do something inside the customer’s session that requires custom logic
When not to use it
- The standard Procedure types would actually work. Start there.
- You need scheduled background work. Procedures run on customer interaction, not on a schedule.
- The logic belongs in your backend, not in the agent. In that case, the agent calls your backend through an API call Procedure; the logic stays where it belongs.
How it works
Custom JavaScript runs in the customer’s browser when they click the Procedure. API calls run server-side against your endpoint with the configured headers. Both leave records in the audit trail in Accountability.
Frequently asked questions
How do I build an API call Procedure?
Open "Train > Procedures > Create procedure", pick "API call", configure the endpoint, headers, and input fields. Add a success and error message. Save.
How do I authenticate the API call?
Add a header. For bearer tokens, store the secret in your account settings and reference it from the header. Avoid pasting secrets directly into the Procedure.
How do I use the API response in the conversation?
Map the response fields to placeholders in the success message. The agent renders the message with live values.
How do I transform an API response before showing it?
Add a JavaScript transformer to the Procedure. The transformer receives the raw JSON and returns the value or values to use in the success message.
Can custom JavaScript do anything?
Anything the customer's browser allows. Standard browser security rules apply (CORS, same-origin policy). For server-side actions, use an API call Procedure.
How do I see what an API call did?
Open "Analyze > Conversations", find the conversation, and inspect the Procedure run. You see the request, the response, and the customer's reaction.
