API commands and script examples

From Planfix
Revision as of 11:08, 20 August 2024 by Dmitri (talk | contribs)
Jump to: navigation, search

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

Команда для получения номера задачи в ПланФиксе.


Параметры запроса:

Имя Описание Тип/формат данных Примечание
cmd тип операции, в данном случае getContact string
providerId идентификатор сторонней системы string не должен содержать символ "~"
planfix_token ключ (token) ПланФикса, указанный в настройках интеграции string
chatId уникальный id чата string


Пример запроса:

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

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


Варианты ответа:

HTTP код Тело Описание
200 {number: 1014} ОК
400 { error: "task not found" } Задача не найдена
401 { error: "Invalid token" } Передан неверный ключ (token)

Commands from Planfix to third-party chats

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 необязательный, допускается несколько
attachments[url] attachment (link) string необязательный, допускается несколько


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


Go To