Skip to content

Pre Processing

Call-time context

Pre Processing looks up caller information from your external system when a voice call starts. It stores the result as {pre_call_context}, ready for the agent to use during the same conversation.

Use it to support a working call flow, not to rescue one that is still unclear.

Pre Processing is useful when the agent should know something about the caller before it gives the first real answer: customer name, account tier, open ticket status, or other short operational context.

It is different from a tool. A tool runs when the agent chooses to use it during the conversation. Pre Processing is a tenant-level caller lookup that runs automatically at call start.

Where to find it

The tenant menu exposes this area as Pre Processing.

The page configures one Caller Lookup. The lookup uses a single HTTP GET request to your external system.

How it works

When an incoming voice call creates a conversation, Nuvoca starts the lookup.

The greeting still goes out right away. If the lookup is still running when the caller speaks for the first time, the first agent reply waits for it. After the lookup finishes, the saved result is available in prompts as {pre_call_context} for the same conversation.

Use the prompt to decide how the agent should handle the context. The lookup only provides information; it does not define the conversation flow.

When to use Pre Processing

Scenario Good use of Pre Processing
Look up a CRM record by caller number Add customer name or account status before the first answer
Identify priority callers Store a tier, SLA, or priority flag in {pre_call_context}
Personalize a callback flow Let the agent greet known callers more naturally
Check an open ticket or order status Provide a short status hint before the agent asks follow-up questions
Fix an unclear prompt Do not use Pre Processing for this. Fix the prompt first.

Lookup settings

Setting What it does Recommendation
Enable pre-processing lookup Turns the caller lookup on or off Enable only after the basic call flow works
Target URL External endpoint called with HTTP GET Use a stable endpoint that can respond quickly
Timeout (ms) Maximum wait time for the lookup Start with the default unless your system needs more time
OAuth configuration Uses an existing OAuth setup for authentication Prefer this over manually managing authorization headers when available
Response storage Controls what part of the response is saved Use JSON fields for large responses

GET only

Pre Processing uses a single HTTP GET request. There is no POST request and no request body. Send values through query parameters or headers.

Request variables

The UI shows which variables are available for the lookup request. A common first variable is:

  • {caller_phone_number} — the incoming caller phone number for the active voice call

Use request variables in query parameters or non-sensitive headers.

Example query parameter:

Key Value
phone {caller_phone_number}

Headers and OAuth

Headers are sent with the GET request. Use them for normal integration values such as API keys, tenant IDs, or routing information.

Mark API keys or tokens as sensitive header values where the UI allows it. If you select an OAuth configuration, it should handle authorization for the request. Avoid adding duplicate authorization logic unless your integration requires it.

Response storage

Pre Processing can store the response in two ways.

Mode What is stored Best for
Whole response The full response body is stored as {pre_call_context} Short, already-readable responses
JSON fields Selected JSON values are mapped into stored keys Larger JSON responses where only a few fields matter

Whole response

Use Whole response when the external system already returns a short, prompt-friendly result.

Example response:

{
  "name": "Mira Keller",
  "tier": "priority",
  "openTicket": "T-4821"
}

If the response is long or noisy, do not store all of it. Switch to JSON fields.

JSON fields

Use JSON fields when the external system returns more data than the agent needs.

Add one row for each value you want to keep:

Response path Stored key
customer.name caller_name
customer.tier customer_tier
ticket.status ticket_status

Start with two or three fields. Add more only after the prompt uses the first set reliably.

Use {pre_call_context} in the prompt

Add a short section to the agent prompt that explains how to use the lookup result.

## Caller context
If {pre_call_context} contains customer information, use it to personalize the conversation and avoid asking for information that is already known.

If the lookup returned no useful information, continue with the standard callback flow and ask for the caller's name as usual.

Do not mention the lookup itself to the caller.

Keep the fallback explicit. External systems can be slow, empty, or temporarily unavailable.

Testing the lookup

Use Send Test before relying on the lookup in live calls.

The test shows:

  • the configured HTTP request,
  • the response handling,
  • the derived prompt value that would become {pre_call_context}.

If the derived prompt value is too long or hard to read, change response storage before changing the agent prompt.

Common mistakes

Expecting a request body

Pre Processing is GET only. Put values in query parameters or headers.

No fallback for missing context

The prompt should still work if {pre_call_context} is empty. Do not make the entire call flow depend on the lookup succeeding.

Storing too much data

Large CRM responses can distract the agent. Prefer a few mapped JSON fields over a full response when the source system returns many fields.

Using Pre Processing instead of tools

Pre Processing prepares context at the start of the call. It does not send emails, create tickets, or update external systems. Use tools or post-processing for those actions.

Read this next