Список команд API для чатов — различия между версиями

Материал из ПланФикс
Перейти к: навигация, поиск
 
(не показаны 32 промежуточные версии 2 участников)
Строка 1: Строка 1:
−
=== Команды от стороннего чата к ПланФиксу ===
+
==Команды от стороннего чата к ПланФиксу==
 +
 
 +
----
 +
 
 +
 
 +
==newMessage==
  
−
==== newMessage ====
 
 
Команда для передачи нового сообщения из стороннего чата в ПланФикс.  
 
Команда для передачи нового сообщения из стороннего чата в ПланФикс.  
 +
 +
----
  
  
Строка 42: Строка 48:
 
|-
 
|-
 
| isEcho || исходящее сообщение || boolean || необязательный
 
| isEcho || исходящее сообщение || boolean || необязательный
 +
|-
 +
| userEmail || email сотрудника-автора исходящего сообщения || string || необязательный, при отсутствии автором будет сотрудник указанный в настройках интеграции, при отсутствии кого-либо и там - сотрудник подключавший интеграцию.
 +
|-
 +
|data_имя_поля_задачи|| дополнительные данные, которые надо внести в создаваемую в планфиксе задачу для этого чата.
 +
 +
 +
Имя поля в задаче должно точно совпадать с текстом после data_, таких параметров может быть столько, сколько полей заполняется, по одному на каждое поле.
 +
 +
К примеру, если вы передаете в запросе параметры data_utm_source и data_utm_medium, то для сохранения этих данных в ПланФиксе, необходимо чтобы в шаблоне задачи были добавлены поля типа Строка с названиями utm_source и utm_medium
 +
|| string || необязательный
 
|-
 
|-
 
|}
 
|}
Строка 80: Строка 96:
 
|-
 
|-
 
|}
 
|}
 +
 +
 +
----
 +
 +
 +
==updateContact==
 +
 +
Команда для обновления данных контакта в ПланФиксе сторонним чатом.
 +
 +
----
 +
 +
 +
'''Параметры запроса:'''
 +
{| class="wikitable" style="margin-top: 1em; width:100% "
 +
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание
 +
|-
 +
|cmd || тип операции, в данном случае updateContact || string ||
 +
|-
 +
|providerId|| идентификатор сторонней системы || string || не должен содержать символ "~"
 +
|-
 +
|planfix_token || ключ (token) ПланФикса, указанный в настройках интеграции || string ||
 +
|-
 +
|contactId|| уникальный идентификатор контакта || string ||
 +
|-
 +
|contactName|| имя контакта || string ||
 +
|-
 +
|contactLastName|| фамилия контакта || string || необязательный
 +
|-
 +
|contactIco|| фото контакта || string || необязательный
 +
|-
 +
|contactEmail|| email контакта || string || необязательный
 +
|-
 +
|contactPhone|| телефон контакта || string || необязательный
 +
|-
 +
|contactData|| дополнительные данные контакта || string || необязательный
 +
|-
 +
|}
 +
 +
 +
'''Пример запроса:'''
 +
<source lang="bash">
 +
POST https://test.planfix.ru/chat/api
 +
 +
cmd=updateContact
 +
providerId=superchat
 +
planfix_token=303cb962ac59075b964b07152d234b70
 +
contactId=57487124
 +
contactName=Пётр
 +
contactLastName=Петров
 +
contactIco=https://superchat.io/avatars/183712.png
 +
contactEmail=petr@petrov.com
 +
contactPhone=79051234567
 +
contactData=пришёл по запросу газовые котлы
 +
</source>
 +
 +
 +
'''Варианты ответа:'''
 +
{| class="wikitable" style="margin-top: 1em; width:100% "
 +
!width="150"|HTTP код !!width="50%"| Тело !! Описание
 +
|-
 +
|200|| || ОК
 +
|-
 +
|400 || { error: "Invalid parameters" } || Переданы некорректные параметры
 +
|-
 +
|401|| { error: "Invalid token" } ||  Передан неверный ключ (token)
 +
|-
 +
|}
 +
 +
==messageStatus==
 +
 +
