Pre-Call Data Fetch - Menace Voice

Pre-Call Data Fetch allows you to enrich the call context with external data before the voice agent starts speaking. Configure it on the Start Call node for every call, inbound calls only, or outbound calls only. While the response is loading, the caller hears a ring-back tone. Once the data arrives, it is merged into the call's initial context and becomes available as template variables in your prompts and greetings.

How It Works#

A call arrives (inbound) or is initiated (outbound).
Menace Voice sends a POST request to your configured endpoint with a standardized payload.
The caller hears a ring-back tone while waiting for the response.
Your API responds with a JSON object containing an initial_context object.
The variables are merged into the call's initial context.
The voice agent starts with full access to the fetched data via {{variable_name}} syntax.

You can also set a lookup URL during agent onboarding on the Launch step. That writes the same Start Call fields as the node editor.

Configuration#

Open the Start Call node editor and expand Advanced Settings. Choose a Pre-Call Data Fetch mode and configure the endpoint when the mode is not disabled:

Field	Description
Pre-Call Data Fetch	Disabled, Always, Inbound calls only, or Outbound calls only. Calls without an inbound or outbound direction run the fetch only in Always mode.
Endpoint URL	The URL Menace Voice will send the POST request to.
Authentication	Optional credential for authenticating the request. Supports API key, bearer token, basic auth, and custom header.

Request Format#

Menace Voice sends a POST request with the following JSON payload:

{  "event": "call_inbound",  "call_inbound": {    "agent_id": 123,    "from_number": "+12137771234",    "to_number": "+12137771235"  }}

Field	Description
`event`	Always `"call_inbound"`.
`call_inbound.agent_id`	The workflow (agent) ID.
`call_inbound.from_number`	The caller's phone number (`caller_number` from initial context).
`call_inbound.to_number`	The called phone number (`called_number` from initial context).

The Content-Type header is set to application/json. If you configured a credential, the corresponding authentication header is included.

Expected Response Format#

Your API should return a JSON object with a 2xx status code. The variables to inject into the call context should be placed inside the initial_context key:

{  "call_inbound": {    "initial_context": {      "customer_name": "Jane Doe",      "account_status": "active",      "loyalty_tier": "gold",      "open_tickets": 2    }  }}

You can also place initial_context at the top level:

{  "initial_context": {    "customer_name": "Jane Doe",    "account_status": "active"  }}

Note

The legacy dynamic_variables key is still accepted as a drop-in alias for initial_context, so existing integrations keep working without any changes. Use initial_context for new integrations. If a response contains both keys, initial_context takes precedence.

After the response is received, you can reference these values anywhere template variables are supported:

Greeting: Hello {{customer_name}}, thank you for calling!
Prompt: The customer is a {{loyalty_tier}} member with {{open_tickets}} open support tickets.

Note

If the response is not a valid JSON object, does not contain initial_context (or the legacy dynamic_variables), or the request fails or times out, the call proceeds normally without the additional context. The pre-call fetch never blocks or fails a call.

Nested Variables#

If your initial_context contains nested objects, you can access them using dot notation:

{  "call_inbound": {    "initial_context": {      "customer": {        "name": "Jane Doe",        "address": {          "city": "Los Angeles"        }      }    }  }}

Access in prompts as {{customer.name}} and {{customer.address.city}}.

Timeout#

The request has a 10-second timeout. If your API does not respond within this window, the call proceeds without the fetched data. Design your endpoint to respond as quickly as possible to minimize the ring-back tone duration.

Testing with Test Calls#

When a real phone call comes in, the caller_number and called_number context variables are automatically set by the telephony provider and included in the pre-call data fetch request as from_number and to_number. However, when you make a test call — either a web call (WebRTC) or a phone test call from the workflow editor — these variables are not available by default.

To simulate telephony data during testing:

Open your workflow and go to Settings.
Under Context Variables, add the following variables:
- caller_number — set to a phone number you want to simulate as the caller (e.g., +12137771234).
- called_number — set to the number that would be dialed (e.g., +12137771235).
Save the settings.

Now when you make a test call (web or phone), these values will be sent in the pre-call data fetch request to your endpoint, allowing you to test the full flow as if a real inbound call were coming in.

Note

These context variables are only used during test calls from the workflow editor. On production inbound calls and campaign outbound calls, the actual telephony data is used and these values are ignored.

Example Integration#

A simple Node.js endpoint that looks up a customer by phone number:

app.post("/dograh/pre-call", async (req, res) => {  const { call_inbound } = req.body;  const customer = await db.customers.findOne({    phone: call_inbound.from_number,  });  if (!customer) {    return res.json({});  }  res.json({    call_inbound: {      initial_context: {        customer_name: customer.name,        account_status: customer.status,        loyalty_tier: customer.tier,      },    },  });});