> For the complete documentation index, see [llms.txt](https://help.sipgate.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sipgate.de/ai-agents/en/connections-and-integrations/datenabruf-bei-anrufbeginn.md).

# Data retrieval at call start

With data retrieval at call start, your agent retrieves a URL you have stored as soon as an incoming call starts. The response is then available to them during the conversation.

### When does this make sense?

Data retrieval is suitable for content that changes frequently or differs per call:

* **query current availability**: for example, available appointments or stock levels
* **load CRM data or customer history**
* **same-day instructions:** for example, special opening hours or promotions
* **past interactions** with the caller **make available**

{% hint style="info" %}
Data retrieval is intended for specific information about the current call. It does not replace a general knowledge base and is not suitable for extensive content such as PDFs, websites, or documentation. You store lasting knowledge in the knowledge base.
{% endhint %}

### Requirements

* a URL that can be reached via HTTP or HTTPS, HTTPS recommended
* an endpoint that responds quickly, because retrieval happens when the call starts
* compact, well-structured content, because the response is embedded as text in the conversation context

{% hint style="warning" %}
**Important:** Do not use a publicly discoverable URL. At present, there is no authentication between sipgate and the connected server. Otherwise, unauthorized third parties could use the endpoint and retrieve transmitted caller data.

Restrict access server-side to the following sipgate IP addresses:

* `217.116.118.254`
* `212.9.46.32`

Use an allowlist for this, for example. This ensures that the server knows that requests to the endpoint really come from sipgate.
{% endhint %}

{% hint style="info" %}
**Note:** The server's response should contain only data. Prompt instructions or behavioral rules are ignored or not processed reliably.
{% endhint %}

### How to set up data retrieval

#### Where can I find data retrieval?

* **sipgate sona:** Open the agent overview and drag and drop Data retrieval at call start from the library in the sidebar onto your agent.
* **AI Agents:** Open your agent's configuration → menu item Integrations → Data retrieval at call start section → gear icon.

{% hint style="info" %}
**Note:** As long as no data retrieval is configured, no card for it will appear in the agent overview either. That is why you always create the first data retrieval via the library.
{% endhint %}

{% stepper %}
{% step %}
In the dialog **configure data retrieval** enter the desired URL.
{% endstep %}

{% step %}
Optionally enable **force retrieval**, so that the retrieval must succeed before the call takes place.
{% endstep %}

{% step %}
Click **Save**.
{% endstep %}
{% endstepper %}

The configured URL then appears in the user interface. The content will be retrieved automatically for the next incoming call.

### Which return formats does the agent support?

Your agent only processes information from third-party applications if it is returned in a readable text format. It cannot directly read PDF files, websites, or other file formats.

Plain text, Markdown, and JSON are supported. The desired format must be specified in the request, and the connected server must set the appropriate `Content-Type`header:

Examples:

* Plain text: `Content-Type: text/plain`
* Markdown: `Content-Type: text/markdown`
* JSON: `Content-Type: application/json`

### Which parameters are passed to the server?

During data retrieval, your agent passes information to the connected server so that suitable data for the current call can be found there:

```json
{
  "callerNumber": "+4915XXXXXXXXX",
  "destinationNumber": "4930xxxxxxx",
  "sessionId": "pbx-<RANDOM_UUID>",
  "assistantId": "<ASSISTANT_ID>"
}
```

**`callerNumber`**\
The caller's phone number.

**`destinationNumber`**\
The phone number that the agent was called on. If multiple phone numbers are assigned to the agent, only the number of the current call is still passed.

**`sessionId`**\
The unique ID of the current call. This ID allows the server to unambiguously assign the data retrieval to a specific conversation. The `sessionId` can also be used for live connections. This allows the server to recognize the same call across multiple queries, for example between the initial data retrieval and later live queries during the conversation.

**`assistantId`**\
The internal ID of the agent. This ID is uniquely assigned to an agent and helps the server distinguish between multiple agents.

The connected server must be able to process these parameters and provide the relevant information in the supported return format.

### Option: “Force retrieval”

With this checkbox, you determine how strictly your agent handles errors:

* **Disabled (default):** If the URL cannot be reached, the call is still connected, simply without the additional context.
* **Enabled:** If the URL cannot be reached, the call is rejected. Only choose this if the context is indispensable, for example if no meaningful conversation is possible without CRM data.

### Remove data retrieval again

1. Open the configuration dialog again.
2. Click **Delete data retrieval**.
3. Confirm with **Delete permanently**.

For future calls, no data retrieval will take place anymore.

### Frequently asked questions

<details>

<summary><strong>How long may the endpoint take to respond?</strong></summary>

As short as possible. Data retrieval occurs synchronously at the start of the call; long response times delay the start of the conversation. Retrieval begins while the phone is already ringing and usually takes 2 to 5 seconds.

**What happens if the 5 seconds are exceeded?**

If the endpoint does not respond within 5 seconds, the retrieval is aborted and your agent starts the conversation without the requested information. The transcript does not record whether the data retrieval failed.

</details>

<details>

<summary><strong>What happens if I change the URL?</strong></summary>

The new URL is automatically retrieved on the next incoming call. There is no cache that needs to be cleared beforehand.

</details>

<details>

<summary><strong>Does it work with any URLs?</strong></summary>

The URL must be reachable via HTTP or HTTPS and contain a valid top-level domain. Entries without a protocol such as `my-company.de` are automatically supplemented with `https://` when saved.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.sipgate.de/ai-agents/en/connections-and-integrations/datenabruf-bei-anrufbeginn.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.