Команда для передачи в ПланФикс статуса отправки / прочтения сообщения
 +
 +
----
 +
 +
 +
'''Параметры запроса:'''
 +
{| class="wikitable" style="margin-top: 1em; width:100% "
 +
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание
 +
|-
 +
|cmd || тип операции, в данном случае messageStatus || string ||
 +
|-
 +
|providerId|| идентификатор сторонней системы || string || не должен содержать символ "~"
 +
|-
 +
|planfix_token || ключ (token) ПланФикса, указанный в настройках интеграции || string ||
 +
|-
 +
|messageId|| идентификатор сообщения - messageId из запроса отправки сообщения из ПланФикса в сторонний чат|| string ||
 +
|-
 +
|messageStatus|| статус отправки || string ||
 +
*error - ошибка, в ПланФиксе рисуется знак ошибки
 +
*sent - отправлено, в ПланФиксе рисуется одна галочка
 +
*read - прочитано, в ПланФиксе рисуется две галочки
 +
любое другое значение обрабатывается как sent
 +
|-
 +
|messageStatusText|| дополнительная информация о статусе отправки, если необходима|| string || необязательный
 +
|-
 +
|}
 +
 +
 +
'''Пример запроса:'''
 +
<source lang="bash">
 +
POST https://test.planfix.ru/chat/api
 +
 +
cmd=messageStatus
 +
providerId=superchat
 +
planfix_token=303cb962ac59075b964b07152d234b70
 +
messageId=4188849
 +
messageStatus=read
 +
</source>
 +
 +
 +
'''Варианты ответа:'''
 +
{| class="wikitable" style="margin-top: 1em; width:100% "
 +
!width="150"|HTTP код !!width="50%"| Тело !! Описание
 +
|-
 +
|200|| || ОК
 +
|-
 +
|400 || { error: "Invalid parameters" } || Переданы некорректные параметры
 +
|-
 +
|401|| { error: "Invalid token" } ||  Передан неверный ключ (token)
 +
|-
 +
|}
 +
 +
 +
 +
==Команды от ПланФикса к стороннему чату==
 +
 +
----
 +
 +
==newMessage==
 +
 +
Команда для передачи нового сообщения из ПланФикса в сторонний чат.
 +
----
 +
 +
 +
'''Параметры запроса:'''
 +
{| class="wikitable" style="margin-top: 1em; width:100% "
 +
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание
 +
|-
 +
|cmd || тип операции, в данном случае newMessage || string ||
 +
|-
 +
|providerId|| идентификатор сторонней системы || string ||
 +
|-
 +
|chatId|| уникальный id чата || string ||
 +
|-
 +
|contactPhone|| телефон контакта || string || необязательный
 +
|-
 +
|contactData|| дополнительные данные контакта || string || необязательный
 +
|-
 +
|channel|| дополнительный идентификатор канала на стороне сторонней системы || string || не обязателен, может использоваться при необходимости.
 +
|-
 +
|token || ключ (token) стороннего чата, указанный в настройках интеграции || string ||
 +
|-
 +
|message|| содержимое сообщения || string ||
 +
|-
 +
|messageId|| идентификатор сообщения || string ||
 +
|-
 +
|userName|| имя ответившего сотрудника || string ||
 +
|-
 +
|userLastName|| фамилия ответившего сотрудника || string ||
 +
|-
 +
|userIco|| аватар ответившего сотрудника || string ||
 +
|-
 +
|taskEmail|| емайл-адрес задачи в ПланФиксе || string ||
 +
|-
 +
|attachments[name]|| вложение (имя) || string || необязательный, допускается несколько
 +
|-
 +
|attachments[url]|| вложение (ссылка) || string || необязательный, допускается несколько
 +
|-
 +
|}
 +
 +
 +
'''Пример запроса:'''
 +
<source lang="bash">
 +
POST https://domain/planfix_api.php
 +
 +
cmd=newMessage
 +
providerId=superchat
 +
chatId=EFHASFN1239351
 +
token=202cb962ac59075b964b07152d234b70
 +
message=Здравствуйте, что вас интересует?
 +
