The Click-to-Call API enables your application to initiate an outbound call between an Acefone agent and a customer with a single API request. Instead of manually dialing numbers, your application simply sends the required call details to Acefone, and the platform automatically establishes the call.

When a request is received, acefone first places a call to the specified agent (using the registered mobile number, Acefone Agent ID, or Acefone Extension for Softphone users). Once the agent answers, Acefone initiates the second leg of the call to the destination number. After the customer answers, Acefone seamlessly bridges both call legs, allowing the agent and customer to communicate.

This API is ideal for CRM integrations, lead management systems, customer support platforms, sales automation, and any application that requires one-click outbound calling without manual intervention.

The Click-to-Call API operates asynchronously, meaning it immediately acknowledges that the request has been accepted for processing instead of waiting for the call to complete. To monitor the call lifecycle—including ringing, answered, completed, missed, or failed events—configure Acefone Webhooks, which provide real-time event notifications to your application.

Typical Flow

1. Your application sends a Click-to-Call request to Acefone.
2. Acefone calls the specified agent.
3. After the agent answers, Acefone calls the destination number.
4. Once the customer answers, Acefone bridges both call legs.
5. Call progress and final status are delivered to your application through Webhooks.

Note: A successful API response only confirms that the request has been accepted for processing. It does not indicate that the call has been connected or answered. Use Acefone Webhooks to track the complete call lifecycle and receive real-time call status updates.

How it Works

The diagram below provides a high-level overview of the Click-to-Call workflow, including call initiation, agent connection, customer dialing, and call bridging.

Request Headers

The following request headers are required to successfully invoke the Click-to-Call API.

Request Parameters

Provide the following parameters in the request body to initiate a Click-to-Call request between a Aceone agent and the destination number.

Sample Request

The following example demonstrates how to initiate a Click-to-Call request using the Acefone Click-to-Call API.

curl --request POST \
  --url https://api.acefone.in/v1/click_to_call \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <YOUR_API_TOKEN>" \
  --data '{
    "agent_number": "050xxx3456",
    "destination_number": "98xxx43210",
    "caller_id": "08xxx678900",
    "async": 1,
    "call_timeout": 300
  }

Sample Response (Success)

The following example shows the response returned when the Click-to-Call request is successfully accepted for processing.

{
    "success": true,
    "message": "Call originated successfully.",
  "ref_id": "C2C2408011234xxx89"
}

Response Parameters

The API returns the following parameters indicating whether the request has been accepted for processing. Since the API is asynchronous, the response confirms only the request acceptance. Use Acefone Webhooks to track the complete call lifecycle and receive real-time call status updates.

Call Status & Webhooks

The Click-to-Call API returns only the request acceptance status. Actual call progress, including call initiation, ringing, answered, completed, failed, and other call events, is communicated through Acefone Webhooks.

For detailed information about supported webhook events, payload structure, and configuration, please refer to the Webhook Documentation.

Response Codes

The following response codes help you identify whether the request was processed successfully or if corrective action is required due to an error.

Error Response Example

The following example shows the response returned when the API request cannot be processed due to invalid input, authentication issues, or other request validation errors.

{
    "success": false,
  "message": "Invalid destination number."
}

Common Error Messages

The table below lists common error messages returned by the Click-to-Call API, along with their possible causes and recommended resolutions to help you troubleshoot integration issues efficiently.
These descriptions are concise and consistent with the rest of your API documentation.

📘 Notes!

• The API is asynchronous and immediately acknowledges the request after successful validation.
• Pass async as 1. Synchronous mode is not supported.
• Store the returned ref_id for correlating webhook events and future call operations.
• You can include up to 10 custom identifiers per request. The combined JSON representation of all custom identifiers must not exceed 512 characters. Custom identifier values must be alphanumeric, and the $ character is not supported.
• Configure Webhooks to receive real-time updates on the complete call lifecycle.

Related APIs

Explore the following related APIs to extend your Click-to-Call integration with advanced call controls, active call management, call history, and real-time event notifications.