Начало работы

Через API ваша CRM, сайт или скрипт пишет клиентам, ставит теги, назначает чаты и запускает workflow в Polygram.

Для ИИ-ассистента нажмите Копировать для LLM или дайте ему ссылку https://polygram.chat/docs/llms.txt.

Базовый адрес

https://api.polygram.chat/api

Пути в статьях даны от него. Например, POST /public/contacts/tag отправляйте на https://api.polygram.chat/api/public/contacts/tag.

Тело запроса передавайте в JSON с заголовком Content-Type: application/json. Без заголовка запрос получит ошибку проверки полей.

Ключ доступа

Ключ может создать сотрудник с правом на настройку интеграций. По умолчанию оно есть у ролей Владелец и Директор.

1. Откройте Настройки, раздел Ключи доступа.
2. Нажмите Ключ.
3. Введите название до 100 символов, например Сайт компании.
4. Нажмите Создать.
5. Скопируйте ключ. Второй раз Polygram его не покажет.

Ключ начинается с ak_, за ним идут 48 шестнадцатеричных символов. В списке ключей видны первые 10 символов, дата создания, автор и время последнего использования.

Если ключ потерялся, отзовите его кнопкой с корзиной и создайте новый. Отозванный ключ перестаёт работать со следующего запроса.

Ключ открывает все методы API для данных своей компании.

Как передать ключ

Подходит любой из двух заголовков:

X-Api-Key: ak_...

Authorization: Bearer ak_...

Если переданы оба, используется X-Api-Key.

Ответы

Успешный ответ приходит в JSON. Код зависит от метода:

Успешным считайте любой код 2xx.

Ошибки

В теле ошибки всегда есть statusCode и message:

{
  "statusCode": 404,
  "message": "Контакт с crm_accounts.id = 1042 не найден",
  "error": "Not Found"
}

Если поля не прошли проверку, приходит код 400 и список полей в errors. В field указан путь к полю через точку:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "field": "match.field", "message": "Только буквы, цифры, _ . -" },
    { "field": "text", "message": "Invalid input: expected string, received undefined" }
  ]
}

Текст в message написан для человека и может меняться. В программе ориентируйтесь на код ответа.

Ключ проверяется раньше полей, поэтому запрос без ключа получит 401, даже если тело неверное.

Лимиты

Число запросов не ограничено. Ограничения на размер полей указаны в описании каждого метода.

Выгрузка по чатам 30 секунд отдаёт на одинаковый запрос тот же ответ из памяти, поэтому опрашивайте её не чаще.

Повторы

Повторяйте запрос при ответе 500 и выше, при обрыве соединения и таймауте. При кодах 400–499 сначала исправьте запрос, иначе ответ будет тем же.

Можно ли повторять запрос, зависит от метода:

Поиск контакта по полю

Методы Написать клиенту, Поставить тег, Назначить чаты и Найти клиентов ищут клиента по полю карточки, которое заполняет ваша система.

"match": { "field": "crm_id", "value": "1042" }

Ключ поля указан рядом с его названием: откройте Настройки, раздел Поля контакта. Ключи пишутся строчными буквами. CRM_ID не найдёт поле crm_id.

Обычное поле

Если в field нет точки, это ключ поля карточки, например crm_id. Контакт подходит, если значение поля как строка совпадает с value. Поле, сохранённое числом 1042, найдётся и по "1042", и по 1042.

Колонка поля-списка

Если в field есть точка, это колонка поля типа Список, например crm_accounts.id. До первой точки стоит ключ поля, после неё ключ колонки. Контакт подходит, если колонка равна value хотя бы в одной записи списка. Так можно найти клиента, у которого в вашей системе несколько аккаунтов.

"match": { "field": "crm_accounts.id", "value": "1042" }

Сохраняйте колонку строкой. Если id записан числом 1042, методы Написать клиенту, Поставить тег и Назначить чаты такую запись не найдут. Найти клиентов найдёт.

Несколько контактов с одним значением

Если значение есть у нескольких контактов:

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

Если контакт не найден