userName=Петр
 +
userLastName=Петров
 +
userIco=https://account.planfix.ru/?action=getuserpic&id=77
 +
attachments[name]=файл1.doc
 +
attachments[url]=https://account.planfix.ru/file/aadkapdoa5456454
 +
attachments[name]=файл2.doc
 +
attachments[url]=https://account.planfix.ru/file/aadkapdoa5456455
 +
</source>
 +
 +
'''Параметры ответа:'''
 +
{| class="wikitable" style="margin-top: 1em; width:100% "
 +
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание
 +
|-
 +
|chatId|| уникальный id чата || string ||
 +
|-
 +
|contactId|| уникальный идентификатор контакта || string ||
 +
|-
 +
|}
 +
 +
'''Варианты ответа:'''
 +
{| class="wikitable" style="margin-top: 1em; width:100% "
 +
!width="150"|HTTP код !!width="50%"| Тело !! Описание
 +
|-
 +
|200|| { chatId: "chatId", contactId: "contactId" } || ОК
 +
|-
 +
|400 || { error: "Invalid parameters" } || Переданы некорректные параметры
 +
|-
 +
|401|| { error: "Invalid token" } ||  Передан неверный ключ (token)
 +
|-
 +
|}
 +
 +
 +
== Перейти ==
 +
*[[API для чатов]]
 +
*[[Разработчикам: API]]
 +
*[[Интеграции]]

Текущая версия на 05:32, 29 марта 2021

Команды от стороннего чата к ПланФиксу


newMessage

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


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

Имя Описание Тип/формат данных Примечание
cmd тип операции, в данном случае newMessage string
providerId идентификатор сторонней системы string не должен содержать символ "~"
channel дополнительный идентификатор канала на стороне сторонней системы string не обязателен, может использоваться при необходимости.
chatId уникальный id чата string
planfix_token ключ (token) ПланФикса, указанный в настройках интеграции string
message содержимое сообщения string
title заголовок сообщения string необязательный, если есть, используется для формирования названия задачи
contactId уникальный идентификатор контакта string
contactName имя контакта string
contactLastName фамилия контакта string необязательный
contactIco фото контакта string необязательный
contactEmail email контакта string необязательный
contactPhone телефон контакта string необязательный
contactData дополнительные данные контакта string необязательный
attachments[name] вложение (имя) string необязательный, допускается несколько
attachments[url] вложение (ссылка) string необязательный, допускается несколько
isEcho исходящее сообщение boolean необязательный
userEmail email сотрудника-автора исходящего сообщения string необязательный, при отсутствии автором будет сотрудник указанный в настройках интеграции, при отсутствии кого-либо и там - сотрудник подключавший интеграцию.
data_имя_поля_задачи дополнительные данные, которые надо внести в создаваемую в планфиксе задачу для этого чата.


Имя поля в задаче должно точно совпадать с текстом после data_, таких параметров может быть столько, сколько полей заполняется, по одному на каждое поле.

К примеру, если вы передаете в запросе параметры data_utm_source и data_utm_medium, то для сохранения этих данных в ПланФиксе, необходимо чтобы в шаблоне задачи были добавлены поля типа Строка с названиями utm_source и utm_medium

string необязательный


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

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

cmd=newMessage
providerId=superchat
chatId=EFHASFN1239351
planfix_token=303cb962ac59075b964b07152d234b70
message=Здравствуйте, есть вопрос
contactId=57487124
contactName=Иван
contactLastName=Иванов
contactIco=https://superchat.io/avatars/183712.png
contactEmail=ivan@ivanov.com
contactPhone=79051234567
contactData=пришёл по запросу газовые котлы
attachments[name]=фото1.jpg
attachments[url]=https://superchat.io/files/5444.jpg
attachments[name]=фото2.jpg
attachments[url]=https://superchat.io/files/5445.jpg


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

HTTP код Тело Описание
200 ОК
400 { error: "Invalid parameters" } Переданы некорректные параметры
401 { error: "Invalid token" } Передан неверный ключ (token)



updateContact

Команда для обновления данных контакта в ПланФиксе сторонним чатом.


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

