The Stop call endpoint ends an active call for a specific agent. This is typically used in CRM style integrations where you start a call using Start call and want a one click way to end it.

Requirements: Base URL, Authentication, Error codes

Scope: voice.call.manage

What this does

When your system sends a Stop call request, Voiso attempts to hang up the specified call for the specified agent.

If the request is accepted, the API returns the call ID.

Prerequisites

The agent must be signed in to Agent Panel.
The agent must be handling an active call.
You must know the call ID you want to end, for example from the response of Start call.

Endpoint


POST /api/v4/voice/calls/{call_id}/hangup

Request parameters

Path parameters

call_id
ID of the call (UUID).

Request body

Required fields

user_id
The agent ID in the contact center (UUID).

Examples

Minimal request

curl -X POST "https://{cluster_id}.voiso.com/api/v4/voice/calls/0b97ce11-b6e0-49b4-8f92-68040aa324bf/hangup" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0b97ce11-b6e0-49b4-8f92-68040aa324bf"
  }'

Response

If successful, the API returns the call ID:

{
  "call": {
    "id": "0b97ce11-b6e0-49b4-8f92-68040aa324bf"
  }
}

Troubleshooting

401 Unauthorized

You are not authenticated.

What to check:

You are sending Authorization: Bearer <contact_center_api_key>.
Your Base URL includes the correct {cluster_id}.

Example response:

{ "error": "Unauthorized" }

403 Forbidden

You are authenticated, but the key does not have permission to stop calls.

What to check:

The API key is allowed to access this resource in this contact center.

Example response:

{ "error": "Forbidden" }

422 Unprocessable Entity

The request is well formed, but one or more values failed validation.

Common causes:

call_id is missing or not a UUID.
user_id is missing or not a UUID.

Example response:

{
  "errors": {
    "parameter1": ["is missing"],
    "parameter2": ["must be a string"]
  }
}

The call is already finished

If the call ended before you sent the request, Voiso cannot hang up an inactive call.

What to check:

Confirm you are using the correct call_id.
Confirm the call is still active before attempting to stop it.