> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Call-Start Data Sourcing

> Fetch live data from your CRM or external APIs at the exact moment a call begins, so your voice assistant always has the most up-to-date context.

## Overview

Call-Start Data Sourcing fetches live data from an external system at the moment a call starts and injects it into your voice assistant's context window. This ensures the assistant always has current information — not data that may have gone stale since the call was scheduled.

This works for both **inbound** and **outbound** calls. The same mechanism runs regardless of how the call was initiated.

***

## Why Fetch at Call Start?

* **Inbound calls have no schedule time.** The phone rings and the assistant picks up. There's no advance window to pre-fetch data.
* **Outbound calls risk stale data.** A call scheduled for 2:00 PM might reference CRM data that changed at 1:55 PM.
* **One flow for everything.** A single data-fetching mechanism works for all call types, eliminating divergent code paths.

***

## How It Works

```text theme={null}
Call starts (inbound or outbound)
  -> Voxworks looks up the contact and their linked objects
  -> Finds the automation with call-start config for this Script
  -> Fetches data from the configured source (CRM API or HTTP endpoint)
  -> Maps the response fields to context keys
  -> Validates required fields
  -> Injects the data into the assistant's context window
  -> Call proceeds
```

The entire process completes within a configurable timeout (default: 5 seconds). The assistant waits for the data before beginning the conversation.

***

## Configuring Call-Start Data

Call-Start Data Sourcing is configured on the **Call-Start Data** tab of the automation editor.

### Source

Choose how to fetch the data:

**Integration Fetch** — Use a connected integration (e.g., Monday.com) to fetch data. The system automatically resolves the CRM identifier from the contact's linked objects.

**HTTP** — Fetch from any API endpoint. The URL, method, headers, and body support `{{variable}}` interpolation using the contact's data and linked objects.

### Result Mapping

Map fields from the API response to context keys that the assistant will receive:

| Source Field        | Context Key      |
| ------------------- | ---------------- |
| `source.notes`      | `customer_notes` |
| `source.deal_stage` | `deal_stage`     |
| `source.priority`   | `priority`       |

These keys become available in the assistant's context window during the call.

### Required Fields

Optionally mark fields as required. If a required field is missing or malformed after the data fetch, the call is blocked:

* **Inbound calls** — The call rings out (does not connect)
* **Outbound calls** — The call fails with reason `precall_validation_failed`

Required field validation supports format checks: `email`, `e164` (phone number), `uuid`, or a custom regex pattern.

This is useful when your assistant cannot function without certain CRM data — for example, a customer account ID that's needed to look up order history.

### Timeout

The default timeout is **5 seconds**. You can adjust this per automation. If the source fetch fails or times out, the call proceeds without the enrichment data (best-effort), unless required fields are configured.

***

## One Automation Per Script

Only one automation can provide call-start data sourcing per Script. This is enforced by the system — if you try to configure call-start data on a second automation for the same Script, you'll receive an error.

If a call was created by an automation (e.g., via a Create Call step), that automation's call-start config takes priority over any other.

***

## Failure Behavior

| Scenario                             | Behavior                                            |
| ------------------------------------ | --------------------------------------------------- |
| No call-start config for this Script | Call proceeds normally, no data fetched             |
| API fetch fails or times out         | Call proceeds without enrichment (best-effort)      |
| Required field validation fails      | Call is blocked — inbound rings out, outbound fails |
| Internal error                       | Call proceeds without enrichment                    |

The assistant can always handle a call without enrichment data. Call-start sourcing adds context but should not be the only way the assistant can function — design your Scripts to gracefully handle missing data fields.