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 (integer).

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": "1234"
  }'

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 an integer.

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.