Skip to main content

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. Tools marked Admins only are not offered to operators at all.

Tools that return lists are paginated and also return total, page, limit and totalPages.

Company​

getCompany​

Returns the 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.

ParameterTypeDescription
searchstring, optionalText to match in the agent name or slug, e.g. "sales". Case-insensitive.
pageinteger, optionalPage number. Default 1.
limitinteger, optionalPage 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 (the agent's skills, each with its id). 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 and the skill tools to avoid overwriting someone else's changes.
ParameterTypeDescription
slugstring, requiredAgent 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.

ParameterTypeDescription
namestring, requiredDisplay name.
promptstring, requiredVoice prompt. Use {{variable}} placeholders for data that changes per call.
voiceIdstring, requiredVoice to use, as returned by listVoices.
greetingstring, optionalFirst message the agent says.
farewellstring, optionalMessage said before hanging up.
outputVariablesarray, optionalData the agent captures from each call. Max 50. See Output variables.

To set the text/WhatsApp prompt, working hours or other settings, the assistant calls updateAgent right after with the returned updatedAt. To add skills, it calls addAgentSkill. Phone numbers, knowledge base files 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 and returns it with its new updatedAt. Only the fields sent are changed, and the change is published immediately, the same as publishing from the dashboard.

ParameterTypeDescription
slugstring, requiredAgent slug.
expectedUpdatedAtstring, requiredThe updatedAt from getAgent. The update fails if the agent changed since, so nobody's edits are lost.
namestringDisplay name. The slug doesn't change.
promptstringFull new voice prompt.
promptEditsarrayUp to 20 small find-and-replace edits to the voice prompt, each { "find": "...", "replace": "..." }. Each find must appear exactly once; an empty replace deletes the text.
textPromptstringFull new text/WhatsApp prompt.
textPromptEditsarrayUp to 20 find-and-replace edits to the text prompt.
greetingstringFirst message the agent says.
farewellstringMessage said before hanging up.
outputVariablesarrayReplaces the whole list of captured variables. Max 50. See Output variables.
workingHoursobjectReplaces the working hours: type ALL_DAY or CUSTOM, and availability with up to 10 { "start": "09:00", "end": "18:00" } windows (24-hour HH:mm, agent timezone) per weekday. Days left out are unavailable.
allowReturnCallbooleanWhether customers can call the agent back.

Send either prompt or promptEdits, not both (same for textPrompt). At least one field besides slug and expectedUpdatedAt is required.

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."

Output variables​

createAgent and updateAgent take output variables in the same shape getAgent returns them:

FieldTypeDescription
namestring, requiredVariable name, up to 100 characters.
valuestring, requiredData type: string, number, boolean or enum.
descriptionstring, requiredWhat to capture, up to 1,000 characters.
enumarray, optionalAllowed values, 1 to 50. Required when value is enum.
idstring, optionalKeep the id from getAgent; omit it for new variables.
shouldUpdateInputDataboolean, optionalKeep the value from getAgent; omit it to keep the stored one.

Agent skills​

Skills are functions an agent can use during calls or chats. They appear in getAgent as tools, each with an id. These tools add, change or remove one skill at a time and leave the agent's other skills untouched.

All three are Admins only, need the updatedAt from getAgent as expectedUpdatedAt, and fail if the agent changed since. Each one returns the agent's skills (tools) and its new updatedAt.

They work on three skill types:

  • EMAIL: sends an email from info@fonema.ai.
  • GPT_CALL: asks a separate GPT model and returns its answer to the agent.
  • PHONE_CALL: for WhatsApp and web chat agents only. Schedules a phone call from one of your voice agents to the person in the conversation.

API call, HubSpot, Google Calendar, WhatsApp template and custom skills are configured in the dashboard; these tools cannot change or remove them.

addAgentSkill​

Admins only. Adds a skill to one agent. Returns the agent's skills, the new skill's skillId and the new updatedAt.

ParameterTypeDescription
slugstring, requiredAgent slug.
expectedUpdatedAtstring, requiredThe updatedAt from getAgent.
skillobject, requiredThe skill. See the fields below.

Fields of skill, for every type:

FieldTypeDescription
typestring, requiredEMAIL, GPT_CALL or PHONE_CALL.
namestring, requiredFunction name the agent sees, e.g. send_quote_email. Up to 64 characters; letters, digits, _ and - (anything else becomes _). Must be unique within the agent.
descriptionstring, requiredWhen the agent should use the skill and what it does, up to 1,000 characters. The agent decides from this.
parametersarray, optionalUp to 30 arguments the agent passes when it uses the skill. See Skill parameters.

Fields by type:

TypeFieldDescription
EMAILtoRequired. 1 to 20 recipients. Each one is an email address or a single {{parameter}}.
EMAILsubjectRequired. Up to 500 characters. Supports {{parameter}} placeholders.
EMAILhtmlRequired. Email body, up to 20,000 characters. Plain text or simple HTML; line breaks are kept. Supports {{parameter}} placeholders.
EMAILreplyToOptional. Reply-To address or a single {{parameter}}.
GPT_CALLpromptRequired. Instruction for the GPT model, up to 20,000 characters. Its answer goes back to the agent. Supports {{parameter}} placeholders.
EMAIL, GPT_CALLrequestStartMessageOptional. Short phrase said on voice calls as soon as the skill starts, up to 300 characters, e.g. "One moment, I'm sending you the email."
PHONE_CALLvoiceAgentSlugRequired. Slug of the voice agent in your company that places the call.
PHONE_CALLtimingOptional. NOW (default) dials right away, DELAY waits delayMinutes, REQUESTED calls at the time the person asks for (right away if they don't ask).
PHONE_CALLdelayMinutesMinutes to wait, from 1 to 10080 (7 days). Required with DELAY, not allowed otherwise.

Every {{placeholder}} in the skill text needs a matching parameter, or the skill is rejected.

tip

Mention the skill in the agent's prompt if it should be used at a specific moment, for example "Use send_quote_email after the customer confirms their email."

updateAgentSkill​

Admins only. Changes one EMAIL, GPT_CALL or PHONE_CALL skill. Only the fields sent change, and the skill type cannot change. Returns the agent's skills, the skillId and the new updatedAt.

ParameterTypeDescription
slugstring, requiredAgent slug.
expectedUpdatedAtstring, requiredThe updatedAt from getAgent.
skillIdinteger, requiredThe skill's id in getAgent tools.
namestringNew function name.
descriptionstringNew description.
parametersarrayReplaces the whole list of parameters.
requestStartMessagestringEMAIL and GPT_CALL. An empty string removes it.
to, subject, html, replyToEMAIL only.
promptstringGPT_CALL only.
voiceAgentSlug, timing, delayMinutesPHONE_CALL only. Changing timing away from DELAY clears delayMinutes.

The fields follow the same rules as in addAgentSkill. Sending a field that doesn't belong to the skill's type fails.

removeAgentSkill​

Admins only. Deletes one EMAIL, GPT_CALL or PHONE_CALL skill from an agent. Returns the remaining skills and the new updatedAt.

ParameterTypeDescription
slugstring, requiredAgent slug.
expectedUpdatedAtstring, requiredThe updatedAt from getAgent.
skillIdinteger, requiredThe skill's id in getAgent tools.

If the agent's prompt mentions the skill, update the prompt too.

Skill parameters​

FieldTypeDescription
namestring, requiredArgument name without braces, up to 64 letters, digits or _. Used as {{name}} in the skill text. Each name only once.
typestring, requiredstring, number or boolean.
descriptionstringWhat the agent should fill in, up to 500 characters. Required unless alreadyExists is true.
alreadyExistsboolean, optionaltrue fills the value from the call or contact input variable with the same name (see inputVariables in getAgent) instead of asking the agent for 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. Also returns total. Read-only.

ParameterTypeDescription
languagestring, optionalText to match in the language, e.g. "spanish". Case-insensitive.
countrystring, optionalText 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 (name and slug), toNumber, fromNumber, direction, createdAt, startAt, endAt, durationSeconds, endedReason, successEvaluation, inputData and a summary of up to 500 characters.

ParameterTypeDescription
phoneNumberstring, optionalCustomer number with country code, e.g. "+5215512345678". Spaces and dashes are ignored. A Mexican number matches whether it was stored with or without the 1 after 52.
agentstring, optionalAgent slug.
startDatestring, optionalCalls created at or after this time. ISO 8601 with UTC offset, e.g. "2026-09-23T00:00:00-06:00".
endDatestring, optionalCalls created at or before this time.
pageinteger, optionalPage number. Default 1.
limitinteger, optionalPage size. Default 20, max 50.
direction, successEvaluation, outcome, endedReason, outputoptionalSee Call filters. These need both startDate and endDate, at most 30 days apart.

Filters are combined, so agent + startDate returns only that agent's calls since that date. To count calls or customers, the assistant uses getCallStats instead of paging through listCalls.

getCallStats​

Counts calls and adds up their duration and cost, optionally grouped by up to two dimensions. The assistant uses it for totals, breakdowns and trends, such as "How many calls did each agent make last week?" or "Daily calls this month, successful vs. not". Read-only.

ParameterTypeDescription
startDatestring, requiredCalls created at or after this time. ISO 8601 with UTC offset.
endDatestring, requiredCalls created at or before this time. At most 30 days after startDate.
timeZonestring, optionalIANA timezone for the hour, day and week groups, e.g. "America/Mexico_City". Default UTC.
agentstring, optionalOnly this agent's calls (slug).
direction, successEvaluation, outcome, endedReason, outputoptionalSee Call filters.
groupByarray, optionalUp to two different dimensions, at most one of hour, day and week. Omit it for a single total.
contactMetricsboolean, optionaltrue adds per-person counts. Default false. See below.

Dimensions for groupBy:

DimensionGroups by
hour, day, weekTime, in timeZone. Weeks start on Monday. Periods with no calls are included as zero.
agentAgent. Adds two columns, agent (name) and agentSlug.
directioninbound or outbound.
successEvaluationtrue, false (includes voicemails) or null (not evaluated).
outcomeanswered, voicemail, no-answer, busy, other or unknown. See Call filters.
endedReasonThe raw ended reason.
{ "output": "key" }A captured output variable, e.g. { "output": "isInterested" }. Values are lower-cased; null means not captured.

The result is compact: columns names the values in each entry of rows (dimensions first, then metrics), and totals holds the metrics for the whole range. It also returns timeZone and currency (USD). Metrics:

MetricMeaning
countNumber of calls.
totalDurationSeconds, avgDurationSecondsTotal and average call duration.
costWhat your company is charged for the calls, in USD. Equals fonemaCost + telephonyCost.
fonemaCostFonema's per-minute price.
telephonyCostCarrier cost.
avgCostAverage cost per call.
costPerMinuteCost per minute of talk time.

Costs from the last hour can still change, because carrier prices arrive after the call.

Contact metrics. Call counts include retries, so one customer often counts several times. With contactMetrics: true, every row and totals also include:

MetricMeaning
uniqueContactsDistinct customers with at least one call.
contactsReachedDistinct customers with at least one answered call.
contactsSuccessfulDistinct customers with at least one call evaluated as successful.

The customer is the call's toNumber, in both directions, compared by digits only; a Mexican number with or without the 1 after 52 counts as one customer. Filters apply to the calls first. These are distinct counts, so rows don't add up: a customer called on two days, or by two agents, counts in both rows. Read the whole range from totals. totals.callsWithoutContact counts the calls left out because they have no customer number (web calls, or calls whose customer data was deleted).

Limits:

  • A result can have at most 1,000 rows. If a grouping would produce more, the tool asks for a coarser time period, fewer dimensions or more filters.
  • A query that runs longer than 90 seconds is stopped. The assistant is told to narrow it: one agent, a shorter range or fewer output filters.

Call filters​

listCalls and getCallStats share these optional filters. They combine with AND, and they need a startDate and endDate at most 30 days apart.

FilterTypeDescription
directionstringinbound or outbound.
successEvaluationbooleantrue = calls evaluated as successful, false = evaluated as unsuccessful. Voicemails are evaluated as false, so false is mostly calls nobody answered; combine it with outcome: ["answered"] for conversations that did not succeed. Calls without an evaluation match neither.
outcomearrayHow the call ended: answered (the customer was on the line), voicemail, no-answer, busy, other (errors, failed or canceled calls) or unknown (no end reason yet, e.g. still in progress).
endedReasonarrayUp to 20 exact ended reasons, e.g. "customer-ended-call". outcome is usually simpler.
outputarrayUp to 5 filters on the captured output variables, each { "key": "...", "op": "...", "value": "..." }. key is the output variable name as it appears in getAgent.

Operators for output:

opMatches
eqThe value equals value (case-insensitive).
neqThe value is different from value, or was not captured.
containsThe value contains value (case-insensitive).
isTrueA yes-like value, such as true, yes or 1.
isFalseA no-like value, such as false, no or 0.
existsThe variable was captured and is not empty.

eq, neq and contains need a value (up to 200 characters).

getCall​

Returns one call with its full end-of-call analysis (summary, success evaluation, captured data) and the transcript in time order, with seconds from the start of the call. The transcript includes the customer and agent turns plus the tools the agent ran during the call: a tool_call entry has the tool name and arguments, and its tool_result entry (same id) can come later, after more conversation, because the call continues while a tool runs. Tool results longer than 2,000 characters are cut. Read-only.

ParameterTypeDescription
uidstring, requiredCall 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.

warning

startCall dials a real phone number and the call is billed like any other call. It cannot be undone once dialed, so most apps ask you to confirm before running it.

ParameterTypeDescription
agentstring, requiredAgent slug.
phoneNumberstring, requiredCustomer number with country code, e.g. "+5215512345678". Spaces, dashes, dots and parentheses are ignored. A 10-digit number without + uses the agent's default country code.
namestring, optionalCustomer name, available to the prompt.
emailstring, optionalCustomer email, available to the prompt.
variablesobject, optionalInput variables for the prompt, without braces: { "policy": "123" }. Max 50. Names use letters, digits and _; values are text (up to 2,000 characters), numbers or booleans.
delayMinutesinteger, optionalWait 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.
  • If your account places calls through your own SIP trunk, the agent has a SIP trunk number.
  • 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.

WhatsApp and web chat​

listWhatsappContacts​

Lists the people who chatted with your WhatsApp and web chat agents, most recent message first. Read-only.

Each contact includes:

  • contactId: use it with getWhatsappConversation.
  • name, number, channel (whatsapp or web) and agent (the agent's slug).
  • lastMessageAt and lastMessage: who sent it (customer or agent), its type, the first 200 characters and when it was sent.
  • tag: the contact's tag, if any.
  • inputData: what is known about the contact: campaign or Excel variables, data the agent captured and sessionSummaries of past conversations.
ParameterTypeDescription
phoneNumberstring, optionalCustomer number with country code, e.g. "+5215512345678". Spaces and dashes are ignored. A Mexican number matches with or without the 1 after 52.
searchstring, optionalPart of the contact's name or digits of the number. Case-insensitive.
agentstring, optionalAgent slug.
startDatestring, optionalContacts whose last message is at or after this time. ISO 8601 with UTC offset, e.g. "2026-11-03T00:00:00-06:00".
endDatestring, optionalContacts whose last message is at or before this time.
pageinteger, optionalPage number. Default 1.
limitinteger, optionalPage size. Default 20, max 50.

Filters are combined with AND.

getWhatsappConversation​

Returns one WhatsApp or web chat contact (in the same shape as listWhatsappContacts) and its messages, oldest first: what the customer wrote and what the agent answered. Read-only.

Each message includes its id, who sent it (customer or agent), its type, its content (cut at 4,000 characters) and sentAt. Agent messages also include WhatsApp's deliveredAt and readAt when known, and the tools the agent ran for that answer (name, arguments and output, cut at 2,000 characters).

ParameterTypeDescription
contactIdinteger, requiredContact id, as returned by listWhatsappContacts.
limitinteger, optionalNumber of messages to return, starting from the most recent. Default 50, max 200.
beforeIdinteger, optionalOnly messages older than this message id.

When hasMore is true, there are older messages: the assistant passes nextBeforeId as beforeId to read them.