Chat API
API Overview
APIs let you link any of your chats or similar systems (communication threads with users) to Planfix. Integrating Planfix and third-party chats lets you do the following:
- receive messages from third-party systems in Planfix, as well as data about contacts from these systems, in real-time;
- receive responses from Planfix in third-party systems, in real-time.
The integration must be two-way. Planfix sends requests to the third-party system's specified entry points, while the third-party system sends other requests to Planfix's single entry point.
The exchange happens over HTTPS. Authorization is done through an address from Planfix or the third-party system, and the authorization key received when setting up the integration. How authorization and communication work
HTTPS:
- Calls to Planfix are accepted only over HTTPS. This ensures that the systems can securely communicate over the Internet.
- To keep your data secure, please use HTTPS to receive calls in your system 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 system 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.
Calls from third-party systems 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
Calls from Planfix to third-party systems:
- Planfix will send all calls 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 call.
- Requests are passed in the format application/x-www-form-urlencoded
Responses
- Planfix sends all responses to calls from third-party systems in JSON format in the body of the response.
- Third-party systems must send all responses to Planfix calls in JSON format in the body of the response.
Connecting in the Planfix interface
To connect and configure the integration, navigate to Integrations > Chats.
Click on Add chat in the newly opened area. A window will open for integration settings.
This window is where you will find the address for sending requests to Planfix (it's different for every account) and the token. This is also where you will add the data from the chat you are integrating. The providerId is the third-party system's identifier. You can set it to anything. It's needed so you can differentiate calls, should you use this API to link several different chats with overlapping identifiers.