|
|
| Строка 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)
| |
| |-
| |
| |}
| |
|
| |
|
|
| |
|
Общие сведения об API
API позволяет подключить к ПланФикс любой ваш собственный чат или подобную ему систему (ленту общения с пользователем)
Интеграция ПланФикса и стороннего чата позволяет реализовать следующее:
- получение в ПланФикс сообщений от сторонней системы, а также данных о контакте из неё в реальном времени;
- получение в стороннюю систему ответов из ПланФикса в реальном времени.
Интеграция должна быть двухсторонней. Поэтому часть запросов ПланФикс посылает в сторону сторонней системы на указанные точки входа, а часть запросов, наоборот, сторонняя система посылает в сторону ПланФикса на единую точку входа.
Взаимодействие производится по протоколу HTTPS. Авторизация осуществляется по адресу ПланФикса или сторонней системы соответственно и авторизационному ключу, полученному в процессе настройки интеграции.
Принцип авторизации и взаимодействия
HTTPS:
- Запросы к ПланФиксу принимаются только по протоколу HTTPS. Это обеспечивает достаточный уровень безопасности для общения систем через Интернет.
- В целях безопасности ваших данных, пожалуйста, реализуйте прием запросов на стороне вашей системы также с использованием HTTPS.
Ключ (token):
- Дополнительно для авторизации каждого запроса к ПланФиксу используется специальный ключ (token). Получить его можно в настройках интеграции.
- Пожалуйста, реализуйте прием запросов на стороне вашей системы также с использованием ключа (token). Сгенерируйте ключ и вставьте его в соответствующее поле в разделе настройки интеграции.
- Ключи создаются один раз при настройке интеграции. При необходимости, вы можете сменить ключ на своей стороне и обновить его интерфейсе ПланФикса.
Запросы от сторонней системы к ПланФиксу:
- Запросы необходимо отправлять на указанный в настройках интеграции адрес для приема уведомлений.
- В теле запроса в специальном поле «token» необходимо всегда передавать специальный ключ.
- Запросы передаются в application/x-www-form-urlencoded формате
Запросы от ПланФикса к сторонней системе:
- ПланФикс будет отправлять все запросы на указанный в настройках интеграции адрес.
- В теле сообщений ПланФикс будет передавать указанный вами в веб-кабинете ключ (token).
- Запросы передаются в application/x-www-form-urlencoded формате
Ответы
- Все ответы на запросы сторонней системы ПланФикс присылает в формате JSON в теле ответа.
- Все ответы на запросы ПланФикса сторонняя система должна присылать в формате JSON в теле ответа.
Подключение в интерфейсе ПланФикса
Для подключения и настройки интеграции перейдите в раздел Интеграции с другими сервисами - Чаты
в открывшемся разделе нажмите Добавить чат. Откроется окно настроек интеграции.
Из него необходимо будет взять адрес для отправки запросов в ПланФикс (он свой для каждого аккаунта) и токен, и указать в нём данные интегрируемого чата. providerId - это идентификатор сторонней системы, он может быть любым, и нужен для различия запросов в случае подключения по этому API нескольких разных чатов с пересекающимися идентификаторами.
Перейти
