Please refer to the detailed API endpoint specification: Start call.

Initiate outbound calls

Using the click2call (click-to-call) API, you can start calls for specific agents from an external system.

For example, you can integrate a one-click feature into your CRM or another system to initiate an outbound call, eliminating the need to dial the number manually.

When the external system triggers the click2call API, Voiso returns the call UUID. You can gather all call data in your system using the CDR API.

To initiate the outbound call for a specific agent use : Start call

Prerequisites

The agent must have an extension configured or a valid login email address.
The click-to-call feature must be enabled for the agent's security access group.
The agent must be logged in.
The agent's status must be Available.

Making requests

Authentication

The startcall API requires the Base URL and the contact center API key.

Request parameters

The startcall API uses the key parameter: the contact center API key.

Parameter	Description	Type	Required	Notes
agent	The agent's contact center phone extension or sign-in email address.	string	Required	This parameter tells Voiso which agent should get the call. The call starts automatically on the agent's configured Web-RTC softphone, known as Agent Panel.
number	The phone number to be dialed.	string	Required	The number must be specified in E.164 format without the preceding '+'. For example: `447414992548`
account_id	An identifier assigned to the contact in an external application such as a CRM.	string	Optional	Once you specify it, the corresponding interactions will be marked with this parameter in CDR. You may want to use it for enriching the interaction data with external identifiers. It might help you with reporting. It is also useful for number masking — when `account_id` is specified, it replaces the destination number in Web-RTC softphone (Agent Panel), Omnichannel Workspace, as well as in Voiso reporting tools, such as Real-Time Dashboard (RTD) and Call Details Records (CDR). Using it, you can hide real contact phone numbers from your agents and supervisors.
CRM	The name of an external application, such as a CRM, where contact information is managed.	string	Optional	Once you specify the `crm` parameter, the corresponding interactions will be marked with this parameter in CDR. It might help with reporting and debugging.
get_call_id	Specify whether to retrieve the UUID for the call.	string	Optional	Specify only `true` or `false`. The UUID lets you track the call in your database, CRM, or Raw Data Streaming to SQS.

With these required parameters, you can make a simple request:

{
  "method": "POST",
  "url": "https://cluster1.contact_center_name.com/api/v1/cc7c76b8987a281d...90ab6c3/click2call",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "agent": "1002",
    "number": "4407414992548"
  }
}

To make more advanced requests, you can include optional parameters.

{
  "method": "POST",
  "url": "https://cluster1.contact_center_name.com/api/v1/cc7c76b8987a281d...90ab6c3/click2call",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "agent": "june.juliette@mail.com",
    "number": "4407414992548",
    "account_id": "June Juliette",
    "CRM": "MyCRM",
    "get_call_id": "true"
  }
}

Response

If the call is successful, the API responds with the call's UUID. You can use this ID to get information about the call using the CDR API.

Response sample

{
  "call_id": "24f6a191-f0ad-4257-x934-32xx26x51208"
}

Troubleshooting

The following issues are sometimes encountered:

Agent click2call disabled

If you see this error, "error": "Agent click2call disabled", the security access group assigned to the agent does not have Click-to-call enabled. Either update the permissions in the security access group or assign the agent to a different security access group.

Invalid destination number

If you see this error, "error": "Invalid destination number", it means that the destination phone number is not in E.164 format or the number does not exist. Verify the phone number is correct and in the correct format without the preceding '+'. For example: 447414992548

Invalid agent's extension or agent login ID

The startcall API uses either the agent's extension or login ID to identify the user who is making the click-to-call request. If you see this error, the value specified for the agent parameter is invalid.

Agent logged off

If you see this error,"error": "Agent logged off", the target agent is not logged in to their softphone. Ensure that agents are logged in to their Voiso account.

Rate limit exceeded

If you see this error, "error": "Rate limit exceeded", the number of permitted requests per agent to the server is exceeded, and requests are being throttled. There must be a minimum of 2 seconds between Startcall requests for an agent.

Invalid API key

The startcall API uses the contact center API key to validate the request. If you see this error, "error": "Invalid API key", check that you use the correct contact center API key. For more information about API keys, refer to Authentication.