The Call Hangup API allows you to terminate an active call programmatically through the Acefone platform. The API supports two identifiers for identifying the active call:

• call_id – Unique identifier of the active call.
• ref_id – Reference ID associated with the call. The ref_id is returned in the API response when the call is initiated and is also available in applicable webhook events.

You can provide either call_id or ref_id in the request. This provides flexibility to customers based on the identifier available in their application. When ref_id is provided, Acefone internally identifies the corresponding call and performs the hangup operation.

Note: The Call Hangup API performs the requested action on an active call. The API response confirms whether the hangup request has been accepted for processing. To monitor the subsequent call lifecycle, configure Acefone Webhooks.

How it Works

The Call Hangup API is used to terminate an active call that is currently in progress on the Acefone platform. To perform the hangup operation, the application must first identify the active call using either call_id or ref_id.

Acefone provides multiple ways to obtain these identifiers based on how the customer has implemented the call flow. The identifier can be obtained directly from the API response received when the call is initiated, retrieved from the Active Call APIs, or received through configured webhook events.

Once the application has obtained either call_id or ref_id, it can pass the identifier to the Call Hangup API. Acefone uses the provided identifier to identify the corresponding active call and process the hangup request.

The following are the supported ways to identify an active call:

1. Call Initiation API Response

When a call is initiated using a Acefone Call Initiation API, the API response provides a ref_id associated with the call.

The application can store this ref_id and use it later to identify the call when a hangup operation is required.

2. Active Call APIs

If the application does not have the ref_id from the call initiation response, it can use the Active Call APIs to retrieve details of calls that are currently in progress.

The Active Call API can be used to identify the required active call and obtain its call_id. The application can then use this call_id in the Call Hangup API request.

3. Configured Webhooks

Customers can also configure the appropriate Acefone Webhook events to receive real-time call information. Depending on the configured webhook event, the webhook payload can provide the relevant ref_id and/or call_id.

The application can use this information to identify the active call and subsequently send a hangup request.

This approach is useful when the customer wants to maintain an event-driven integration instead of continuously querying the Active Call APIs.

Important: Either call_id or ref_id can be used to identify the active call. Both identifiers are supported, and providing both is not required.

Recommendation: Store the ref_id received in the call initiation API response whenever possible. The same ref_id can also be used to correlate applicable webhook events and subsequent call operations.

Request Headers

Defines the HTTP headers required to authenticate the request and specify the request and response format.

Request Parameters

Lists the parameters used to identify the active call that needs to be terminated. The API supports either call_id or ref_id.

Parameter Requirement

Either call_id or ref_id must be provided in the request to identify the active call. Both parameters are not mandatory.

Sample Request

The following examples demonstrate how to use the Call Hangup API to terminate an active call. The request can be made using either call_id or ref_id as the call identifier.

Use call_id when the active call identifier is available through the Active Call API or other call-related events. Alternatively, use ref_id when it is available from the call initiation API response or configured webhook events.

The request must include at least one of these identifiers in the request body.

Example using call_id

{
  "call_id": "16273XXXX6.35XX3"
}

Example using ref_id

{
  "ref_id": "SRHXXXXXC123456"
}

Note: call_id and ref_id are alternative identifiers. You only need to provide one of them to identify the active call.

Sample Response (Success)

A successful response indicates that Acefone has accepted the hangup request for processing after validating the request and identifying the call.

The response does not necessarily indicate that the call has already been disconnected at the exact time the API response is received. Since the hangup operation is processed on the active call, the actual call status should be tracked through the configured Acefone Webhooks.

{
    "success": true,
    "message": "Call hangup successful"
}

Important: A successful API response confirms acceptance of the hangup request. To track the subsequent call status and confirm the call disconnection, use the appropriate Acefone Webhook events.

Response Parameters

The response contains the status of the API request and a message describing the result.

Common Error Messages

The following are common errors that may be returned when the Call Hangup API request cannot be validated or the provided call identifier is invalid.

Call Status & Webhooks

The Call Hangup API performs an operation on an already active call. The API response only confirms whether the requested hangup operation has been accepted for processing.

To monitor the complete lifecycle of the call after the hangup request, configure Acefone Webhooks.

Recommended webhook events can be used to determine whether the call was answered, missed, disconnected, or otherwise transitioned to another state.

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

Related APIs

The following APIs and features can be used along with the Call Hangup API to manage and monitor the complete call lifecycle.