Actions

Let the agent reach into your own systems mid-call — look up an order, check stock, create a ticket — without writing any code on our side.

For: Someone with access to your API

On this page

What this looks like on a call
Who this page is for
Creating an action
Placeholders
Security
Design notes for your endpoint
Limits and gotchas

Out of the box the agent can talk, answer from your knowledge base, book appointments and transfer calls. Actions extend that to anything with a web API: your order system, your stock database, your ticketing tool.

You describe the endpoint once. The agent decides on its own when a conversation needs it.

Agent → Actions

What this looks like on a call

Caller: Hi, I'm chasing order 40921. Agent: Let me check that for you… (calls your order API) …that one shipped on Tuesday and it's due with you tomorrow. Do you want the tracking number by text?

The agent worked out that the caller's question needed the order lookup, extracted the order number from speech, called your endpoint, and turned the JSON response into a spoken sentence. You wrote the endpoint definition; you didn't write any of that logic.

Who this page is for

Setting up an action needs someone who knows your API — the URL, the auth header, the shape of the request. It's the one genuinely technical corner of the product. Everything else in Vocallie is click-and-type.

If you don't have an API, you probably want CRM actions instead, which give the agent the same kind of abilities against Vocallie's own CRM with no setup.

Creating an action

1
Name it
A machine name like lookup_order or check_stock. This is what the AI sees, so make it descriptive — the name is part of how it decides which action fits the moment.
2
Describe when to use it
Purpose is a one-line description. When to call is one condition per line:
```
the caller asks about the status of an existing order
the caller gives an order number and wants an update
```
This matters more than it looks. Vague descriptions produce an agent that calls your API at strange moments, or fails to call it when it should.
3
Define the parameters
Each piece of information the agent must collect from the caller before it can run the action. Give each a name, a type (text, number, or yes/no), whether it's required, and a description.
The description tells the agent what it's asking the caller for — order_id: "the order number, usually five digits, printed on their confirmation email".
4
Point it at your endpoint
The HTTP method, the URL, and any headers (one key: value per line — this is where your API key goes).
Parameters are substituted into the URL with double braces:
```
https://api.yourshop.com/orders/{{order_id}}
```
For POST and PUT requests you can also supply a JSON body template using the same placeholders.
5
Choose which agents get it
If you have more than one agent, a picker appears. Leave everything selected and the action is available to all agents, including ones you create later. Deselect to keep a sensitive action — a refund, say — off a customer-facing agent.
6
Test it
The play button asks you for a value for each parameter and runs the real call, showing you the response.
Careful
The test performs a real request. If your action creates a refund or deletes something, the test will genuinely do that. Point tests at a sandbox endpoint where it matters.

Placeholders

Two kinds are available in the URL, headers and body:

Placeholder	Value
`{{param_name}}`	Whatever the agent collected from the caller for that parameter.
`{{__tenantId}}`	Your workspace id — useful if your endpoint serves multiple customers.
`{{__roomName}}`	An identifier for this specific call.
`{{__timestamp}}`	When the call was made.
`{{__functionName}}`	The name of the action being run.

A placeholder that doesn't match anything renders as an empty string, not an error — so a typo produces a silently malformed URL. This is exactly what the test button is for.

Security

Because you control the URL, actions are a potential route into infrastructure that shouldn't be reachable. Every request — from the test button and from live calls alike — goes through a guarded HTTP client that:

Blocks private, loopback and link-local addresses, including ones reached through DNS.
Re-checks the destination on every redirect, so a redirect can't smuggle a request somewhere blocked.
Validates the address at the moment of connection, closing the gap where DNS could change between check and connect.
Refuses anything that isn't HTTP or HTTPS, and caps how much data comes back.

If you point an action at something internal, it fails with a "blocked" error rather than going through. That's deliberate.

Note

Your endpoint should be quick. Requests time out after about 8 seconds — a caller is waiting on the line, so an API that takes 30 seconds isn't usable here regardless.

Design notes for your endpoint

Return small, readable JSON. The response is handed to the agent to turn into speech. A tidy {"status": "shipped", "eta": "tomorrow"} produces a good sentence; a 200-field object produces a confused one.
Return an error message the agent can say. If the order isn't found, a response like {"error": "no order with that number"} lets the agent recover gracefully. A bare 500 leaves it guessing.
Don't require anything the caller can't say out loud. A UUID is not a workable parameter; an order number is.

Limits and gotchas

Editing an existing action is limited. Once created, the panel only lets you change which agents it applies to. To change the URL, parameters or headers, delete and recreate it.
Deselecting every agent means no agent gets it. The list will show "None" — easy to misread as "all".
Names must be unique within your workspace. Creating a second action with the same name fails with an unhelpful generic error; if a save mysteriously fails, check for a name clash.
Failures are handled, not fatal. If your endpoint is down, the agent is told the call failed and carries on the conversation — it doesn't hang up on your caller.