Prerequisites
- A configured telephony provider – outbound calls will fail without one
- An API key for authentication
Finding your trigger URL
When you add an API Trigger node to your workflow, Bananaflow assigns it a unique UUID. The trigger node exposes two URLs that share this UUID:- A production URL for the published workflow
- A test URL for the latest draft
Test vs production
Use the test URL while iterating on changes so production traffic continues to hit the published version.
The production URL only executes a published workflow. If you update the workflow but do not publish it, the production trigger will continue to run the older published version.
Once you publish your draft, both URLs run the same definition.
The request body, headers, and response shape are identical for both URLs.
Making a request
Authenticate by passing your API key in theX-API-Key header. The request body requires a phone_number and accepts optional initial_context, telephony_configuration_id, from_phone_number_id, status_url, max_wait_seconds and dial_by fields. An optional Idempotency-Key header makes a retried request safe (see Retrying a request safely).
Response
What changed (2026-11-03). A request is now queued and answered
200 with status queued. When every line of your account is in use you no longer get 429; the call waits for a free line instead. If your code retried on 429, stop retrying and read the call statuses.workflow_run_id), which you can use to retrieve run details, recordings, and transcripts, and the deadline: the latest time the call may be dialled.
status is queued for a new request. It is expired when the request arrived outside your account’s calling hours; no call is placed. A repeated request with the same Idempotency-Key gets the first call’s answer, with the status that call has now.
An account with no lines gets each of its calls queued, then expired at its deadline.
Error responses
Call statuses
Passstatus_url (an https address) to receive each status change of the call as a POST. Each status is sent once, with retries if your endpoint fails; see Call status deliveries for the body and the retry rules.
A call moves forward only: queued, then dialing, then in_progress, then one final status.
A request that is answered
expired sends only expired.
When a call expires
Thedeadline in the answer is the earliest of:
- Your account’s longest wait: 10 minutes, unless our team has set another for your account. Our team can raise it as far as 8 hours (28,800 seconds).
max_wait_secondsin the request asks for a shorter wait; a longer one is cut to your account’s limit, never refused (reason:max_wait). dial_by: a time with a time zone, in the future and at most 7 days ahead, by which the call must be dialled (reason:dial_by).- Your account’s calling hours, when our team has set them for your account: a call waiting when the hours close expires, and a request outside the hours is answered
expiredat once (reason:calling_hours).
deadline is 5:00 PM. If a line frees up before 5:00 PM, the call is dialled. If not, the call expires and you get the status expired with reason max_wait. No call is placed. If your calling hours close at 6:00 PM, they would only matter for a wait that runs past 6:00 PM.
Retrying a request safely
Send anIdempotency-Key header (1 to 255 visible ASCII characters) with each request. The same key within 24 hours gives the same call, dialled once, and the same answer. The same key with a different request body is refused with 422. After 24 hours the key starts a new call.
Initial context
initial_context is a JSON object containing any information you want your voice agent to access during the call. You can reference these values in your prompts using template variables – values enclosed in {{ and }}.
For example, if your request includes:
{{user.name}} – in Agent prompts, initial_context fields are referenced directly by name (not prefixed with initial_context.). See template variables for the exact syntax in prompts versus webhook payloads.
See Context & Variables for more on how data flows through a call.
Override the greeting for one call
Passgreeting_override inside initial_context to replace the Start Call node’s saved greeting for one API-triggered call. A valid override takes precedence over the saved greeting. If you omit it, Bananaflow uses the saved greeting; if neither exists, the Start node follows its normal no-greeting behavior.
For a text greeting:
greeting_override. Because fetched context is applied after trigger context, a valid fetched override replaces one supplied by the trigger.
Choosing a telephony configuration and caller ID
By default, calls are placed through your organization’s default outbound telephony configuration. To route a specific call through a different configuration – for example, to dial out from a regional number – passtelephony_configuration_id in the request body.
https://app.bananaflow.ai/telephony-configurations). The configuration must belong to the same organization as the API Trigger; otherwise the request returns 404.
To use a specific caller ID from that configuration, also pass from_phone_number_id:
from_phone_number_id is the ID of a phone number configured under the selected telephony configuration. The number must be active and belong to that configuration; otherwise the request returns 400. You can retrieve configured numbers with List phone numbers.
For full endpoint details including all parameters and response fields, see the API reference.