Input parameters, body template, headers, and response mapping
How to define the data your agent sends to your API and how to extract just the value it needs from the response.
Watch this step in the video · Custom actions: parameters, variables and testing
What this configuration is for
Once the action exists, these four blocks define what the agent sends to your API and what it gets back into the conversation: input parameters, the body template, headers, and response mapping. Getting them right is what makes the integration reliable.
Input parameters (input_schema)
These are the values the model must fill before calling the endpoint. In the Input parameters section, click Add parameter and define for each one:
- Name: the field identifier (e.g.
email,plan_id). - Type:
string,number,boolean,email, orphone. - Description: explain what it is; the model uses it to fill the right value.
- Required: check the box if the agent can't call the action without that value.
The model infers these values from the conversation, so a good description (e.g. "customer email to look up their order") greatly improves accuracy.
Body template
This is the body sent with POST, PUT, or PATCH methods (it isn't used on GET). Write it in JSON, with variables replaced at run time:
{
"email": "{{input.email}}",
"channel": "{{contact.email}}"
}
{{input.name}}inserts an input parameter.{{contact.email}}and other contact fields insert data about whoever is chatting.
If you declare a Content-Type: application/json header, the body is sent as JSON; otherwise it's sent as plain text.
Headers
Under Headers, click Add header and add key/value pairs. The most common is authentication:
Authorization→Bearer YOUR_TOKENContent-Type→application/json
You can define up to 20 headers. Values also accept {{...}} variables.
Field to extract (response_mapping)
Your API usually returns a large JSON, but the agent only cares about one value. In Field to extract (response_mapping), enter the dot path to that value:
- Response
{"data": {"plans": [...]}}→ enterdata.plans. - Leave it empty and the agent receives the full response.
This keeps the model's context clean and focused only on what's useful.
Verification
- Each required parameter shows its Required box checked.
- The Body template is valid JSON (balanced braces) and only uses variables that exist.
- After Save action, use Test to confirm your API receives the fields and that Field to extract points to the right value.
If it doesn't work
- A value arrives empty: check that the variable name
{{input.x}}matches the parameter Name exactly. - Your API rejects the body: add the
Content-Type: application/jsonheader and validate that the JSON is well formed. - The agent returns "too much information": set Field to extract to keep only the value you need.
Tip: start with few parameters and only the essential Required ones. The fewer values the model has to guess, the more reliable it is.
Tip: never put tokens in the URL; put them in Headers (
Authorization).
Related articles
Related articles
-
Create your first AI agent
Learn what an AI agent does in Omnifox, how to give it instructions, connect it to a channel and test it in the sandbox before it talks to real customers.
-
How to write good instructions for your AI agent
Learn how to write clear instructions so your AI agent replies with the right tone, limits and actions.
-
AI Agents complete guide
AI Agents in depth, in 65 chapters: creating, instructions, tools, knowledge, behavior, tester, inbox, workflows, analytics and usage, with every setting explained.
-
Connect your AI agent to WhatsApp, Instagram, Messenger and web chat
An agent with no channels serves nobody. Connect it to your WhatsApp, Instagram, Messenger or website chat from the Connections section, then switch it on so it starts replying.
-
Start here: AI Agents in 8 minutes
AI Agents essentials in a short video: creating an agent, its instructions, tools, knowledge, channels, the tester, hours and handing over to a person.