API calls during a conversation

An API call lets the agent reach into one of your systems mid-conversation. Look up an order, check availability, create a ticket. The caller waits a second or two and gets a real answer instead of a promise that someone will call back. You set them up under Actions on your agent.

Before you build one

Two questions decide whether this is the right tool. Does the agent need the answer during the call? If the information can wait until afterwards, a summary email or a post-call webhook is simpler and cannot keep a caller waiting. Does the endpoint answer quickly? Anything over two or three seconds is a long silence on a phone call. If your system is slow, say so in the pre-execution message and keep the timeout honest.

Name it and describe it well

The description is not documentation. It is how the agent decides whether to call this at all, so write it for a colleague who has never seen your systems.

Say what it does, what it needs, and when to use it. “Looks up an order by order number. Use when the caller refers to an existing order.” beats “Order API”.

Avoid describing data the call does not return. If your description promises delivery dates and the response has none, the agent will keep looking for them and improvise when it cannot find them.

Declare your parameters

Add each value the call needs under Parameters, with a name, a type and a short description. This matters more than it looks. With parameters declared, the agent fills them in one at a time, like arguments. Without them, it has to compose a blob of JSON from your URL, and it gets that wrong more often.

	With parameters declared	Without
What the agent does	Fills each named value	Guesses a whole JSON object
Bad values	Rarer, and easier to spot	Harder to trace
Descriptions	Guide each value	One long instruction

Values the agent cannot know, such as the caller’s phone number or the language of the call, do not need to be parameters. Write them straight into the URL or body as {{caller_phone_number}} and {{language}}, and the call fills them in from the conversation.

Response mapping

Leave this empty and the agent gets the whole response. For most lookups that is exactly right, and mapping every field by hand would be work for nothing. Map when you want one of three things:

Narrow what the agent sees. Useful when the response carries fields that are irrelevant, or that you would rather the agent did not repeat back to a caller.
Keep a value for later. Mapped values are remembered for the rest of the conversation, so a later call or a later step can use them.
Route on a value. In a flow, a mapped value can decide which way the conversation goes next.

Name the values you want and give the path each one reads from. Once you map anything, the agent sees the mapped values instead of the full response.

The syntax

The left box is the variable name you choose. The right box is the path into the JSON response.

{
  "customer_name": "data.customer.name",
  "order_status":  "data.status"
}

Path	Reads
`data.customer.name`	A nested field
`orderId`	A field at the top level
`slots[0].time`	The first item in a list
`$`	The whole response, under one name

A leading $. is also accepted, so $.data.customer.name works too. You will see that style in our own integration definitions. It makes no difference to the result, so use whichever you find easier to read.

The Tell the agent what to do on success field is an instruction, not a filter. Writing “only mention the temperature” asks the agent to be discreet about data it can still see. If a field must not reach the agent, leave it out of the response mapping.

Mapped values stick around

A later call can use a mapped value as {{customer_name}}, exactly like any other variable. It is saved with the conversation too, so you can see it afterwards. That makes chaining natural: one call looks up a customer id, the next uses it.

Say something while it runs

Fill in Pre-execution message with a short line the agent says before the call starts, such as “Let me look that up for you.” Without it the caller hears silence, which on the phone reads as a dropped line. Keep it short and honest. If the call usually takes three seconds, do not say “just a moment” in a way that promises one.

Handle failure on purpose

Fill in Tell the agent what to do on failure. Otherwise the agent improvises, and improvising around a broken API is where callers get told their order is confirmed when nothing was written.

Good failure instructions say what happened and offer a way forward. “Say you could not reach the booking system, and offer to take a message so a colleague can call back.”

Timeouts, retries and fire-and-forget

Setting	Use it for
Timeout	Keep it under what a caller will sit through. Three seconds is already a long pause.
Retry attempts	Only for reads. Retrying something that creates a record can create it twice.
Execution mode	Wait for response when the agent needs the answer. Fire and forget when it does not, such as logging a note.

In a conversation, or in a flow

The same API call behaves differently depending on where you use it. As an agent action, the agent decides when to call it, based on your description. It fills the parameters from the conversation. As a step in a flow, the flow decides. It fires when the caller reaches that step, and it fills the values from what the flow has already collected. There is no decision to make and no description to get right. If you drop a tool onto a flow, the message it says while running is copied onto the step, so you can change the wording for that one place without touching the tool everywhere else.

Things that go wrong

Symptom	Usually
The agent invents details the API never returned	The description promises more than the response contains
The agent mentions data you did not expect	No response mapping, so it can see the whole response
A mapped value is empty	The path does not match the response. Check the exact spelling and nesting
The agent calls it at odd moments	The description is too broad. Say when to use it, not only what it does
Long silences	No pre-execution message, or a timeout longer than a caller will wait

​Before you build one

​Name it and describe it well

​Declare your parameters

​Response mapping

​The syntax

​Mapped values stick around

​Say something while it runs

​Handle failure on purpose

​Timeouts, retries and fire-and-forget

​In a conversation, or in a flow

​Things that go wrong

Before you build one

Name it and describe it well

Declare your parameters

Response mapping

The syntax

Mapped values stick around

Say something while it runs

Handle failure on purpose

Timeouts, retries and fire-and-forget

In a conversation, or in a flow

Things that go wrong