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)
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:
|
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:
outgoing call status:
|
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 | Notes |
|---|---|---|---|
| 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 |
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.