POST
/
calls
/
end
cURL
curl --request POST \
  --url https://api.callab.ai/v1/calls/end \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "call_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "disconnect_reason": "<string>"
}'
{
  "status": "<string>",
  "message": "<string>",
  "data": "<string>"
}

​
End a Call

This endpoint terminates an active call and performs post-call processing including analysis and webhook notifications.

​
Endpoint Details

  • URL: /calls/end
  • Method: POST
  • Authentication: Required (API KEY or JWT Token)
  • Source: src/api/public_apis_v1/call/end_call/end_call_controller.rs

​
Request Headers

HeaderValueDescription
AuthorizationBearer <api_key>Your API KEY or JWT Token
Content-Typeapplication/jsonRequest content type

​
Request Body

FieldTypeRequiredDescriptionExample
call_idUUIDYesThe unique identifier of the call to end550e8400-e29b-41d4-a716-446655440000
disconnect_reasonStringNoCustom reason for ending the call. Defaults to “Ended Via API call”Customer requested to end call

​
Example Request

​
cURL

curl -X POST "https://api.callab.ai/calls/end" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "disconnect_reason": "Call completed successfully"
  }'

​
JavaScript

const endCall = async (callId, disconnectReason = null) => {
  const url = 'https://api.callab.ai/calls/end';
  const apiKey = 'YOUR_API_KEY';

  const requestBody = {
    call_id: callId
  };

  if (disconnectReason) {
    requestBody.disconnect_reason = disconnectReason;
  }

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(requestBody)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error ending call:', error);
    throw error;
  }
};

// Usage
const callId = '550e8400-e29b-41d4-a716-446655440000';
endCall(callId, 'Customer hung up').then(data => console.log(data));

​
Python

import requests
import json

def end_call(call_id, api_key, disconnect_reason=None):
    url = "https://api.callab.ai/calls/end"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "call_id": call_id
    }
    
    if disconnect_reason:
        payload["disconnect_reason"] = disconnect_reason
    
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Error: {response.status_code} - {response.text}")

# Usage
call_id = "550e8400-e29b-41d4-a716-446655440000"
api_key = "YOUR_API_KEY"
result = end_call(call_id, api_key, "Call objective achieved")
print(result)

​
Node.js with Axios

const axios = require('axios');

async function endCall(callId, apiKey, disconnectReason = null) {
  const url = 'https://api.callab.ai/calls/end';
  
  const data = {
    call_id: callId
  };
  
  if (disconnectReason) {
    data.disconnect_reason = disconnectReason;
  }
  
  try {
    const response = await axios.post(url, data, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error ending call:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
const callId = '550e8400-e29b-41d4-a716-446655440000';
const apiKey = 'YOUR_API_KEY';
endCall(callId, apiKey, 'Manual termination')
  .then(result => console.log(result))
  .catch(error => console.error(error));

​
Response

​
Success Response

Status Code: 200 OK 
{
  "status": "ok",
  "message": "ok",
  "data": "Call Ended"
}

​
Error Response

Status Code: 200 OK (with empty body) When an error occurs, the endpoint may return an empty response body.

​
Post-Call Processing

When a call is ended through this endpoint, the following actions are automatically performed:

​
1. Provider Termination

  • The call is terminated with the telephony provider (e.g., Twilio) using the provider’s API
  • Uses BYOT (Bring Your Own Twilio) credentials if configured

​
2. Resource Cleanup

  • Echo room associated with the call is deleted
  • Any temporary resources are cleaned up

​
3. Call Record Update

  • The call’s ended_at timestamp is set to the current time
  • The disconnect_reason is updated with the provided reason or default
  • Call status is updated to reflect termination

​
4. Call Analysis

  • Automatic call analysis is triggered after termination
  • Sentiment analysis and other metrics are calculated
  • Analysis results are stored in the call record

​
5. Webhook Notifications

  • If configured, webhook notifications are sent with the call analysis results
  • Webhooks include complete call data and analysis outcomes

​
Use Cases

​
1. Manual Call Termination

End an ongoing call when specific conditions are met or upon user request.

​
2. Emergency Stop

Immediately terminate a call in case of issues or emergencies.

​
3. Scheduled Termination

End calls that have exceeded time limits or met completion criteria.

​
4. Quality Control

Terminate test calls or problematic calls detected by monitoring systems.

​
5. Integration Workflows

End calls as part of automated workflows or third-party system integrations.

​
Important Notes

  • The endpoint requires the call to exist and be associated with a valid phone number
  • The call must be active or in a state that allows termination
  • Post-call analysis is performed asynchronously and may not be immediately available
  • Webhook notifications are sent on a best-effort basis
  • The disconnect_reason field is useful for tracking why calls were ended
  • If no disconnect_reason is provided, it defaults to “Ended Via API call”
  • The endpoint will attempt to end the call even if some cleanup operations fail

​
Error Handling

The endpoint handles various error scenarios:
  • Invalid call ID: Returns empty response
  • Call not found: Returns empty response
  • Provider termination failure: Continues with local cleanup
  • Echo room deletion failure: Continues with other operations
  • Analysis failure: Logged but doesn’t prevent call termination
  • GET /calls/{id} - Get call details after ending
  • GET /calls/query - Query calls with specific end reasons
  • POST /calls/make-call - Initiate a new call

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Details to end the call

​
call_id
string<uuid>
required

ID of the call to end

​
disconnect_reason
string | null

Reason for disconnecting the call. Defaults to 'Ended Via API call' if not provided.

Response

Call ended successfully

​
status
string
required

Status of the response, e.g., 'ok'

​
message
string
required

A descriptive message for the response

​
data
string

Confirmation message, e.g., 'Call Ended'