API commands and script examples

newMessage (POST)

Command to send a new message from a third-party chat to Planfix.

Request parameters:

Name	Description	Data type/format	Note
cmd	type of operation, in this case newMessage	string
providerId	third-party system identifier	string	cannot contain the symbol "~"
channel	additional channel identifier on the third-party system side	string	optional, can be used as needed.
chatId	unique chat ID	string	optional;
planfix_token	Planfix key (token), specified in the integration settings	string
message	message content	string
messageId	message identifier in the third-party system	string	if provided, it is saved in Planfix and used later for editing or deleting this message with the editMessage and deleteMessage commands
title	message header	string	optional; if it exists, it's used to create task names
contactId	contact's unique identifier	string
contactName	contact's first name	string
contactLastName	contact's last name	string	optional
contactIco	contact's picture	string	optional
contactEmail	contact's email	string	optional
contactPhone	contact's phone number	string	optional
contactData	additional contact data	string	optional
attachments[name]	attachment (name)	string	optional, several allowed
attachments[url]	attachment (link)	string	optional, several allowed
isEcho	outgoing message	boolean	optional
userEmail	email of the author of the outgoing message	string	optional if this field is left blank, the author is the employee specified in the integration settings. If no one is specified there, it will default to the employee who set up the integration by default.
data_name_of_task_custom_field	additional data that can be included in a task created in Planfix for this chat. The field's name in the task must match the text after data_. You can insert as many such parameters as there are fields to fill in, one parameter per field. For example, if you pass the parameters' data_utm_source and data_utm_medium in the request, to save this data in Planfix, you must add fields of type "String" with the names utm_source and utm_medium to the task template	string	optional

Sample request:

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

cmd=newMessage
providerId=superchat
chatId=EFHASFN1239351
planfix_token=303cb962ac59075b964b07152d234b70
message=Hello, I have a question
contactId=57487124
contactName=Ivan
contactLastName=Ivanov
contactIco=https://superchat.io/avatars/183712.png
contactEmail=ivan@ivanov.com
contactPhone=79051234567
contactData=the gas boilers came as expected
attachments[name]=photo1.jpg
attachments[url]=https://superchat.io/files/5444.jpg
attachments[name]=photo2.jpg
attachments[url]=https://superchat.io/files/5445.jpg

Response options:

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

getTask

Command to retrieve the task number from Planfix.

Request parameters:

Name	Description	Data type/format	Note
cmd	type of operation, in this case getTask	string
providerId	third-party system identifier	string	нcannot contain the symbol "~"
planfix_token	Planfix key (token), specified in the integration settings	string
chatId	unique chat ID	string

Sample request:

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

cmd=getTask
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
chatId=EFHASFN1239351

Response options:

HTTP code	Body	Description
200	{number: 1014}	ОК
400	{ error: "task not found" }	Task not found
401	{ error: "Invalid token" }	Invalid key (token) passed

getContact

Command to retrieve the contact number from Planfix.

Request parameters:

Name	Description	Data type/format	Note
cmd	type of operation, in this case getContact	string
providerId	third-party system identifier	string	cannot contain the symbol "~"
planfix_token	Planfix key (token), specified in the integration settings	string
contactId	contact's unique identifier	string

Sample request:

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

cmd=getContact
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
contactId=57487124

Response options:

HTTP code	Body	Description
200	{number: 1058}	ОК
400	{ error: "unknown contact" }	Contact not found
401	{ error: "Invalid token" }	Invalid key (token) passed

updateContact

Command for updating contact data in Planfix through an external chat.

Request parameters:

Name	Description	Data type/format	Note
cmd	type of operation, in this case updateContact	string
providerId	third-party system identifier	string	cannot contain the symbol "~"
planfix_token	Planfix key (token), specified in the integration settings	string
contactId	contact's unique identifier	string
contactName	contact's first name	string
contactLastName	contact's last name	string	optional
contactIco	contact's picture	string	optional
contactEmail	contact's email	string	optional
contactPhone	contact's phone number	string	optional
contactData	additional contact data	string	optional

Sample request:

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

cmd=updateContact
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
contactId=57487124
contactName=Mike
contactLastName=Wilson
contactIco=https://superchat.io/avatars/183712.png
contactEmail=mike@wilson.com
contactPhone=190512345670
contactData=came as a result of the gas boilers request

Response options::

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

messageStatus

Command to send the message delivery/reading status to Planfix.

Request parameters::

Name	Description	Data type/format	Note
cmd	тype of operation, in this case messageStatus	string
providerId	third-party system identifier	string	cannot contain the symbol "~"
planfix_token	Planfix key (token), specified in the integration settings	string
messageId	message identifier - messageId from the request for sending a message from Planfix to an external chat	string
messageStatus	delivery status	string	error - error, an error icon is displayed in Planfix sent - sent, a single checkmark is displayed in Planfix read - read, two checkmarks are displayed in Planfix any other value is treated as sent
messageStatusText	additional information about the delivery status, if needed	string	optional

