The Start call endpoint initiates an outbound call for a specific agent from an external system, such as a CRM. If the request is accepted, the API returns an ID for the initiated call.

Requirements: Base URL, Authentication, Error codes

Scope: voice.call.manage

What this does

When your system sends a Start call request, Voiso attempts to place an outbound call for the target agent.

If the request is accepted, the API returns an ID for the initiated call. You can use Voiso reporting APIs to retrieve call details later.

Prerequisites

The agent must have an extension configured or a valid sign in identity.
The click-to-call permission must be enabled for the agent’s assigned security access group.
The agent must be signed in to Agent Panel.
The agent status must be Available.

Endpoint


POST /api/v4/voice/calls

Request body

Required fields

user_id
The agent ID in the contact center (UUID).
phone_number
The phone number to be dialed.

Optional fields

caller_id
The phone number or identifier shown as the caller ID.
source
Metadata about the external system that provided the contact number.
- source.account_id
  External identifier for the contact, such as a CRM contact ID.
- source.name
  External system name, such as your CRM name.

Notes on formatting

Phone number format: Use an international number that includes the country code. Examples in this API omit the leading plus sign.

Examples

Minimal request

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

Request with source metadata and caller ID

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

Response

If successful, the API returns the initiated 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>.
The API key is correct for this environment.
Your Base URL includes the correct {cluster_id}.

Example response:

{ "error": "Unauthorized" }

403 Forbidden

You are authenticated, but the key or agent does not have permission to start calls.

What to check:

The agent’s security access group has click-to-call enabled.
The API key is allowed to access this resource in this contact center.

Example response:

{ "error": "Forbidden" }

422 Unprocessable Entity

The request body is well formed JSON, but one or more fields failed validation.

Common causes:

user_id is missing, not a UUID, or does not match an existing agent.
phone_number is missing or not in a supported format.

Example response:

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

429 Too many requests

Your requests are being rate limited.

What to do:

Reduce request frequency.
Retry with backoff.

Example response:

{ "error": "Too many requests" }

201Created

401Unauthorized

403Forbidden

422Unprocessable Entity

429Too many requests