API для чатов

Общие сведения об 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 нескольких разных чатов с пересекающимися идентификаторами.

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

От стороннего чата к ПланФиксу:

• newMessage (POST)

От ПланФикса к стороннему чату:

• newMessage (POST)

Команды API и примеры доступных сценариев

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

newMessage

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

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

Имя	Описание	Тип/формат данных	Примечание
cmd	тип операции, в данном случае newMessage	string
providerId	идентификатор сторонней системы	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	необязательный

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

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)

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

newMessage

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

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

Имя	Описание	Тип/формат данных	Примечание
cmd	тип операции, в данном случае newMessage	string
providerId	идентификатор сторонней системы	string
chatId	уникальный id чата	string
contactPhone	телефон контакта	string	необязательный
token	ключ (token) стороннего чата, указанный в настройках интеграции	string
message	содержимое сообщения	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)

Перейти

• Интеграции
• Разработчикам: API