Список команд API для чатов — различия между версиями
SliZzzZ (обсуждение | вклад) |
Seva (обсуждение | вклад) |
||
(не показано 17 промежуточных версий 2 участников) | |||
Строка 1: | Строка 1: | ||
− | Команды от стороннего чата к ПланФиксу | + | ==Команды от стороннего чата к ПланФиксу== |
---- | ---- | ||
− | == newMessage | + | |
+ | ==newMessage== | ||
+ | |||
Команда для передачи нового сообщения из стороннего чата в ПланФикс. | Команда для передачи нового сообщения из стороннего чата в ПланФикс. | ||
Строка 46: | Строка 48: | ||
|- | |- | ||
| isEcho || исходящее сообщение || boolean || необязательный | | isEcho || исходящее сообщение || boolean || необязательный | ||
+ | |- | ||
+ | | userEmail || email сотрудника-автора исходящего сообщения || string || необязательный, при отсутствии автором будет сотрудник указанный в настройках интеграции, при отсутствии кого-либо и там - сотрудник подключавший интеграцию. | ||
+ | |- | ||
+ | |data_имя_поля_задачи|| дополнительные данные, которые надо внести в создаваемую в планфиксе задачу для этого чата. | ||
+ | |||
+ | |||
+ | Имя поля в задаче должно точно совпадать с текстом после data_, таких параметров может быть столько, сколько полей заполняется, по одному на каждое поле. | ||
+ | |||
+ | К примеру, если вы передаете в запросе параметры data_utm_source и data_utm_medium, то для сохранения этих данных в ПланФиксе, необходимо чтобы в шаблоне задачи были добавлены поля типа Строка с названиями utm_source и utm_medium | ||
+ | || string || необязательный | ||
|- | |- | ||
|} | |} | ||
Строка 86: | Строка 98: | ||
+ | ---- | ||
+ | |||
+ | |||
+ | ==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 == | + | |
+ | ==newMessage== | ||
+ | |||
Команда для передачи нового сообщения из ПланФикса в сторонний чат. | Команда для передачи нового сообщения из ПланФикса в сторонний чат. | ||
---- | ---- | ||
Строка 107: | Строка 241: | ||
|- | |- | ||
|contactPhone|| телефон контакта || string || необязательный | |contactPhone|| телефон контакта || string || необязательный | ||
+ | |- | ||
+ | |contactData|| дополнительные данные контакта || string || необязательный | ||
|- | |- | ||
|channel|| дополнительный идентификатор канала на стороне сторонней системы || string || не обязателен, может использоваться при необходимости. | |channel|| дополнительный идентификатор канала на стороне сторонней системы || string || не обязателен, может использоваться при необходимости. | ||
Строка 113: | Строка 249: | ||
|- | |- | ||
|message|| содержимое сообщения || string || | |message|| содержимое сообщения || string || | ||
+ | |- | ||
+ | |messageId|| идентификатор сообщения || string || | ||
|- | |- | ||
|userName|| имя ответившего сотрудника || string || | |userName|| имя ответившего сотрудника || string || | ||
Строка 171: | Строка 309: | ||
== Перейти == | == Перейти == | ||
+ | *[[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_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 |
любое другое значение обрабатывается как 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) |