Project

General

Profile

API - OriginateCall

Originate Call API is used to initiate calls to customers via the extensions logged in to the PBX.

The process is done in three steps:

  • Originate call: sending to the PBX the destination number (caller_id) and the user / queue / context (destination)
  • First call: the PBX first calls the agent's phone or the customer, depending on type (see the table below)
  • Second call: when the first call is answered, the PBX connects it to the destination

Call order by type

type destination rings first then
user username of the While1 Voice user agent's phone customer (caller_id)
user_email email of the While1 Voice user agent's phone customer (caller_id)
queue queue name customer (caller_id) queue (first available agent)
extension extension from the internal context customer (caller_id) extension
context dialplan context customer (caller_id) context

Click-to-call from a CRM (agent rings first, then the customer): use type = user or user_email.

API URL

https://[YOUR-PBX-URL]/api/originate-call

Data is sent via POST or GET and must be of the form:

Array
(
    [data] => Array
        (
            [project_id] => 1
            [caller_id] => 0123456789
            [caller_id_name] => John Doe
            [type] => queue
            [destination] => test-queue
            [external_id] => asdf1234
            [external_info] => some test call
            [async] => 1
            [outbound_number] => +40212345678
            [outbound_trunk] => default-trunk
            [vars] => Array
                (
                    [SKIP_WELCOME] => 1
                    [SKIP_WE_ARE_RECORDING] => 1
                    [SKIP_ENTER_QUEUE] => 0
                    [BACKEND_LINK] => https://[YOUR-EXTERNAL-CRM-URL]/?change_this_url=1234
                )

        )

    [api_hash] => 0f25e797e72d0dbba96d2c571a7bd6ba
)

Parameters:

  • project_id: project ID in While1 Voice, mandatory
  • caller_id: destination phone number according to the PBX outbound rules, mandatory
  • caller_id_name: recipient name, mandatory
  • type: action type - user, user_email, queue, extension, context, mandatory (see "Call order by type")
  • destination: username (type user), user email (type user_email), queue (type queue), extension (type extension) or context (type context) in While1 Voice, mandatory
  • external_id: ID from the partner's own application (eg: ticket / customer ID), saved on the call and used for further queries through API - Call Detail Records - CDR, recommended
  • external_info: informative text describing the external_id
  • async: if the operation is executed asynchronously (1) or not (0), optional, by default 0
  • outbound_number: the number that is displayed to the recipient, optional
  • outbound_trunk: the provider through which the call is made, optional
  • vars: array with various variables for the PBX context, optional

Please note: if the async option is 1, the API returns immediately. For type user / user_email it first checks that the user's phone is online, and for type queue that the queue has free slots (it is not guaranteed that the call was answered). For extension / context no check is made.
If the async option is 0, the API keeps the connection open until the first call (see the table) is answered, rejected or times out, returning error or success.

HTTP Headers:

Content-Type: application/json
Authorization: Bearer <token>

Example of parameters generation:

$params = array(
    'data' => array(
        'project_id' => 1,
        'caller_id' => '0123456789',
        'caller_id_name' => 'John Doe',
        'type' => 'queue', // user, queue, context, extension, user_email
        'destination' => 'test-queue',
        'external_id' => 'asdf1234',
        'external_info' => 'some test call',
        'async' => 1,
        'outbound_number' => '+40212345678',
        'outbound_trunk' => 'default-trunk',
        'vars' => array(
            'SKIP_WELCOME' => 1,
            'SKIP_WE_ARE_RECORDING' => 1,
            'SKIP_ENTER_QUEUE' => 0,
            'BACKEND_LINK' => 'https://[YOUR-EXTERNAL-CRM-URL]/?change_this_url=1234', // for pop-up
        )
    )
);

Example of hash generation:

$params['api_hash'] = md5(json_encode($params) . 'your_api_key'); // make hash

Example of sending data:

$url = 'https://[YOUR-PBX-URL]/api/originate-call';
$token = 'your_api_token';
echo curlPost($url, json_encode($params), array("Authorization: Bearer {$token}", "Content-Type: application/json"));

Data sent JSON

{
  "data": {
    "project_id": 1,
    "caller_id": "0123456789",
    "caller_id_name": "John Doe",
    "type": "queue",
    "destination": "test-queue",
    "external_id": "asdf1234",
    "external_info": "some test call",
    "async": 1,
    "outbound_number": "+40212345678",
    "outbound_trunk": "default-trunk",
    "vars": {
      "SKIP_WELCOME": 1,
      "SKIP_WE_ARE_RECORDING": 1,
      "SKIP_ENTER_QUEUE": 0,
      "BACKEND_LINK": "https://[YOUR-EXTERNAL-CRM-URL]/?change_this_url=1234" 
    }
  },
  "api_hash": "a397d9c156faf7c90a18c12ad9a4beaf" 
}

Response

If successful:

{

    "has_error": false,
    "messages": [ ],
    "results": [
        {
            "originate_result": "Call successfully originated for queue: test-queue" 
        }
    ]
}

Or in case of error:

{

    "has_error": true,
    "messages": [
        "Invalid Queue. Check if pbx queue exists" 
    ],
    "results": [ ]
}

Call result

The API does not return the call ID (uniqueid). To get the result (uniqueid, call_status: ANSWERED / NO ANSWER / BUSY / FAILED, duration, recording etc.), send an external_id to originate-call and, after the call ends, read the details through API - Call Detail Records - CDR using the external_id filter.


Available in other languages: RO