API commands and script examples: Difference between revisions

From Planfix
Jump to: navigation, search
No edit summary
No edit summary
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==Commands from third-party chats to Planfix==
==Commands from third-party chats to Planfix==
 
== '''newMessage (POST)''' ==
----
 
 
'''newMessage (POST)'''
 
Command to send a new message from a third-party chat to Planfix.  
Command to send a new message from a third-party chat to Planfix.  
----


'''Call parameters:'''
'''Call parameters:'''
Line 49: Line 41:
| isEcho || outgoing message || boolean || not required
| isEcho || outgoing message || boolean || not required
|-
|-
| userEmail || outgoing message author || string || not required
| userEmail || email of the author of the outgoing message || string || not required 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 || not required
|-
|-
|}
|}


'''Sample call:'''
'''Sample call:'''
<source lang="bash">
<source lang="bash">
POST https://test.planfix.ru/chat/api
POST https://test.planfix.com/webchat/api


cmd=newMessage
cmd=newMessage
Line 75: Line 73:
attachments[url]=https://superchat.io/files/5445.jpg
attachments[url]=https://superchat.io/files/5445.jpg
</source>
</source>


'''Response options:'''
'''Response options:'''
Line 88: Line 85:
|-
|-
|}
|}
== '''getTask''' ==
Command to retrieve the task number from Planfix.


'''Call parameters:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Name !!width="50%"| Description !!width="150"| 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:'''
<source lang="bash">
POST https://test.planfix.com/webchat/api
cmd=getTask
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
chatId=EFHASFN1239351
</source>
'''Response options:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|HTTP code !!width="50%"| 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:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Name !!width="50%"| Description !!width="150"| 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:'''
<source lang="bash">
POST https://test.planfix.com/webchat/api
cmd=getContact
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
contactId=57487124
</source>
'''Response options:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|HTTP code !!width="50%"|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:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Name !!width="50%"| Description !!width="150"| 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:'''
<source lang="bash">
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 call
</source>


'''Response options::'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|HTTP code !!width="50%"| 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.


'''Call parameters::'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Name!!width="50%"| Description !!width="150"| 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 call 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 ||  not required
|-
|}


==Commands from Planfix to third-party chats==
'''Sample call:'''
<source lang="bash">
POST https://test.planfix.com/webchat/api


----
cmd=messageStatus
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
messageId=4188849
messageStatus=read
</source>


'''newMessage (POST)'''
'''Response options:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|HTTP code !!width="50%"| Body !! Description
|-
|200|| || ОК
|-
|400 || { error: "Invalid parameters" } || Incorrect parameters passed
|-
|401|| { error: "Invalid token" } || Invalid key (token) passed
|-
|}
== Commands from Planfix to an external chat ==
== '''newMessage (POST)''' ==


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


'''Call parameters:'''
'''Call parameters:'''
Line 128: Line 296:
|taskEmail|| task email address in Planfix || string ||
|taskEmail|| task email address in Planfix || string ||
|-
|-
|attachments[name]|| attachment (name) || string || необязательный, допускается несколько
|attachments[name]|| attachment (name) || string || not required, several allowed
|-
|-
|attachments[url]|| attachment (link) || string || необязательный, допускается несколько
|attachments[url]|| attachment (link) || string || not required, several allowed
|-
|-
|}
|}
Line 175: Line 343:
|-
|-
|}
|}
== '''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.


'''Call parameters:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Name !!width="50%"| Description !!width="150"| 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 || not required, 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 || not required, several allowed
|-
|attachments[url]|| attachment (link) || string || not required, several allowed
|-
|}
'''Sample call:'''
<source lang="bash">
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.ru/?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
</source>
'''Response parameters:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Name !!width="50%"| Description !!width="150"| Data type/format !! Note
|-
|chatId|| unique chat ID || string || required
|-
|contactId|| contact's unique identifier || string || required
|-
|}
'''Response options:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|HTTP code !!width="50%"| Body !! Description
|-
|200|| { chatId: "chatId", contactId: "contactId" } || ОК
|-
|400 || { error: "Invalid parameters" } || Incorrect parameters passed
|-
|401|| { error: "Invalid token" } ||  Invalid key (token) passed
|-
|}


== Go To ==
== Go To ==
Line 181: Line 426:
*[[Integrations]]
*[[Integrations]]
*[[Planfix]]
*[[Planfix]]
__FORCETOC__

Latest revision as of 09:16, 21 August 2024

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 email of the author of the outgoing message string not required 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 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=came as a result of the gas boilers call

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.

Call 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 call 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 not required

Sample call: 

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

Commands from Planfix to an external chat

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

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.


Call 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 not required, 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 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
contactPhone=190512345670
token=202cb962ac59075b964b07152d234b70
message=Hello, what are you interested in?
userName=Mike
userLastName=Wilson
userIco=https://account.planfix.ru/?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

Go To

Retrieved from "http://planfix.com/help/index.php?title=API_commands_and_script_examples&oldid=21564"