Click to Call¶

HTTP endpoint to originate a call from an external application: QVOICE Platform rings the authenticated user's extension first and, once that leg answers, dials the destination.

Who receives the call¶

The call always rings the user that owns the access token used in the request.

There is no parameter to choose the agent. The endpoint takes the destination from the URL path and the caller from the authentication context:

The access token carries an identity claim in the form <user_id>:<account>.
The backend resolves that claim to a user document and uses the user's presence_id (their extension) as the first leg of the call.
The destination in the path is dialled only after that extension answers.

So, to make a call ring agent A, the request must be authenticated with agent A's token. A token belonging to an administrator will ring the administrator's own extension, not the agent's.

One token, one extension

The X-Account-ID header does not change who receives the call. This endpoint always uses the account and user encoded in the token. If your integration places calls on behalf of several agents, it must obtain and store one access token per agent.

The user needs an extension and a registered device

If the authenticated user has no presence_id, or has no phone / softphone registered, there is nothing to ring and the call never gets to the destination.

Authentication¶

Use the standard QVOICE Platform login endpoint to obtain an access token for the user that should receive the call:

curl -X POST "https://{portalURL}:9443/ucp/v2/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent@example.com",
    "password": "yourPassword",
    "domain": "yourTenant"
  }'

Response

{
  "user": { "...": "..." },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Send the access_token as Authorization: Bearer <token> on every Click to Call request. When it expires, obtain a new one with the refresh token or by logging in again.

API keys are not supported on this endpoint

An API key (X-API-Key) authenticates the account, not a person: it resolves to a virtual admin user with no extension, so there is no phone to ring and the request fails. Click to Call requires a real user's access token.

Endpoint¶


Method	`POST`
URL	`https://{portalURL}:9443/ucp/v2/c2c/{destination}`
Headers	`Authorization: Bearer <access_token>`
Body	none
Success	`201 Created` (empty body)

Path parameter¶

Name	Description
`destination`	Number or extension to dial once the user's extension answers. Anything the account's dialplan accepts: an internal extension (`2001`) or an external number (`5491155551234`). URL-encode it if it contains `+` or other reserved characters.

Example¶

curl -i -X POST "https://{portalURL}:9443/ucp/v2/c2c/5491155551234" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

HTTP/1.1 201 Created

Responses¶

Code	Meaning
`201 Created`	The call was accepted and is being originated.
`401 Unauthorized`	Missing, malformed or expired token.
`5xx`	The user document could not be read, or the platform rejected the origination.

Call behaviour¶

The request returns 201 as soon as the platform accepts the origination — it does not wait for anyone to answer. A 201 therefore means "the call was launched", not "the call was connected".
The authenticated user's extension rings first. If that user does not answer, the destination is never dialled.
When the user answers, the destination is dialled and both legs are bridged.
The response carries no call identifier. To follow the call, use the CDR: Click to Call legs are tagged with the SIP header Fonouc-Call-Type: clicktocall, stored in the CDR as custom_sip_headers.fonouc_call_type = "clicktocall".

The first time a user places a Click to Call, QVOICE Platform provisions the underlying click-to-call resource for that user automatically and stores it on the user document. No manual setup per user is required.

The UCP feature toggle does not gate this endpoint

The account feature UCP click2call only shows or hides the button inside UCP. The API answers the same whether that toggle is on or off.

Typical integration¶

A CRM or web application that wants a "call this contact" button:

When the agent signs in to your application, log them in to QVOICE Platform with their own credentials and keep their access_token.
On click, POST /ucp/v2/c2c/{contact_number} with that agent's token.
The agent's phone rings; when they pick up, the contact is dialled.

If your application serves many agents, store one token per agent — never share a single token, or every call will ring the same extension.