Sample request:

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

cmd=messageStatus
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
messageId=4188849
messageStatus=read

Response options:

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

newMessage

Command for passing a new message from Planfix to a third-party chat.

Request parameters:

Name	Description	Data type/format	Note
cmd	type of operation, in this case newMessage	string
providerId	third-party system identifier	string
chatId	unique chat ID	string
contactPhone	contact's phone number	string	optional
channel	additional channel identifier on the third-party system side	string	optional, can be used as needed
token	third-party chat key (token), specified in the integration settings	string
message	message content	string
messageId	message identifier	string
userName	first name of employee who responded	string
userLastName	last name of employee who responded	string
userIco	profile picture of employee who responded	string
taskEmail	task email address in Planfix	string
attachments[name]	attachment (name)	string	optional, several allowed
attachments[url]	attachment (link)	string	optional, several allowed

Sample request:

POST https://domain/planfix_api.php

cmd=newMessage
providerId=superchat
chatId=EFHASFN1239351
token=202cb962ac59075b964b07152d234b70
message=Hello, how can I help you?
userName=Peter
userLastName=Peterson
userIco=https://account_name.planfix.com/?action=getuserpic&id=77
attachments[name]=file1.doc
attachments[url]=https://account_name.planfix.com/file/aadkapdoa5456454
attachments[name]=file2.doc
attachments[url]=https://account_name.planfix.com/file/aadkapdoa5456455

Response parameters:

Name	Description	Data type/format	Note
chatId	unique chat ID	string
contactId	contact's unique identifier	string

Response options:

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

newMessage ( first message from Planfix)

Command to send the first message from Planfix to an external chat if the option "Show "Message" button in contact cards if phone number is set" is activated.

Request parameters:

Name	Description	Data type/format	Note
cmd	type of operation, in this case newMessage	string
providerId	third-party system identifier	string
contactPhone	contact's phone number	string
channel	additional channel identifier on the third-party system side	string	optional, can be used as needed.
token	third-party chat key (token), specified in the integration settings	string
message	message content	string
messageId	message identifier	string
userName	first name of employee who responded	string
userLastName	last name of employee who responded	string
userIco	profile picture of employee who responded	string
taskEmail	task email address in Planfix	string
attachments[name]	attachment (name)	string	optional, several allowed
attachments[url]	attachment (link)	string	optional, several allowed

Sample request:

POST https://domain/planfix_api.php

cmd=newMessage
providerId=superchat
contactPhone=190512345670
token=202cb962ac59075b964b07152d234b70
message=Hello, what are you interested in?
userName=Mike
userLastName=Wilson
userIco=https://account.planfix.com/?action=getuserpic&id=77
attachments[name]=file1.doc
attachments[url]=https://account.planfix.com/file/aadkapdoa5456454
attachments[name]=file2.doc
attachments[url]=https://account.planfix.com/file/aadkapdoa5456455

Response parameters:

Name	Description	Data type/format	Note
chatId	unique chat ID	string	required
contactId	contact's unique identifier	string	required

Response options:

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

editMessage

Command to edit a message previously sent from a third-party chat to Planfix.

The message in Planfix is searched by the messageId parameter that was passed in the newMessage command. If messageId was not passed when creating the message or a message with that identifier is not found, the message text in Planfix will not be changed.

Name	Description	Type/format	Note
cmd	operation type, in this case editMessage
providerId	identifier of the third-party system	string	must not contain the "~" character
planfix_token	Planfix key (token) specified in the integration settings
messageId	message identifier in the third-party system	string	must match the messageId previously passed in the newMessage command
message	new message content	string

Sample request:

POST https://test.planfix.com/webchat/api 
cmd=editMessage 
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70 
messageId=msg-4188849 
message=Здравствуйте, уточнил вопрос 

Response options:

HTTP code	Body	Description
200	OK	Request accepted
400	{ error: "Invalid parameters" }	Incorrect parameters were provided
401	{ error: "Invalid token" }	Invalid key (token) provided

deleteMessage

Command to delete a message previously sent from a third-party chat to Planfix.

The message in Planfix is searched by the messageId parameter that was passed in the newMessage command. If messageId was not passed when creating the message or a message with that identifier is not found, the message in Planfix will not be deleted.

Name	Description	Type/format	Note
cmd	operation type, in this case deleteMessage	string
providerId	identifier of the third-party system	string	must not contain the "~" character
planfix_token	Planfix key (token) specified in the integration settings	string
messageId	message identifier in the third-party system	string	must match the messageId previously passed in the newMessage command

Sample request:

POST https://test.planfix.com/webchat/api 
cmd=deleteMessage providerId=superchat 
planfix_token=303cb962ac59075b964b07152d234b70 
messageId=msg-4188849 

Response options:

HTTP code	Body	Description
200	OK	Request accepted
400	{ error: "Invalid parameters" }	Incorrect parameters were provided
401	{ error: "Invalid token" }	Invalid key (token) provided

Go To

• Chat API
• Integrations
• Planfix