Caller Data Retrieval via Webservice¶
Webservice (REST API) that will be called by While1 Voice, via GET, on a URL like the one below:
https://example.com/api/while1voice?phone=[PHONE]&dnid=[DNID]&token=some_secret_token
The URL is set on each project (API URL). The [PHONE] and [DNID] placeholders are replaced at call time (%s can also be used instead of [PHONE]). If the URL has no parameters, ?phone=[PHONE]&dnid=[DNID] is added automatically.
Parameters sent via GET:- phone => the customer's phone number (Caller ID)
- dnid => the phone number the customer called; for outbound calls (ctk_action=outgoing), the caller ID of the caller (agent / line)
- ctk_action => the request type: incoming, incoming_no_schedule, outgoing, missed, answer
- ctk_uniqueid => the unique ID of the call
- ctk_pin => the PIN entered by the customer, if any
- ctk_dnid_identifier => the identifier of the Inbound route, if any
- ctk_agent_username, ctk_agent_remote_id => the agent, if known (e.g. on answer)
- ctk_external_id, ctk_external_info => the external_id and external_info values sent to API - OriginateCall, only for ctk_action=outgoing (to link the call to a CRM record, e.g. a ticket), if available
The request timeout is 3 seconds.
Your server will respond with HTTP 200 and JSON with the following data (the id or name keys are required, other keys are ignored):- id => the internal customer ID
- name => name, first name
- backend_link => popup link for Incoming Call Answer, starting with http(s)://
- direct_line => used for Inbound calls for direct transfer to agent or queue (e.g. SIP/ion-popescu, Local/ion-popescu or sales-queue), optional
- queue_position => queue position, numeric / NULL, optional
- route_identifier => the number or the identifier (Identifier) of a route in Inbound routes; for outbound calls the Outbound number of that route is used, optional
- outbound_number => the number used for outbound calls; it must be in the provider's number range, optional
- language => the channel language for audio messages (e.g. ro, en), optional
- external_id => external ID, saved in the CDR (external_id), optional
If the customer is not found, respond with HTTP 204 (no content). Any other response is considered an error, and the search is done in the While1 Voice Contacts. Responses are cached according to the AGI cache for getCallerInfo (hours) setting (default 24 hours, 0 = disabled).
Example of caller data retrieval from your own application:
$contact_info = $db->get_row("SELECT * FROM contacts WHERE telephone = '" . $db->escape($_GET['phone']) . "'");
Sending information:
$result = array(
'id' => 12345,
'name' => 'John Doe',
'queue_position' => null,
'direct_line' => null,
'backend_link' => 'https://your-crm.com/example-popup?id=12345',
'route_identifier' => null,
'outbound_number' => null,
'language' => null,
'external_id' => null
);
header('Content-Type: application/json');
echo json_encode($result);
Response contact found - json:
{
"id": 12345,
"name": "John Doe",
"queue_position": null,
"direct_line": null,
"backend_link": "https://your-crm.com/example-popup?id=12345",
"route_identifier": null,
"outbound_number": null,
"language": null,
"external_id": null
}
If the customer is not found, answer with HTTP 204 (no content). A JSON with id / name null is treated as a found customer with empty data.
Connecting to the URL is made from PBX's dedicated IP address. Warning: you must secure the access to that URL by IP restriction or access token.
To make it possible to send the customer data extracted via Webservice to the agent answering the call, continue with the steps described at item 2 - Caller ID Pop-up section.
The URL will be set on each project (API URL), and the parameters for each type of API according to the data below (Help section of the project page)
Api params usage: Generic: type=json&bearer_token=YOUR-TOKEN&root_tag=&send_request_headers=0&ignore_response=0&event_prefix=ctk_ Freshdesk: domain=&api_key= Gomag: ApiShop=&ApiKey= Hubspot: portalId=&token=&search_prefix=+4&add_country_code=1 Kommo: vendor=kommo.com&subdomain=&secret_key=&integration_id= (or token=) iStoma: domain=yourclinic.istomadmain.ro&key=yourkey MedSoft: client_path=&api_key= MiniCRM: SystemId=&APIKey=&APIKeyVoip= MondayCRM: domain=&token=&boards_id=&column_id=&create_contact=1 Pipedrive: domain=&user=&token=&default_owner_id=&default_activity_id=1&create_activity=1&create_lead=1&create_deal=1&update_deal=1&send_call_skip_person_id=0 PrestaShop: domain=&key=&screenpop_uri=screenpop.php Soap: func_name=getCallerInfo&init_params[login]=asdf&init_params[password]=1234&func_params[do_something]=true Ticketsys: - Vaunt: uuid=&token= WooCommerce: domain=&consumer_key=&consumer_secret=&search_key=billing_phone
Available in other languages: RO