VoIP API

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:

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

A window will open with integration settings:

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)
• setup (POST)

From cloud PBX to Planfix

• contact (POST)
• event (POST)
• record (POST)
• ping (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	Note
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

Setup

The command is triggered when you activate the integration in Planfix. It automatically enables the integration on the PBX side. If the response status is not 200, an error message with the response text will be shown in Planfix.

• Call parameters:

Name	Description	Data type/format	Note
cmd	type of operation, in this case setup	string
token	cloud PBX key (token) set in the integration settings	string
planfix_token	Planfix key (token), specified in the integration settings	string
planfix_url	The URL for sending requests to Planfix	string

• Sample API call:

POST https://domain/planfix_api.php

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

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	Note
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	Note
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

• Sample API call

POST https://test.planfix.ru/tel/api

cmd=event
type=out
event=COMPLETED
phone=79101234567
ext=102
callid=D10D0EB124F4E64AF4EA-1511
duration=124
is_recorded=1
status=Success
record_link=https://link/file.mp3
planfix_token=303cb962ac59075b964b07152d234b70
data_utm_source=site.io
data_utm_medium=banner

• Response options

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

record

Notification contains information about call record. Planfix expects this notification if there is no record_link parameter in an event command with event=COMPLETED and is_recorded=1. It makes sense to use a notification if records are saved to the cloud PBX in such a way that the link can only be generated at a later point.

The link must be permanent, so that, depending on the integration settings:

• the associated file can be saved in Planfix,
• it can be used to listen to recordings directly from the PBX servers. (users actively request this setting and it will be implemented shortly for telephony that supports it).

• Call parameters

Name	Description	Data type/format	Note
cmd	type of operation, in this case record	string
callid	unique call ID	string
is_temp	the link is temporary and can only be used to save a file to Planfix once; cannot listen to call recording from cloud PBX	0/1	not required, default is 0 if not used
record_link	link to call record	string
planfix_token	Planfix key (token), specified in the integration settings	string

• Sample API call

POST https://test.planfix.ru/tel/api

cmd=record
callid=D10D0EB124F4E64AF4EA-1511
record_link=https://link/file.mp3
planfix_token=303cb962ac59075b964b07152d234b70

• Response options

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

ping

With this command, you can check the correctness of the connection and the parameters set on the Planfix side.

• Call parameters:

Name	Description	Data type/format	Note
cmd	тype of operation, in this case ping	string
planfix_token	Planfix key (token), specified in the integration settings	string

• Sample API call:

POST https://test.planfix.com/tel/api

cmd=ping
planfix_token=303cb962ac59075b964b07152d234b70

Sample API call:

HTTP code	Body	Description
200	{ pbxToken: "value", pbxUrl: "https://domain.com/path" }	pbxToken - cloud PBX key (token) set in the integration settings, pbxUrl - the PBX address, specified in the integration settings.
401	{ error: "Invalid token" }	Invalid key (token) passed

Example of using the API for an incoming call to a group of employees

• call initiated:
  • a request is sent to each employee with their ext and INCOMING; the call identifier is the same for all employees. Planfix displays a window that shows that a call is in progress.
• one of the employees picks up the phone:
  • ACCEPTED is sent for this employee.
  • COMPLETED with Canceled is sent for the rest, and the call window goes away for them (the call ID is the same for all employees in the group and is the same as in the start event).
• call completed:
  • COMPLETED with Success is sent with and the ext of the employee who picked up the phone. Planfix shows a window saying the call was completed and records a data tag.

Example of using the API for a call to a group, with sequential transfer between employees

• сall started
  • a request is sent to the first employee with their ext, INCOMING, and the call ID. Planfix displays a window indicating an incoming call.
• the first employee does not answer, the call is transferred to the next employee
  • a COMPLETED request with Canceled is sent for the first employee, and the call window disappears.
  • an INCOMING request is sent to the second employee.

(the call ID remains the same as the initial event.)

• The second employee does not answer, the call is transferred to the next employee
  • a COMPLETED request with Canceled is sent for the second employee, and the call window disappears.
  • an INCOMING request is sent to the third employee.

(the call ID remains the same as the initial event.)

• an employee answers the call
  • an ACCEPTED request is sent for the employee.

(the call ID remains the same as the initial event.)

• call is completed
  • a COMPLETED request with Success and the ext of the employee who answered the call is sent. Planfix displays a window showing the call's completion, and the data tags are recorded.

Go To

• API