Common issues¶
Quick diagnosis
Start with the symptom, then check the most likely area: prompt, memory, routing, forwarding, tools, knowledge, or voice. Avoid changing everything at once.
The goal is a small fix backed by evidence.
Work from the symptom to the likely cause: identify what went wrong, check the most relevant area, then change one thing and test again.
Common questions about summaries, history, and privacy¶
How do I append the full conversation history to the summary?¶
In Post Processing, open the Summary Prompt tab and enable Append conversation history. Nuvoca appends the full transcript as a separate section after the generated summary.
This is useful for QA, audit, or handoff review. Leave it off for normal inbox delivery when a concise summary is enough, because the transcript can contain personal data and can make emails or webhook payloads much longer.
How do I remove PII from a call?¶
Open Call History, find the completed call, and choose Remove PII from the call's action menu. Afterwards, the record should show PII removed.
This redacts phone numbers and generated notes or call summaries. Billing data, timestamps, and duration remain available.
Why do I still see billing data after removing PII?¶
That is expected. Remove PII removes personal content, while operational metadata such as duration, timestamps, and billing information remains available.
Common questions about context and integrations¶
Where should I put {caller_phone_number}, {conversation_fact_summary}, and {conversation_history}?¶
Put these values into separate runtime blocks in the prompt, not inside long instruction paragraphs. See Prompting and Agent Options for a practical structure.
Important: runtime blocks may be empty. The prompt should say what the agent should do when no caller number, facts, or history are available.
When should I use Pre Processing instead of an API Tool?¶
Use Pre Processing when Nuvoca should automatically look up caller context at the start of an incoming voice call.
Use an API Tool when the agent should decide during the conversation that an external request is needed, such as creating a ticket, checking a status, or sending structured data.
Summary Email or Email Tool?¶
Use Summary Email when every final post-call summary should go to fixed tenant-level recipients.
Use the Email Tool when the agent should decide during the conversation when the handoff is complete and the email should be sent. Use the Email Tool if the destination can change during the conversation, for example when a routing lookup returns an email address that should receive the handoff.
The agent sends an email without a recipient. What should I configure?¶
Configure at least one fixed To recipient, or enable Allow agent-added To recipients and instruct the agent when to pass toRecipients.
For API-driven routing, make the sequence explicit:
First run the routing lookup. If it returns service_email, send the Email Tool with toRecipients set to [service_email]. If no trusted email address is available, do not send the email and continue with the fallback path.
Use agent-added recipients only with trusted routing data, such as an API result or approved prompt context. Do not ask callers for internal company email addresses.
Can the agent add multiple email recipients?¶
Yes. If Allow agent-added To recipients is enabled, the agent can add multiple runtime To recipients. Fixed To recipients are still included.
The agent cannot add CC, BCC, From, subject, or prompt values. CC recipients remain admin-configured.
The agent ignores my prompt¶
Check:
- Is the instruction specific and testable?
- Is it hidden in a long paragraph?
- Does another instruction conflict with it?
- Is the agent missing required information?
- Are you expecting a parameter change to fix a prompt issue?
Fix:
- Rewrite the instruction as a short bullet.
- Add the condition when it applies.
- Add the fallback behavior.
- Test the same scenario again.
The agent invents information¶
Check:
- Does the prompt say what to do when the answer is unknown?
- Is the knowledge base connected and up to date?
- Is the user asking for information that is not in the knowledge base?
Fix:
Add a boundary such as:
If the answer is not available in the knowledge base, say that you are not sure
and offer to collect the caller's details for follow-up.
Routing does not happen at the expected time¶
Check:
- Is the phone number assigned to the right default route?
- Is the routing override enabled?
- Is the routing timezone correct?
- Do the days and times match the expected window?
- Does the time window cross midnight?
- Is another override overlapping?
A call ran too long. How do I limit call duration?¶
Set a maximum AI call duration on the phone number. Treat this as a safety limit that prevents unusually long calls from continuing indefinitely.
Also add a clear closing rule to the prompt. The duration limit stops runaway calls, but the prompt should still tell the agent to finish once the job is done:
When you have answered the question or collected all required callback details, summarize the next step briefly, say goodbye, and end the call.
If calls are regularly reaching the limit, review whether the agent asks too many follow-up questions, gives overly long answers, or lacks a clear completion condition.
Can I forward to a phone number returned by an API?¶
Yes, for workflows where the destination is determined during the conversation. Configure a safe fallback target in the Conference Forwarding tool, and use the prompt to tell the agent when to use the API-provided number.
Example:
Run the routing lookup before forwarding. If it returns a valid transfer_phone_number in E.164 format, forward the caller to that number. If no valid number is available, use the configured fallback forwarding target or collect a callback request.
In the prompt, make it clear that transfer_phone_number is the value returned by your API and should be used as the forwarding number.
Use E.164 phone numbers with country code, such as +49... or +1.... Test both paths: API number available, and fallback when no number is available.
Forwarding does not work¶
Check:
- Is the forwarding tool available to the agent?
- Does the prompt tell the agent when to use it?
- Does the target name match the configured forwarding target?
- Is the phone number in E.164 format?
- Is the timeout long enough?
- Is call screening enabled when the recipient expects direct forwarding, or the other way around?
If the agent should use an API-provided number, also check whether the API Tool returned the number before forwarding and whether the prompt names the fallback behavior.
The agent uses a tool too early¶
Check whether the prompt requires confirmation and required information before tool use. The instruction should say when the tool is allowed, what data is required, and what to do if the data is missing.
Example fixes:
Only send an SMS after the caller has agreed to receive it.
Before sending, repeat the phone number and ask for confirmation.
Use the Email Tool only after name, company, callback number, and reason have been collected. If the email destination comes from routing, run the routing lookup first and do not send the email without a trusted recipient.
Forward the caller only after they ask for a live handoff or the case is urgent. Before forwarding, say that you will try to connect them. If forwarding fails, collect callback details.
The voice sounds wrong¶
Check:
- selected voice,
- language/accent,
- expressiveness,
- speech tempo,
- speaking style availability.
If the content is wrong, fix the prompt or knowledge base first. Voice settings only change how the agent sounds.