> 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 ### When does this make sense? Retrieving data when the call starts is suitable for content that changes frequently or differs from call to call. Typical use cases: * **Current availability** querying (e.g. free appointments, stock levels) * **CRM data** or loading customer history * **Daily up-to-date instructions** (e.g. special opening hours, promotions) * **Past interactions** make available to the caller {% hint style="info" %} **Note:** The initial 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. For permanent agent knowledge, use file upload in the **Knowledge**. {% endhint %} ### Requirements * A URL accessible via HTTP or HTTPS (HTTPS recommended). * The endpoint should respond quickly; retrieval occurs when the call starts. * The response is embedded as text in the conversation context. Ideally, return well-structured, concise content. {% 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. This ensures that requests to the endpoint really come from sipgate. {% endhint %} {% hint style="info" %} **Note:** The server response should contain only data. Prompt instructions or behavior rules should not be passed via the server response. They are ignored or not processed reliably. {% endhint %} ### How to set up data retrieval {% stepper %} {% step %} **Open the configuration of your AI Agent** {% endstep %} {% step %} **Go to the “Integrations” menu item** {% endstep %} {% step %} **Find the “Data retrieval when call starts” section and click the gear icon** {% endstep %} {% step %} **In the “Configure data retrieval” dialog, enter the desired URL.** Optionally, you can also enable “Force retrieval” so that the retrieval must succeed for the call to take place at all {% endstep %} {% step %} **Click “Save”** {% endstep %} {% endstepper %} The configured URL will then appear directly in the interface. On the next incoming call, the content will be retrieved automatically. ### Which return formats does the Agent support? The Agent can only process information from third-party applications if it is returned in a readable text format. The Agent cannot read PDF files, websites, or other file formats directly. **Supported:** Plain text, Markdown, JSON The desired return format must be specified in the request to the third-party application. The connected server must return the response in this format and the appropriate [`Content-Type`-header ](ttps://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Type)set. 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 the initial data retrieval, the Agent can pass information to the connected server so that suitable data about the current call or previous conversations can be found there. The following parameters are passed: ```json { "callerNumber": "+4915XXXXXXXXX", "destinationNumber": "4930xxxxxxx", "sessionId": "pbx-", "assistantId": "" } ``` **`callerNumber`**\ The phone number of the person calling. **`destinationNumber`**\ The phone number the Agent was called on. If multiple 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 connections. This means the server can 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 the checkbox **Force retrieval** you decide how strictly the Agent should handle errors in this retrieval: * **Disabled** (Default): If the URL is unavailable, the call is still connected — simply without the dynamic context. * **Enabled:** If the URL is unavailable, the call is rejected. Only choose this option if the context is essential for the call (e.g. if a meaningful conversation is not possible without CRM data). ### Remove data retrieval again If data retrieval should no longer take place: 1. Open the configuration dialog again via the gear icon. 2. Click **Delete data retrieval**. 3. In the following dialog, confirm with **Delete permanently**. Afterwards, the section will again show the status **Inactive**. No more data retrieval will take place for future calls. ### Frequently asked questions
How long may the endpoint take to respond? As short as possible. Data retrieval occurs synchronously at the start of the call. Long response times can therefore delay the start of the conversation. Retrieval starts while the phone is still ringing and usually takes 2–5 seconds. If no data is available after 5 seconds, the Agent continues the conversation without this information. **What happens if the 5 seconds are exceeded?** If the endpoint does not respond within 5 seconds, the data retrieval is canceled. The Agent then starts the conversation without the requested information. This can happen, for example, if the connected third-party application responds slowly. The transcript does not note whether the data retrieval failed.
What happens if I change the URL? The new URL is automatically retrieved on the next incoming call. There is no cache that needs to be cleared beforehand.
Does it work with any URL? The URL must be accessible 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.
--- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.sipgate.com/documentation/en/connections-and-integrations/datenabruf-bei-anrufbeginn.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.