API commands and script examples: Difference between revisions

From Planfix
Jump to: navigation, search
No edit summary
No edit summary
 
(45 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Commands from third-party chats to 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:'''
{| 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 || 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.


'''newMessage (POST)'''
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
|-
|}


Command to send a new message from a third-party chat to Planfix.  
'''Sample call:'''
<source lang="bash">
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
</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
|-
|}
== '''getTask''' ==
Command to retrieve the task number from Planfix.


'''Call parameters:'''
'''Call parameters:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание
!width="150"|Name !!width="50%"| Description !!width="150"| Data type/format !! Note
|-
|-
|cmd || тип операции, в данном случае newMessage || string ||  
|cmd || type of operation, in this case getTask || string ||  
|-
|-
|providerId|| идентификатор сторонней системы || string || не должен содержать символ "~"
|providerId|| third-party system identifier || string || нcannot contain the symbol "~"
|-
|-
|channel|| дополнительный идентификатор канала на стороне сторонней системы || string || не обязателен, может использоваться при необходимости.
|planfix_token || Planfix key (token), specified in the integration settings || string ||  
|-
|-
|chatId|| уникальный id чата || string ||  
|chatId|| unique chat ID || string ||  
|-
|-
|planfix_token || ключ (token) ПланФикса, указанный в настройках интеграции || 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
|-
|-
|message|| содержимое сообщения || string ||  
|200|| {number: 1014} || ОК
|-
|-
|title|| заголовок сообщения || string || необязательный, если есть, используется для формирования названия задачи
|400 || { error: "task not found" } || Task not found
|-
|-
|contactId|| уникальный идентификатор контакта || string ||  
|401|| { error: "Invalid token" } || Invalid key (token) passed
|-
|-
|contactName|| имя контакта || string ||  
|}
== '''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
|-
|-
|contactLastName|| фамилия контакта || string || необязательный
|cmd || type of operation, in this case getContact || string ||  
|-
|-
|contactIco|| фото контакта || string || необязательный
|providerId|| third-party system identifier || string ||cannot contain the symbol "~"
|-
|-
|contactEmail|| email контакта || string || необязательный
|planfix_token || Planfix key (token), specified in the integration settings || string ||  
|-
|-
|contactPhone|| телефон контакта || string || необязательный
|contactId|| contact's unique identifier|| string ||  
|-
|-
|contactData|| дополнительные данные контакта || 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
|-
|-
|attachments[name]|| вложение (имя) || string || необязательный, допускается несколько
|200|| {number: 1058} || ОК
|-
|-
|attachments[url]|| вложение (ссылка) || string || необязательный, допускается несколько
|400 || { error: "unknown contact" } || Contact not found
|-
|-
| isEcho || исходящее сообщение || boolean || необязательный
|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">
<source lang="bash">
POST https://test.planfix.ru/chat/api
POST https://test.planfix.com/webchat/api


cmd=newMessage
cmd=updateContact
providerId=superchat
providerId=superchat
chatId=EFHASFN1239351
planfix_token=303cb962ac59075b964b07152d234b70
planfix_token=303cb962ac59075b964b07152d234b70
message=Здравствуйте, есть вопрос
contactId=57487124
contactId=57487124
contactName=Иван
contactName=Mike
contactLastName=Иванов
contactLastName=Wilson
contactIco=https://superchat.io/avatars/183712.png
contactIco=https://superchat.io/avatars/183712.png
contactEmail=ivan@ivanov.com
contactEmail=mike@wilson.com
contactPhone=79051234567
contactPhone=190512345670
contactData=пришёл по запросу газовые котлы
contactData=came as a result of the gas boilers call
attachments[name]=фото1.jpg
attachments[url]=https://superchat.io/files/5444.jpg
attachments[name]=фото2.jpg
attachments[url]=https://superchat.io/files/5445.jpg
</source>
</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% "
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|HTTP код !!width="50%"| Тело !! Описание
!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
|-
|}
 
'''Sample call:'''
<source lang="bash">
POST https://test.planfix.com/webchat/api
 
cmd=messageStatus
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
messageId=4188849
messageStatus=read
</source>
 
'''Response options:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|HTTP code !!width="50%"| Body !! Description
|-
|-
|200|| || ОК
|200|| || ОК
|-
|-
|400 || { error: "Invalid parameters" } || Переданы некорректные параметры
|400 || { error: "Invalid parameters" } || Incorrect parameters passed
|-
|-
|401|| { error: "Invalid token" } || Передан неверный ключ (token)
|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:'''
{| 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 ||
|-
|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:'''
<source lang="bash">
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
</source>


----


