VoIP API

From Planfix
Revision as of 09:30, 1 February 2023 by Artem (talk | contribs)
Jump to: navigation, search

API Overview

The API lets you connect any cloud PBX to Planfix.

Integrating Planfix and cloud PBX addresses several business needs:

  • retrieving caller names so they can be displayed on phone or SIP client screens;
  • automatic routing of incoming calls from a client to a specific employee assigned to this client;
  • displaying information about incoming calls directly within Planfix (pop-up windows for calls);
  • saving entire call history and recordings of conversations to Planfix;
  • making outgoing calls directly from the Planfix interface.


The integration must be two-way. As a result, some requests will be sent by Planfix to the specified cloud PBX entry points, and some requests will be sent from the cloud PBX to Planfix's single entry point.

The exchange happens over HTTPS. Authorization is done using the Planfix or cloud PBX address, respectively, and the authorization key obtained during the integration setup process.


How authorization and communication work

HTTPS

  • API calls to Planfix are accepted only over HTTPS. This ensures that the systems can communicate securely over the Internet.
  • To keep your data secure, please use HTTPS to receive calls in your PBX as well.


Key (token)

  • In addition, a special key (token) is used to authorize each call to Planfix. You can get it in the integration settings.
  • Please use a key (token) to accept calls in your PBX as well. Generate a key and enter it in the corresponding field in the integration settings section.
  • Keys are created one time, when configuring the integration. You can replace the key on your end as needed and update it in Planfix.


API calls from cloud PBX to Planfix

  • Calls must be sent to the address specified in the integration settings to receive notifications.
  • The special key must always be passed in the body of the request, in the "token" field.
  • Requests are passed in the format application/x-www-form-urlencoded


API calls from Planfix to cloud PBX

  • Planfix will send all requests to the address specified in the integration settings.
  • Planfix will pass the key (token) that you specify in your settings in the body of the message.
  • Requests are passed in the format application/x-www-form-urlencoded


Responses

  • Planfix sends all responses to API calls from cloud PBX in JSON in the body of the response.
  • The cloud PBX must send all responses to Planfix calls in JSON in the body of the response.


Connecting in the Planfix interface

To connect and configure the integration, go to Integrations - Virtual PBX: <screenshot>


In the section that opens, select Planfix API for telephony (at the end of the list): <screenshot>


A window will open with integration settings:


<screenshot>


From this window, you will need to take the address for sending requests to Planfix (unique for each account) and the token (planfix_token for calls to Planfix). You will also need to specify the PBX data: the address where Planfix will send requests and the PBX authorization key (token parameter in requests to the PBX).


List of API commands

From Planfix to cloud PBX

  • makeCall (POST)


From cloud PBX to Planfix

  • contact (POST)
  • event (POST)
  • record (POST)


API commands and script examples

Commands from Planfix to cloud PBX

  • makeCall

Command required to initiate a call from manager to client. When this command is successfully made, the cloud PBX will first call the manager's phone and then connect them to the client. The command is used to call by clicking a client's number in Planfix.


  • Call parameters
Name Description Data type/format
cmd type of operation, in this case makeCall string
from short code of the employee making the outgoing call string
to number to which the outgoing call is made string
token cloud PBX key (token) set in the integration settings string


  • Sample API call
POST <nowiki>https://domain/planfix_api.php</nowiki>

cmd=makeCall
from=101
to=79101234567
token=202cb962ac59075b964b07152d234b70


  • Response options
HTTP code Body Description
200 ОК
400 { error: "Invalid parameters" } Invalid parameters passed
401 { error: "Invalid token" } Invalid key (token) passed


Commands from cloud PBX to Planfix

  • contact

Command for obtaining information about a client's name and the person responsible for working with them using their phone number.

The command can be used to display the client's name on the screen of an IP phone or in the communication system on an employee's PC. It can also be used to redirect calls from clients to the employee indicated as their manager in Planfix.


  • Call parameters
Name Description Data type/format Notes
cmd type of operation, in this case contact string
phone contact's phone number string
callid unique call ID string not required
planfix_token Planfix key (token), specified in the integration settings string


  • Sample API call
POST https://test.planfix.ru/tel/api

cmd=contact
phone=79101234567
planfix_token=303cb962ac59075b964b07152d234b70
callid=D12D0EB124F4E64AF4EA-1511


  • Response option
HTTP code Body Description
200 { contact_name: "John Smith", manager: 103 } manager - short code of the user who is the manager; not required if there is no manager or the manager doesn't have a short code
400 { error: "Invalid parameters" } Invalid parameters passed
401 { error: "Invalid token" } Invalid key (token) passed


  • event

Cloud PBX sends Planfix notifications about call events: calls made, pickups, hangups, and info about the call once it's completed. This command is used to display a pop-up card for the call in the interface.

Data about call length and outcome is used to record call data in a data tag (to be implemented soon) as well as to to figure out whether a call record exists and whether Planfix should expect to receive one.


  • Call parameters
Name Description Data type/format Notes
cmd operation type, in this case event string
type call type in/out incoming/outgoing
event type of event associated with the call:
  • INCOMING — an incoming call was received (at this time the manager's phone should start ringing).
  • OUTGOING — an outgoing call was initiated.
  • ACCEPTED — the call was successfully accepted (the manager picked up).
  • COMPLETED — the call was completed (the manager or client hung up after a conversation).
 string
phone client phone number string
diversion external phone number of the PBX through which the call was made or received string
ext employee's internal PBX number string
callid unique call ID string
duration call duration, in seconds int when event=COMPLETED
is_recorded whether or not the call was recorded 0/1 when event=COMPLETED
status incoming call status:
  • Success - successful incoming call
  • Missed - missed incoming call
  • Canceled - canceled incoming call (phone answered by another employee, etc.)

outgoing call status:

  • Success - successful incoming call
  • Busy - PBX received a Busy signal
  • NoAnswer - there was no answer
  • NotAvailable - PBX received a "Not Available" response
  • NotAllowed - Call prohibited
 string when event=COMPLETED
record_link link to call record, if the PBX can provide it immediately; if not, the link is sent using the record command string not required, when event=COMPLETED
planfix_token Planfix key (token), specified in the integration settings string
data_name_field_datatag additional data that needs to be entered into the call's data tag. field name in the data tag must match the text after "data_"; there can be as many parameters as there are fields to fill in, with one parameter per field. For example, if you pass the parameters data_utm_source and data_utm_medium in the API call, then to store this data in Planfix, you must add String fields to the Call data tag called utm_source and utm_medium string when event=COMPLETED
Retrieved from "http://planfix.com/help/index.php?title=VoIP_API&oldid=15310"