Available tools

The assistant picks these tools on its own based on what you ask. You don't need to call them by name, but knowing what each one does helps you write better requests.

All tools work on the company of the user who authorized the app.

Company

getCompany

Returns the id, name and slug of your company. Read-only.

Agents

listAgents

Lists your voice and WhatsApp agents, ordered by name, with each agent's name and slug. Read-only.

Parameter	Type	Description
search	string, optional	Text to match in the agent name or slug, e.g. "sales". Case-insensitive.
page	integer, optional	Page number. Default 1.
limit	integer, optional	Page size. Default 50, max 100.

getAgent

Returns one agent's configuration: voice prompt, text (WhatsApp) prompt, greeting, voice, recall and retry logic, working hours, transfer destinations, output variables, knowledge base files and tools. Secrets and credentials are never included. Read-only.

It also returns:

• inputVariables: the {{placeholders}} the voice prompt and greeting use, so the assistant knows what to send with startCall.
• updatedAt: used by updateAgent to avoid overwriting someone else's changes.

Parameter	Type	Description
slug	string, required	Agent slug, as returned by listAgents.

createAgent

Admins only. Creates a new voice agent in your company and returns it, in the same shape as getAgent (including updatedAt). It works like creating an agent from the dashboard or the Create agent API.

Parameter	Type	Description
name	string, required	Display name.
prompt	string, required	Voice prompt. Use {{variable}} placeholders for data that changes per call.
voiceId	string, required	Voice to use, as returned by listVoices.
greeting	string, optional	First message the agent says.
farewell	string, optional	Message said before hanging up.
outputVariables	array, optional	Data the agent captures from each call. Max 50.

To set the text/WhatsApp prompt, working hours or other settings, the assistant calls updateAgent right after with the returned updatedAt. Phone numbers, knowledge base files, tools and webhooks are configured in the dashboard.

To avoid duplicates, Fonema rejects the request if:

• An agent with the same name was created in the last 10 minutes (usually a retry). The assistant is told to update that agent or pick another name.
• The connection has already created 20 agents in the last hour.

updateAgent

Admins only. Updates one agent. Only the fields sent are changed, and the change is published immediately, the same as publishing from the dashboard.

Parameter	Type	Description
slug	string, required	Agent slug.
expectedUpdatedAt	string, required	The updatedAt from getAgent. The update fails if the agent changed since, so nobody's edits are lost.
name	string	Display name. The slug doesn't change.
prompt	string	Full new voice prompt.
promptEdits	array	Small find-and-replace edits to the voice prompt. Each find must appear exactly once.
textPrompt	string	Full new text/WhatsApp prompt.
textPromptEdits	array	Find-and-replace edits to the text prompt.
greeting	string	First message the agent says.
farewell	string	Message said before hanging up.
outputVariables	array	Replaces the whole list of captured variables.
workingHours	object	Replaces the working hours (ALL_DAY or CUSTOM with time windows per weekday).
allowReturnCall	boolean	Whether customers can call the agent back.

Send either prompt or promptEdits, not both (same for textPrompt).

tip

Ask the assistant to show you the change before applying it, for example: "Suggest a new greeting for my sales agent and wait for my OK before updating it."

Voices

listVoices

Lists the voices available for your agents, including your company's custom voices. Each voice includes its voiceId, name, country, language, sex, a short detail and a sample audio URL. Read-only.

Parameter	Type	Description
language	string, optional	Text to match in the language, e.g. "spanish". Case-insensitive.
country	string, optional	Text to match in the country, e.g. "mexico". Case-insensitive.

Use the voiceId with createAgent.

Calls

listCalls

Lists inbound and outbound calls, newest first. Read-only. Each call includes its uid, agent, numbers, direction, timing, duration, ended reason, success evaluation, input variables and a short summary.

Parameter	Type	Description
phoneNumber	string, optional	Customer number with country code, e.g. "+5215512345678".
agent	string, optional	Agent slug.
startDate	string, optional	Calls created at or after this time. ISO 8601 with UTC offset, e.g. "2026-09-23T00:00:00-06:00".
endDate	string, optional	Calls created at or before this time.
page	integer, optional	Page number. Default 1.
limit	integer, optional	Page size. Default 20, max 50.

Filters are combined, so agent + startDate returns only that agent's calls since that date.

getCall

Returns one call with its full end-of-call analysis (summary, success evaluation, captured data) and the transcript in time order. The transcript includes the customer and agent turns plus the tools the agent ran during the call (tool_call and tool_result entries). Read-only.

Parameter	Type	Description
uid	string, required	Call uid, as returned by listCalls.

The recording itself is not returned; hasRecording tells you whether one exists.

startCall

Places an outbound call from one of your agents. The call is queued and dialed within about a minute, following the same rules as the Calls API: working hours, retries and throttling all apply.

Parameter	Type	Description
agent	string, required	Agent slug.
phoneNumber	string, required	Customer number with country code, e.g. "+5215512345678". A 10-digit number without + uses the agent's default country code.
name	string, optional	Customer name, available to the prompt.
email	string, optional	Customer email, available to the prompt.
variables	object, optional	Input variables for the prompt, without braces: { "policy": "123" }. Max 50.
delayMinutes	integer, optional	Wait before calling. Default 0, max 10080 (7 days).

The response tells the assistant:

• callAt: when the call is scheduled.
• outsideWorkingHours and nextAvailableAt: if the time falls outside the agent's working hours, when it will actually be dialed.
• missingVariables: prompt variables that were not sent.

Before queuing, Fonema checks that:

• The agent has a voice prompt.
• Your account's billing is active.
• There isn't already a pending call from the same agent to the same number.
• The connection hasn't started more than 10 calls in the last 10 minutes.

Once dialed, the call shows up in listCalls.