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