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

Материал из ПланФикс
Перейти к: навигация, поиск
Строка 61: Строка 61:
  
 
*[[Список команд API для чатов]]
 
*[[Список команд API для чатов]]
−
 
−
== Список команд API ==
 
−
 
−
 
−
'''От стороннего чата к ПланФиксу:'''
 
−
* newMessage (POST)
 
−
 
−
 
−
'''От ПланФикса к стороннему чату:'''
 
−
* newMessage (POST)
 
−
 
−
 
−
== Команды API и примеры доступных сценариев ==
 
−
=== Команды от стороннего чата к ПланФиксу ===
 
−
==== newMessage ====
 
−
Команда для передачи нового сообщения из стороннего чата в ПланФикс.
 
−
 
−
'''Параметры запроса:'''
 
−
{| class="wikitable" style="margin-top: 1em; width:100% "
 
−
!width="150"|Имя !!width="50%"| Описание !!width="150"| Тип/формат данных !! Примечание
 
−
|-
 
−
|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 || необязательный
 
−
|-
 
−
|}
 
−
 
−
 
−
'''Пример запроса:'''
 
−
<source lang="bash">
 
−
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
 
−
</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 || необязательный
 
−
|-
 
−
|channel|| дополнительный идентификатор канала на стороне сторонней системы || string || не обязателен, может использоваться при необходимости.
 
−
|-
 
−
|token || ключ (token) стороннего чата, указанный в настройках интеграции || string ||
 
−
|-
 
−
|message|| содержимое сообщения || 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)
 
−
|-
 
−
|}
 
  
  

Версия 18:38, 22 июня 2019

Общие сведения об API

API позволяет подключить к ПланФикс любой ваш собственный чат или подобную ему систему (ленту общения с пользователем)


Интеграция ПланФикса и стороннего чата позволяет реализовать следующее:

  • получение в ПланФикс сообщений от сторонней системы, а также данных о контакте из неё в реальном времени;
  • получение в стороннюю систему ответов из ПланФикса в реальном времени.


Интеграция должна быть двухсторонней. Поэтому часть запросов ПланФикс посылает в сторону сторонней системы на указанные точки входа, а часть запросов, наоборот, сторонняя система посылает в сторону ПланФикса на единую точку входа.

Взаимодействие производится по протоколу HTTPS. Авторизация осуществляется по адресу ПланФикса или сторонней системы соответственно и авторизационному ключу, полученному в процессе настройки интеграции.


Принцип авторизации и взаимодействия

HTTPS:

  • Запросы к ПланФиксу принимаются только по протоколу HTTPS. Это обеспечивает достаточный уровень безопасности для общения систем через Интернет.
  • В целях безопасности ваших данных, пожалуйста, реализуйте прием запросов на стороне вашей системы также с использованием HTTPS.


Ключ (token):

  • Дополнительно для авторизации каждого запроса к ПланФиксу используется специальный ключ (token). Получить его можно в настройках интеграции.
  • Пожалуйста, реализуйте прием запросов на стороне вашей системы также с использованием ключа (token). Сгенерируйте ключ и вставьте его в соответствующее поле в разделе настройки интеграции.
  • Ключи создаются один раз при настройке интеграции. При необходимости, вы можете сменить ключ на своей стороне и обновить его интерфейсе ПланФикса.


Запросы от сторонней системы к ПланФиксу:

  • Запросы необходимо отправлять на указанный в настройках интеграции адрес для приема уведомлений.
  • В теле запроса в специальном поле «token» необходимо всегда передавать специальный ключ.
  • Запросы передаются в application/x-www-form-urlencoded формате


Запросы от ПланФикса к сторонней системе:

  • ПланФикс будет отправлять все запросы на указанный в настройках интеграции адрес.
  • В теле сообщений ПланФикс будет передавать указанный вами в веб-кабинете ключ (token).
  • Запросы передаются в application/x-www-form-urlencoded формате


Ответы

  • Все ответы на запросы сторонней системы ПланФикс присылает в формате JSON в теле ответа.
  • Все ответы на запросы ПланФикса сторонняя система должна присылать в формате JSON в теле ответа.

Подключение в интерфейсе ПланФикса

Для подключения и настройки интеграции перейдите в раздел Интеграции с другими сервисами - Чаты

12i2H2.jpg

в открывшемся разделе нажмите Добавить чат. Откроется окно настроек интеграции.

ecIyyL.jpg

Из него необходимо будет взять адрес для отправки запросов в ПланФикс (он свой для каждого аккаунта) и токен, и указать в нём данные интегрируемого чата. providerId - это идентификатор сторонней системы, он может быть любым, и нужен для различия запросов в случае подключения по этому API нескольких разных чатов с пересекающимися идентификаторами.


Перейти

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