Data Retrieval at Call Start

With data retrieval at call start, your AI agent retrieves a URL stored by you as soon as an incoming call starts.

When is this useful?

Data retrieval at call start is suitable for content that changes frequently or differs from call to call. Typical use cases:

• Current availability query it (e.g. available appointments, stock levels)

• CRM data or load customer history

• Daily up-to-date instructions (e.g. special opening hours, promotions)

• Past interactions make available to the caller

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 the file upload in the section Knowledge.

Requirements

• A URL that is reachable via HTTP or HTTPS (HTTPS recommended).

• The endpoint should respond quickly; retrieval happens at call start.

• The response is embedded as text in the conversation context. Ideally, provide well-structured, compact content.

Important: Do not use a publicly accessible URL. Currently, 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 on the 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.

Note: The server response should contain data only. Prompt instructions or behavioral rules should not be passed via the server response. They will be ignored or not processed reliably.

How to set up data retrieval

1

Open the configuration of your AI agent

2

Go to the menu item “Integrations”

3

Find the section “Data retrieval at call start” and click the gear icon

4

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

5

Click “Save”

The configured URL will then appear directly in the user 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 directly read PDF files, websites, or other file formats.

Supported are: 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 set the appropriate Content-Typeheader .

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:

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

callerNumber The phone number of the calling person.

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 passed.

sessionId The unique ID of the current call. sessionId It 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 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 not reachable, the call will still be connected — just without the dynamic context.

• Enabled: If the URL is not reachable, the call will be rejected. Only choose this option if the context is indispensable 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 dialog that follows, confirm with Delete permanently.

After that, the section will show the status again Inactive. No further 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 happens synchronously at the start of the call. Long response times can therefore delay the start of the conversation.

The 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 aborted. 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 will automatically be retrieved on the next incoming call. There is no cache that needs to be cleared first.

Does it work with any URLs?

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