Имя Описание Тип/формат данных Примечание
cmd тип операции, в данном случае updateContact string
providerId идентификатор сторонней системы string не должен содержать символ "~"
planfix_token ключ (token) ПланФикса, указанный в настройках интеграции string
contactId уникальный идентификатор контакта string
contactName имя контакта string
contactLastName фамилия контакта string необязательный
contactIco фото контакта string необязательный
contactEmail email контакта string необязательный
contactPhone телефон контакта string необязательный
contactData дополнительные данные контакта string необязательный


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

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

cmd=updateContact
providerId=superchat
planfix_token=303cb962ac59075b964b07152d234b70
contactId=57487124
contactName=Пётр
contactLastName=Петров
contactIco=https://superchat.io/avatars/183712.png
contactEmail=petr@petrov.com
contactPhone=79051234567
contactData=пришёл по запросу газовые котлы


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

HTTP код Тело Описание
200 ОК
400 { error: "Invalid parameters" } Переданы некорректные параметры
401 { error: "Invalid token" } Передан неверный ключ (token)

messageStatus

Команда для передачи в ПланФикс статуса отправки / прочтения сообщения


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

Имя Описание Тип/формат данных Примечание
cmd тип операции, в данном случае messageStatus string
providerId идентификатор сторонней системы string не должен содержать символ "~"
planfix_token ключ (token) ПланФикса, указанный в настройках интеграции string
messageId идентификатор сообщения - messageId из запроса отправки сообщения из ПланФикса в сторонний чат string
messageStatus статус отправки string
  • error - ошибка, в ПланФиксе рисуется знак ошибки
  • sent - отправлено, в ПланФиксе рисуется одна галочка
  • read - прочитано, в ПланФиксе рисуется две галочки

любое другое значение обрабатывается как sent

messageStatusText дополнительная информация о статусе отправки, если необходима string необязательный


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

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

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


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

HTTP код Тело Описание
200 ОК
400 { error: "Invalid parameters" } Переданы некорректные параметры
401 { error: "Invalid token" } Передан неверный ключ (token)


Команды от ПланФикса к стороннему чату

newMessage

Команда для передачи нового сообщения из ПланФикса в сторонний чат.


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

Имя Описание Тип/формат данных Примечание
cmd тип операции, в данном случае newMessage string
providerId идентификатор сторонней системы string
chatId уникальный id чата string
contactPhone телефон контакта string необязательный
contactData дополнительные данные контакта string необязательный
channel дополнительный идентификатор канала на стороне сторонней системы string не обязателен, может использоваться при необходимости.
token ключ (token) стороннего чата, указанный в настройках интеграции string
message содержимое сообщения string
messageId идентификатор сообщения string
userName имя ответившего сотрудника string
userLastName фамилия ответившего сотрудника string
userIco аватар ответившего сотрудника string
taskEmail емайл-адрес задачи в ПланФиксе string
attachments[name] вложение (имя) string необязательный, допускается несколько
attachments[url] вложение (ссылка) string необязательный, допускается несколько


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

POST https://domain/planfix_api.php

cmd=newMessage
providerId=superchat
chatId=EFHASFN1239351
token=202cb962ac59075b964b07152d234b70
message=Здравствуйте, что вас интересует?
userName=Петр
userLastName=Петров
userIco=https://account.planfix.ru/?action=getuserpic&id=77
attachments[name]=файл1.doc
attachments[url]=https://account.planfix.ru/file/aadkapdoa5456454
attachments[name]=файл2.doc
attachments[url]=https://account.planfix.ru/file/aadkapdoa5456455

Параметры ответа:

Имя Описание Тип/формат данных Примечание
chatId уникальный id чата string
contactId уникальный идентификатор контакта string

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

HTTP код Тело Описание
200 { chatId: "chatId", contactId: "contactId" } ОК
400 { error: "Invalid parameters" } Переданы некорректные параметры
401 { error: "Invalid token" } Передан неверный ключ (token)


Перейти

Источник — «http://planfix.ru/wiki/index.php?title=Список_команд_API_для_чатов&oldid=31604»