How It Works
- A call arrives (inbound) or is initiated (outbound).
- Bananaflow sends a POST request to your configured endpoint with a standardized payload.
- If the response has not arrived when the call connects, the caller hears a ringing tone until it does.
- Your API responds with a JSON object containing an
initial_contextobject. - The variables are merged into the callβs initial context.
- The voice agent starts with full access to the fetched data via
{{variable_name}}syntax.
What the Caller Hears
Bananaflow sends the request while it sets up the call. If your endpoint answers before the call connects, the agent greets the caller straight away and there is no ringing. If the response is still on its way when the call connects, the caller hears a ringing tone: a one-second tone, then a second and a half of silence, repeated. For an outbound call this starts once the person you called answers. The ringing stops as soon as your endpoint answers, fails, or reaches the timeout, and the agent then plays its greeting.Configuration
Open the Start Call node editor and expand Advanced Settings. Choose a Pre-Call Data Fetch mode and configure the endpoint when the mode is not disabled:
Chats from the website widget count as inbound, so Inbound calls only runs the fetch for them too. When a visitor chats and then calls, the call continues the chat and reuses the data the chat fetched. It does not fetch again.
Request Format
Bananaflow sends aPOST request with the following JSON payload:
The
Content-Type header is set to application/json. If you configured a credential, the corresponding authentication header is included.
The request also carries an Idempotency-Key header that names the call, built from its run ID, for example bananaflow-pre-call-456. Bananaflow sends the request once per call. If your endpoint writes data, such as logging the call in your CRM, use this key to make sure the same call is never recorded twice.
Expected Response Format
Your API should return a JSON object with a2xx status code. The variables to inject into the call context should be placed inside the initial_context key:
initial_context at the top level:
The legacy
dynamic_variables key is still accepted as a drop-in alias for initial_context, so existing integrations keep working without any changes. Use initial_context for new integrations. If a response contains both keys, initial_context takes precedence.- Greeting:
Hello {{customer_name}}, thank you for calling! - Prompt:
The customer is a {{loyalty_tier}} member with {{open_tickets}} open support tickets.
If the response is not a valid JSON object, does not contain
initial_context (or the legacy dynamic_variables), or the request fails or times out, the call proceeds normally without the additional context. The pre-call fetch never blocks or fails a call.Nested Variables
If yourinitial_context contains nested objects, you can access them using dot notation:
{{customer.name}} and {{customer.address.city}}.
Timeout
The request has a 10-second timeout. If your API does not respond within this window, the call proceeds without the fetched data. Design your endpoint to respond as quickly as possible to minimize how long the caller hears ringing.Testing with Test Calls
When a real phone call comes in, thecaller_number and called_number context variables are automatically set by the telephony provider and included in the pre-call data fetch request as from_number and to_number. However, when you make a test call β either a web call (WebRTC) or a phone test call from the workflow editor β these variables are not available by default.
To simulate telephony data during testing:
- Open your workflow and go to Settings.
- Under Context Variables, add the following variables:
caller_numberβ set to a phone number you want to simulate as the caller (e.g.,+12137771234).called_numberβ set to the number that would be dialed (e.g.,+12137771235).
- Save the settings.
These context variables are only used during test calls from the workflow editor. On production inbound calls and campaign outbound calls, the actual telephony data is used and these values are ignored.