Skip to main content
The API Trigger node lets you initiate outbound calls to your voice agent programmatically. When you add an API Trigger node to your workflow, Bananaflow generates a unique endpoint URL that external systems can call to start a conversation. This is useful when you want to trigger calls from your own backend, a CRM, or workflow tools like n8n and Zapier.

Prerequisites

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
You can copy either URL from the trigger node’s settings dialog.

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.
A common pitfall is editing the workflow, saving the draft, and then calling the production trigger URL expecting the new behavior. That will not work until you publish the workflow. Use the test URL to verify draft changes before publishing.
The request body, headers, and response shape are identical for both URLs.

Making a request

Authenticate by passing your API key in the X-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).
Use the test URL when you want to verify draft changes before publishing.

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.
A request is answered at once. The call is queued and goes out as soon as one of your account’s lines is free. The answer gives the call’s ID (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

Pass status_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

The deadline 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_seconds in 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 expired at once (reason: calling_hours).
Example. You send a request at 9:00 AM and all your lines are busy. The call is queued and waits in line. Your account’s longest wait is 8 hours, so the 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 an Idempotency-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:
You can reference the user’s name in your agent prompt as {{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

Pass greeting_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:
For a pre-recorded greeting, pass the recording’s string ID from the Recordings page:
Bananaflow renders a text override after Pre-Call Data Fetch completes, so the override can reference variables returned by the fetch. The override follows the same playback rules as a saved greeting. Pre-Call Data Fetch can also return 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 – pass telephony_configuration_id in the request body.
The id is shown on each row in Telephony configurations (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.