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

Материал из Planfix
Перейти к: навигация, поиск
Нет описания правки
Нет описания правки
 
(не показано 10 промежуточных версий 4 участников)
Строка 6: Строка 6:
}}
}}
== Общие сведения об API ==
== Общие сведения об API ==
API  позволяет подключить к ПланФикс любой ваш собственный чат или подобную ему систему (ленту общения с пользователем)
API  позволяет подключить к ПланФикс любой ваш собственный чат или подобную ему систему (ленту общения с пользователем).
 


Интеграция ПланФикса и стороннего чата позволяет реализовать следующее:
Интеграция ПланФикса и стороннего чата позволяет реализовать следующее:
* получение в ПланФикс сообщений от сторонней системы, а также данных о контакте из неё в реальном времени;
* получение в ПланФикс сообщений от сторонней системы, а также данных о контакте из неё в реальном времени;
* получение в стороннюю систему ответов из ПланФикса в реальном времени.
* получение в стороннюю систему ответов из ПланФикса в реальном времени.
Строка 18: Строка 16:


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




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




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




'''Запросы от сторонней системы к ПланФиксу:'''
=== Запросы от сторонней системы к ПланФиксу ===
* Запросы  необходимо  отправлять на указанный в настройках интеграции адрес для приема уведомлений.  
* Запросы  необходимо  отправлять на указанный в настройках интеграции адрес для приема уведомлений.  
* В  теле  запроса  в  специальном  поле  «token»  необходимо всегда  передавать специальный ключ.  
* В  теле  запроса  в  специальном  поле  «token»  необходимо всегда  передавать специальный ключ.  
Строка 39: Строка 36:




'''Запросы от ПланФикса к сторонней системе:'''
=== Запросы от ПланФикса к сторонней системе ===
* ПланФикс будет отправлять все запросы на указанный в настройках интеграции адрес.  
* ПланФикс будет отправлять все запросы на указанный в настройках интеграции адрес.  
* В  теле  сообщений ПланФикс будет  передавать  указанный  вами  в  веб-кабинете ключ (token).  
* В  теле  сообщений ПланФикс будет  передавать  указанный  вами  в  веб-кабинете ключ (token).  
Строка 45: Строка 42:




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


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


https://p.pfx.so/pf/5p/12i2H2.jpg
https://p.pfx.so/pf/0L/qov58q.png


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


https://p.pfx.so/pf/H4/ecIyyL.jpg
В открывшемся разделе нажмите '''Добавить чат'''. Откроется окно настроек интеграции:


Из него необходимо будет взять адрес для отправки запросов в ПланФикс (он свой для каждого аккаунта) и токен, и указать в нём данные интегрируемого чата. providerId - это идентификатор сторонней системы, он может быть любым, и нужен для различия запросов в случае подключения по этому API нескольких разных чатов с пересекающимися идентификаторами.
https://p.pfx.so/pf/GC/1cJ5aU.png


== Список команд API ==


Из него необходимо будет взять адрес для отправки запросов в ПланФикс (он свой для каждого аккаунта) и токен, и указать в нём данные интегрируемого чата. providerId - это идентификатор сторонней системы, он может быть любым, и нужен для различия запросов в случае подключения по этому 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)
|-
|}




== Перейти ==
== Перейти ==
*[[Список команд API для чатов]]
*[[Разработчикам: API]]
*[[Интеграции]]
*[[Интеграции]]
*[[Разработчикам: API]]

Текущая версия от 13:55, 21 ноября 2022

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

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

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

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


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

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


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

HTTPS

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


Ключ (token)

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


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

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


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

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


Ответы

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


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

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

qov58q.png


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

1cJ5aU.png


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


Дополнительно

  • В переписке с клиентами для ответа на типовые вопросы вы можете использовать механизм быстрых ответов.


Перейти

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