API commands and script examples
From Planfix
Commands from third-party chats to Planfix
newMessage (POST)
Command to send a new message from a third-party chat to Planfix.
Call 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 | not required, can be used as needed. |
| chatId | unique chat ID | string | |
| planfix_token | Planfix key (token), specified in the integration settings | string | |
| message | message content | string | |
| title | message header | string | not required; 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 | not required |
| contactIco | contact's picture | string | not required |
| contactEmail | contact's email | string | not required |
| contactPhone | contact's phone number | string | not required |
| contactData | additional contact data | string | not required |
| attachments[name] | attachment (name) | string | not required, several allowed |
| attachments[url] | attachment (link) | string | not required, several allowed |
| isEcho | outgoing message | boolean | not required |
| userEmail | outgoing message author | string | not required |
| 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 | not required |
Sample call:
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.
Call 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 call:
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.
Call 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 call:
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.
Call 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 | not required |
| contactIco | contact's picture | string | not required |
| contactEmail | contact's email | string | not required |
| contactPhone | contact's phone number | string | not required |
| contactData | additional contact data | string | not required |
Sample call:
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=the gas boilers came as expected
Response options::
| HTTP code | Body | Description |
|---|---|---|
| 200 | ОК | |
| 400 | { error: "Invalid parameters" } | Incorrect parameters passed |
| 401 | { error: "Invalid token" } | Invalid key (token) passed |
newMessage (POST)
Command for passing a new message from Planfix to a third-party chat.
Call 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 | not required |
| channel | additional channel identifier on the third-party system side | string | not required, can be used as needed |
| token | third-party chat key (token), specified in the integration settings | string | |
| message | message content | 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 | not required, several allowed |
| attachments[url] | attachment (link) | string | not required, several allowed |
Sample call:
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 |