'''newMessage (POST)'''
'''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 ||
|-
|contactId|| contact's unique identifier || string ||
|-
|}


Команда для передачи нового сообщения из ПланФикса в сторонний чат.
'''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
|-
|}
== '''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% "
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание
!width="150"|Name !!width="50%"| Description !!width="150"| Data type/format !! Note
|-
|-
|cmd || тип операции, в данном случае newMessage || string ||  
|cmd || type of operation, in this case newMessage || string ||  
|-
|-
|providerId|| идентификатор сторонней системы || string ||  
|providerId|| third-party system identifier || string ||  
|-
|-
|chatId|| уникальный id чата || string ||  
|contactPhone|| contact's phone number|| string ||  
|-
|-
|contactPhone|| телефон контакта || string || необязательный
|channel|| additional channel identifier on the third-party system side || string || not required, can be used as needed.
|-
|-
|channel|| дополнительный идентификатор канала на стороне сторонней системы || string || не обязателен, может использоваться при необходимости.
|token || third-party chat key (token), specified in the integration settings || string ||  
|-
|-
|token || ключ (token) стороннего чата, указанный в настройках интеграции || string ||  
|message|| message content || string ||  
|-
|-
|message|| содержимое сообщения || string ||  
|messageId|| message identifier || string ||  
|-
|-
|userName|| имя ответившего сотрудника || string ||  
|userName|| first name of employee who responded || string ||  
|-
|-
|userLastName|| фамилия ответившего сотрудника || string ||  
|userLastName|| last name of employee who responded || string ||  
|-
|-
|userIco|| аватар ответившего сотрудника || string ||  
|userIco|| profile picture of employee who responded || string ||  
|-
|-
|taskEmail|| емайл-адрес задачи в ПланФиксе || string ||
|taskEmail|| task email address in Planfix || string ||
|-
|-
|attachments[name]|| вложение (имя) || string || необязательный, допускается несколько
|attachments[name]|| attachment (name) || string || not required, several allowed
|-
|-
|attachments[url]|| вложение (ссылка) || string || необязательный, допускается несколько
|attachments[url]|| attachment (link) || string || not required, several allowed
|-
|-
|}
|}




'''Пример запроса:'''
'''Sample call:'''
<source lang="bash">
<source lang="bash">
POST https://domain/planfix_api.php
POST https://domain/planfix_api.php
Line 139: Line 386:
cmd=newMessage
cmd=newMessage
providerId=superchat
providerId=superchat
chatId=EFHASFN1239351
contactPhone=190512345670
token=202cb962ac59075b964b07152d234b70
token=202cb962ac59075b964b07152d234b70
message=Здравствуйте, что вас интересует?
message=Hello, what are you interested in?
userName=Петр
userName=Mike
userLastName=Петров
userLastName=Wilson
userIco=https://account.planfix.ru/?action=getuserpic&id=77
userIco=https://account.planfix.ru/?action=getuserpic&id=77
attachments[name]=файл1.doc
attachments[name]=file1.doc
attachments[url]=https://account.planfix.ru/file/aadkapdoa5456454
attachments[url]=https://account.planfix.com/file/aadkapdoa5456454
attachments[name]=файл2.doc
attachments[name]=file2.doc
attachments[url]=https://account.planfix.ru/file/aadkapdoa5456455
attachments[url]=https://account.planfix.com/file/aadkapdoa5456455
</source>
</source>


'''Параметры ответа:'''
 
'''Response parameters:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание
!width="150"|Name !!width="50%"| Description !!width="150"| Data type/format !! Note
|-
|-
|chatId|| уникальный id чата || string ||  
|chatId|| unique chat ID || string || required
|-
|-
|contactId|| уникальный идентификатор контакта || string ||  
|contactId|| contact's unique identifier || string || required
|-
|-
|}
|}


'''Варианты ответа:'''
 
'''Response options:'''
{| class="wikitable" style="margin-top: 1em; width:100% "
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|HTTP код !!width="50%"| Тело !! Описание
!width="150"|HTTP code !!width="50%"| Body !! Description
|-
|-
|200|| { chatId: "chatId", contactId: "contactId" } || ОК
|200|| { chatId: "chatId", contactId: "contactId" } || ОК
|-
|-
|400 || { error: "Invalid parameters" } || Переданы некорректные параметры
|400 || { error: "Invalid parameters" } || Incorrect parameters passed
|-
|-
|401|| { error: "Invalid token" } ||  Передан неверный ключ (token)
|401|| { error: "Invalid token" } ||  Invalid key (token) passed
|-
|-
|}
|}


 
== Go To ==
== Перейти ==
*[[Chat API]]
*[[API для чатов]]
*[[Integrations]]
*[[Разработчикам: API]]
*[[Planfix]]
*[[Интеграции]]

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"