> For the complete documentation index, see [llms.txt](https://help.sipgate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sipgate.com/documentation/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 varies per call:

* **query current availability**: for example, available appointments or stock levels
* **load CRM data or customer history**
* **daily-updated 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. 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 accessible 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`

For example, use an allowlist for this. This ensures that the server can verify that requests to the endpoint actually 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 → section Data Retrieval at Call Start → gear icon.

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

{% stepper %}
{% step %}
Enter in the dialog **Configure data retrieval** the desired URL.
{% endstep %}

{% step %}
Optionally activate **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 is automatically retrieved for the next incoming call.

### Which response 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 read PDF files, websites, or other file formats directly.

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?

When retrieving data, your agent passes information to the connected server so that suitable data about 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 the agent was called on. If multiple phone numbers are assigned to the agent, only the phone number of the current call is passed.

**`sessionId`**\
The unique ID of the current call. Using this ID, the server can clearly assign the data retrieval to a specific conversation. The `sessionId` can also be used for live integrations. 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 appropriate information in the supported response format.

### Option: “Force retrieval”

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

* **Disabled (default):** If the URL is unavailable, the call is still connected, just without the additional context.
* **Enabled:** If the URL is unavailable, the call is rejected. Only choose this if the context is indispensable, for example if a meaningful conversation is not 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 takes place synchronously at the start of the call; long response times delay the start of the conversation. Retrieval already starts while the phone is 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 canceled and your agent starts the conversation without the requested information. The transcript does not note whether the data retrieval failed.

</details>

<details>

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

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

</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.com/documentation/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.