Интеграция с amoCRM
Обзор возможностей
Автопилот умеет:
- Создавать контакт и обновлять в нем информацию
(имя, теги, контактные данные). - Аналогично Создавать / Обновлять сделку.
- Управлять доп. полями контакта или сделки
(в т.ч. значениями списков и мультисписков) - Находить существующие контакты или сделки по VK ID в дополнительных полях и статусах сделок (для обновления).
- Менять статусы сделки.
- Добавлять «примечания» в существующие контакт или сделку.
- Реагировать на события (вебхуки) из amo, которые могут передавать ID подписчика ВКонтакте по дополнительному полю.
Например: Создание / обновление контакта, создание / обновление сделки, изменение статуса сделки.
Что это дает в итоге?
- Возможность супер-тесно интегрировать и синхронизировать данные
ВК, Senler или GetCourse с amoCRM. - Просматривать полный цикл взаимодействия с подписчиком в рамках воронки на одной странице (внутри сделки).
- Хранить там активности пользователя (комментарии / сообщения) в виде примечаний.
- Вести человека по воронке амо автоматически, реагируя на его активность в сообществе ВК.
И многое другое.
Общие принципы (читать обязательно!)
Связь контакта или сделки в amoCRM осуществляется благодаря дополнительному текстовому полю в амо, содержащему ID подписчика ВКонтакте и небольшой суффикс. В случае со сделкой также в поиске участвует статус сделки.
Если контакт / сделка не найдены, будут созданы новые.
Исключение — действие «Добавить примечание».
Если нужно заполнить несколько полей в сделке, можете просто добавить 2 почти одинаковых действия подряд. Но имейте в виду: если в первом поменялся статус то в опциях второго нужно уже выбирать новый!
Для реакции на события в amoCRM (например, обновление / создание контакта / сделки) название, поле содержащее ID подписчика ВКонтакте должно обязательно иметь название: vk_uid.
Более детально описано в этом разделе.
Там же указаны и причины подобных особенностей работы.
Основная настройка интеграции (теперь подключение идет через OAUTH)
Важно! Токен AmoCRM не генерируется при достижении лимита в 10000 сделок на пользователя аккаунта
Лимиты распространяются на всех пользователей в аккаунте. Например, если в аккаунте тариф расширенный с 10 пользователями, то в сумме в аккаунте может быть 10000 сделок всего. А как они распределяются по менеджерам не имеет значения. То есть сделки могут распределяться как равномерно по всем менеджерам, так и за всеми сделками, может отвечать 1 пользователь.
Если у вас перестал генерироваться токен, узнавайте в техподдержке AmoCRM не заблокирован ли ваш аккаунт по API.
Дополнительная информация от AmoCRM:
В amoCRM есть техническое ограничение на число запросов к API — не более 7 в секунду для одной интеграции и не более 50 запросов в секунду суммарно для всех интеграций на аккаунте. Данное ограничение действует по умолчанию на все тарифы.
Если количество запросов на аккаунте превышает данные лимиты, то, чтобы избежать блокировки, существует возможность увеличить общий лимит через покупку дополнительного пакета API-запросов.
На данный момент существует 4 основных пакета API:
- до 100 запросов / сек. на весь аккаунт, до 15 запросов / сек. для каждой интеграции;
- до 150 запросов / сек. на весь аккаунт, до 30 запросов / сек. для каждой интеграции;
- до 200 запросов / сек. на весь аккаунт, до 50 запросов / сек. для каждой интеграции;
- более 200 запросов / сек. на весь аккаунт — индивидуально.
Ограничения
Взяты отсюда
В случае подозрительной активности через API или сбоя интеграции, доступ к API аккаунта может быть заблокирован. Например при выборке одних и тех же раз за короткий промежуток времени, бесконтрольный перебор всех данных.
В случае превышения количества запросов – будет возвращаться HTTP код 429, при многократном нарушении ограничений, аккаунт блокируется и на любой запрос в API будет возвращаться HTTP код 403.
В случае окончания подписки, доступ к данным через API будет закрыт через 30 дней после окончания подписки. Запросы на добавление/изменение данных блокируются сразу после окончания действия подписки. В ответ на запросы сервер будет возвращать HTTP код 402.
Важно:
- Приобретение пакетов доступно только для аккаунтов с актуальными тарифными планами.
- Пакеты приобретаются строго до конца подписки аккаунта.
- Бонусных месяцев для пакетов нет — оплачивается весь период.
- Перерасчёты в аккаунтах с примененным пакетом невозможны.
- Пакеты могут покупаться отдельно от лицензий.
Для работы действий Автопилота нужно:
Для подключения нескольких сообществ, повторите настройку для каждого.
Алгоритм подключения:
- Открыть настройки сообщества в Автопилоте и найти там раздел amoCRM.
- Скопировать «Ссылку для перенаправления».
- Зайти в amoCRM → Настройки → Интеграции и нажать там кнопку «Создать интеграцию».
- В открывшемся окне:
- Вставьте ссылку для перенаправления в первое поле.
- - Загрузите картинку (можно эту → skyjoom.com/amo-avatar)
- Поставьте все галочки в поле «Предоставить доступ»
- Напишите название «Автопилот» и произвольный текст описания.
- Дальше нажмите синюю кнопку «Сохранить»
- И переключитесь на появившуюся вкладку Ключи и доступы,
- Откуда скопируйте ID интеграции и Секретный ключ в настройки Автопилота - - Обязательно сгенерируйте долгосрочный токен нажатием «Сгенерировать токен» сроком допустим на несколько месяцев или несколько лет, чтобы интеграция не ломалась.
В противном случае интеграция сломается через указанное время. - - Дальше скопируйте «Долгосрочный токен» в соответствующее поле нашего сервиса.
- - Сохраните настройки в Автопилоте
- Еще раз прокрутите до раздела amoCRM на странице настроек в АП.
- Нажмите там на появившуюся ссылку «Сгенерировать токен».
- Настройте тестовую команду и проверьте работу интеграции!
P.S. Если у вас есть интеграция, достаточно вставить токен.
Важно! Пояснение по токену от колллег от AmoCRM
Доступные действия
После этого должны заработать действия:
Но в первую очередь стоит проверить работу на «кнопочке»
«Обновить данные полей». Для этого (после настроек выше, конечно) добавьте в любую команду одно из первых 2-х действий. И нажмите в них на ссылку с таким названием. Как результат должны появиться дополнительные поля контактов и сделок в выпадающих списках, а также статусы воронок.
Режимы настройки
Также в каждом действии есть 2 режима, которые переключаются небольшой иконкой справа:
1) Удобный — Параметры редактируются при помощи выпадающих списков.
2) Универсальный — ID полей и статусов воронок прописываются вручную в виде чисел, или переменных Автопилота.
Для статусов сделок в «удобном» режиме доступен выпадающий список с несколькими возможными вариантами. В «универсальном» ID статусов прописываются числами через запятую.
Общие принципы. ВАЖНО!
Теперь, когда вы немного познакомились с действиями, поговорим о главном.
Связь контакта или сделки в amoCRM осуществляется благодаря дополнительному текстовому полю в амо, содержащему ID подписчика ВКонтакте и небольшой суффикс -avtp для точности поиска. Это важно потому, что поиск выполняется сразу по ВСЕМ доп. полям! И можно случайно найти не того подписчика, например по чужому номеру телефона.
В случае со сделкой в поиске также участвует статус сделки. ID статусов разные для разных воронок. Поэтому в Автопилоте они выводятся одним списком. Если в параметре передать 0 (то же самое, что выбрать только «Не искать сделку, создать новую» в выпадающем списке «удобного режима»), то Автопилот не будет искать сделок, а просто создаст новую.
Если контакт / сделка не найдены, также будут созданы новые. Исключение - действие «Добавить примечание». Оно ищет только по существующим объектам. Если объект может не существовать, добавьте в команду действие «Обновить...» перед действием «Добавить примечание».
Если нужно заполнить несколько полей одной командой, можете просто добавить 2 почти одинаковых действия подряд. Но имейте в виду: если в первом поменялся статус, то в опциях второго (параметр статус для поиска) нужно уже выбирать новый.
Чтобы передавать из Амо в Автопилот уведомления о новых событиях, используются обычные «вебхуки», но с необычными параметрами (в разделах дальше поговорим более подробно об этом).
Более детально про API можно прочитать в документации amoCRM. Например, о сделках тут: amocrm.ru/developers/content/api/leads. Остальные методы находятся в левом меню сайта ↑
Реакции на события (вебхуки)
Для реакции на события в amoCRM (например, обновление / создание контакта / сделки) название, поле содержащее ID подписчика ВКонтакте должно обязательно иметь название: vk_uid. Это касается как контакта, так и сделки.
Именно по названию Автопилот попытается найти поле обрабатывая данные из запроса вебхука.
Общий принцип получения структуры запроса от amoCRM следующий. Нужно создать команду с событием Упомянут в GET запросе (Входящий запрос), но вместо &sid= прописать в его опциях один из наборов параметров из списка ниже. Как можно заметить, набор разный для разных событий.
&integration=amocrm&obj=contacts&event=add— создание контакта (0 — для случаев, когда заполнено только поле VK ID, или если оно самое первое, что крайне маловероятно);&integration=amocrm&obj=contacts&event=update— обновление контакта;&integration=amocrm&obj=leads&event=add— создание сделки;&integration=amocrm&obj=leads&event=update— обновление сделки;&integration=amocrm&obj=leads&event=status— изменение статуса сделки;
Эти параметры берутся из названий первых 2-х уровней JSON-объекта вебхука (запоминать и понимать это предложение не обязательно).
Подробнее про названия других событий можете почитать в статье: amocrm.ru/developers/content/api/webhooks. Или если что, пишите.
Настройка вебхука на стороне amoCRM
Дальше адрес вебхука, скопированный из события, вставляете в Аmo по пути: AmoМаркет → Кнопочка «Web Hooks» → Кнопочка «Добавить хук» и попутно отмечаете галочками ВСЕ типы событий, на которые собираетесь реагировать. Важно! Автопилот дружит только с теми, которые могут передать ID подписчика ВКонтакте среди дополнительных полей.
Вебхук будет передавать дополнительные поля. Поля сделки при событиях сделок и поля пользователя при событиях контактов соответственно.
Чтобы получить значение конкретного поля, достаточно прописать в действиях переменную %api_field_000%, где 000 заменить на уникальный ID дополнительного поля. Где его взять пишу ;-)
Массив дополнительных полей передается в формате JSON.
В виде ID: Значение. Пример:
{
"120863"26187274-avtp", (
поле vk_uid) "108423":"Знач. текстового поля", "121235":"Вариант обычного списка", "121471":"Вариант мультисписка 1, Вариант мультисписка 2", "122201":"1" (чекбокс: 0 или 1)}
Увидеть его можно создав тестовый запуск (рекомендую события: «Контакт изменен» или «Сделка изменена») и в сообщении себе прописав переменную: %api_fields%.
ВАЖНО! Большинство типов полей не попадут в массив, если они не заполнены. Поэтому в примере заполните все поля.
Дальше сохраните себе их номера и используйте для формирования переменных. Допустим, если нам нужно значение чекбокса из примера выше, переменная будет выглядеть так: %api_field_122201%.
Другие полезные данные можно получить из полного объекта запроса при помощи переменной get_var. Ниже показано несколько примеров:
Обновление сделки:{get_var}leads.update.0.id{/get_var} — ID обновленной сделки;{get_var}leads.update.0.status_id{/get_var} — ID статуса сделки.{get_var}leads.update.0.pipeline_id{/get_var} — ID воронки.
Обновление статуса сделки:{get_var}leads.status.0.id{/get_var} — ID обновленной сделки;{get_var}leads.status.0.status_id{/get_var} — ID нового статуса сделки.{get_var}leads.status.0.old_status_id{/get_var} — ID старого статуса сделки.{get_var}leads.status.0.pipeline_id{/get_var} — ID воронки.
Обновление контакта:{get_var}contacts.update.0.id{/get_var} — ID контакта;{get_var}contacts.update.0.name{/get_var} — ФИО контакта;{get_var}contacts.update.0.linked_leads_id{/get_var} - массив ID сделок контакта (правда, не в самом удобном для обработки виде. Просто как информация).