Skip to main content
The API Request Pre-Call Action allows your Phonely agent to communicate with external systems before the conversation begins. It sends or retrieves data from external APIs immediately when a call starts. This allows the system to prepare information, validate callers, or trigger external systems before the AI agent speaks to the caller. Because it runs before the greeting message, this action is commonly used to load customer data, perform verification checks, or prepare variables that the conversation workflow will use. Once the API request finishes, the call continues to the greeting message or the first workflow block.

​
When This Action Runs

The Pre-Call API Request executes immediately after the call is answered, but before any conversation logic begins. Typical execution order: 
Incoming Call
      ↓
Pre-Call API Request
      ↓
Greeting Message
      ↓
Conversation Workflow
This ensures any retrieved data is available to the agent from the very first message.

​
What the API Request Can Do

The Pre-Call API Request allows your system to interact with external services such as:
  • CRM systems
  • Customer databases
  • Order management platforms
  • Fraud detection services
  • Authentication systems
  • Analytics platforms
It can be used to:
  • Retrieve customer information using the caller’s phone number
  • Verify account status
  • Load order or subscription data
  • Trigger CRM events
  • Send call start notifications to other systems
The returned data can then be stored in variables and used throughout the call.

​
How to Add a Pre-Call API Request

Pre-Call Actions can only be added at the very beginning of a workflow, before the conversation flow starts. This starting point is the Start Flow. The Start Flow is the block that runs first when a call is answered. By default, this block may be labeled Greeting Message, but it can be renamed to match your workflow. Pre-Call Actions are added above the Start Flow, so this block must be configured first before the option to add Pre-Call Actions becomes available.
1

Set the Start Flow

Open your Flow Editor and select the block that should run when a call begins.In the configuration panel on the right, enable Set as First Flow.When this option is checked, Phonely will always start the workflow with this block whenever a call is received. Once it is set, the system enables the Pre-Call Actions area above the Start Flow.
Startflowprecall
2

Add a Pre-Call Action

After the Start Flow is configured, a ➕ button will appear above the beginning of the workflow labeled Add a pre-call action.Click this ➕ button.
3

Select API Request

From the list of available Pre-Call Actions, select API Request.The API Request configuration panel will open, allowing you to configure how the external API should be called before the conversation begins.

​
Setup

In the Setup stage you define the request structure. Phonely allows two ways to configure the API call:

​
Option 1 — Import from cURL

If you already have a request from tools like Postman, API documentation, or terminal commands, you can paste it directly. Paste the cURL command into the cURL Command field and click Import from cURL. Example: 
curl -X GET "https://api.example.com/customer?phone=123456789"
-H "Content-Type: application/json"
Phonely automatically extracts:
  • HTTP method
  • API endpoint
  • headers
  • query parameters
  • request body
These values are then populated in the Configure tab.

​
Option 2 — Build Manually

If you don’t have a cURL command, select Build Manually. You will then configure the request step-by-step in the Configure section.

​
Configure

The Configure tab defines how the API request should behave.

​
API Method

Select the HTTP method used by the API. Supported methods:
  • GET – Retrieve information from a system
  • POST – Send new data to an API
  • PUT – Update an existing resource
  • PATCH – Partially update a resource
  • DELETE – Remove a resource
Example: Use GET to retrieve a customer profile.

​
API URL

Enter the API endpoint where the request will be sent. Example: 
https://api.example.com/customers
This URL represents the destination where your request is processed.

​
Headers

Headers provide additional metadata required by the API. Click Add to create key-value pairs. Common examples include:
HeaderExample Value
Content-Typeapplication/json
AuthorizationBearer YOUR_API_KEY
Headers are often required for authentication and data formatting.

​
Query Parameters

Query parameters allow you to send additional information through the URL. Example: 
https://api.example.com/orders?customer_id=123
In the interface, these appear as key-value pairs:
KeyValue
customer_id123

​
Advanced Settings

The Advanced Settings section allows you to control how the API request behaves during execution.

​
Enable Error Handling

When enabled, the system can detect failed requests and handle them gracefully. Example scenarios:
  • API unavailable
  • authentication error
  • invalid request
Instead of breaking the flow, you can define fallback logic.

​
Retry on Failure

If the API request fails due to temporary issues, Phonely will automatically retry the request. This helps prevent interruptions caused by short network or server delays.

​
Timeout Duration

Defines how long Phonely waits for the API response before considering the request failed. Example: 
5 seconds
If the server does not respond within the configured time, the request will timeout.

​
Interim Message

If the API request takes time, Phonely can send a short message to the caller to indicate progress. Example:
“One moment while I retrieve your information.”
This prevents silence during longer API requests.

​
Interim Message Prompt Type

Two options are available: Fixed The message is predefined and always the same. Promptable Phonely dynamically generates a short message using AI based on the configured prompt. Example prompt:
Generate a friendly 3–7 word interim message telling the caller you are working on their request.

​
Post Interim Message Delay

Adds a small delay after the interim message before the API request continues. This makes the interaction feel more natural.

​
Call Outcome Tagging

You can assign outcome tags for reporting and analytics. Example tags:
  • customer_lookup_success
  • account_verified
  • api_timeout
These tags help categorize calls in dashboards and reports.

​
Test Stage

After configuration, use the Test step to validate the request. Click Test to send the request exactly as configured. Phonely will display the API response immediately. If successful, you may see a response like: 
Status: 200 OK
If the request fails, the system displays the error message to help troubleshoot issues such as:
  • incorrect endpoint
  • missing authentication
  • invalid parameters
  • server errors
Testing ensures the request works correctly before publishing the workflow.