Look up caller context

Use pre-processing to look up a caller and any existing request before the conversation. For example, the lookup can use the phone number to find a customer name in your CRM. If you need details from the conversation first, use an API tool.

Configure the lookup

Open Pre Processing and select or create the relevant profile. Enable the lookup and configure:

Setting	Purpose
Target URL	External lookup endpoint
Timeout	Maximum request wait
Authentication	Supported saved credentials or OAuth configuration
Query parameters and headers	Request values, including available variables
Response processing	Whole response, JSON fields or JEXL script

The lookup sends one HTTP GET request. There is no request body. For a lookup by number, a query parameter can use phone with value {caller_phone_number}. Use only variables offered by the editor and allow for a missing caller number.

Select the fields you need

Map a large response to a few fields, for example:

Response path	Stored key
$.customer.name	name
$.customer.tier	tier
$.ticket.status	ticket_status

Use response mapping and JEXL scripts to select the fields your Agent needs.

Use the result in the prompt

Caller lookup:
{pre_call_context}

Use relevant context to avoid asking for known information twice.
Confirm important details with the caller. If no useful context is available,
continue with the standard questions. Do not disclose unrelated account data.

Add {pre_call_context} where you need the result in the system prompt. To address the caller by name in the opening, also set up a personalized greeting.

Access individual fields with dot notation

You can insert individual values from the stored lookup result. A dot moves to the next level of an object. Use [0] for the first item in a list and [1] for the second.

Suppose the processed result contains:

{
  "customer": {"id": "K-1042", "name": "Alex"},
  "orders": [{"id": "B-204", "status": "open"}],
  "vip": true
}

Placeholder	Inserted value
{pre_call_context.customer.name}	Alex
{pre_call_context.customer.id}	K-1042
{pre_call_context.orders[0].status}	open
{pre_call_context.vip}	true
{pre_call_context}	The complete lookup result

These field paths work in the Agent prompt, summary prompt and personalized greeting.

Use the structure after response processing. If you map $.customer.name to the output key name, use {pre_call_context.name} afterwards. The original path customer.name is no longer present. Choose simple output keys such as customer_name, without spaces or hyphens.

A field path must point to text, a number or a boolean. Missing fields, null, whole objects and whole lists produce an empty value when accessed through a field path. Explain in the prompt how the Agent should handle this. In a personalized greeting, a missing value causes Nuvoca to use the standard greeting.

Test before assignment

Use Send Test with test values. Inspect request, raw result, processed context and any greeting preview. It sends a real lookup request. Use transformation previews for changes that only affect response processing.

Test a known caller, an unknown caller, missing fields and a timeout. Save the intended profile assignment and verify a fresh incoming call. The conversation must remain usable when the lookup has no result.