ManyChat Help Portal
Submit a ticket

СОДЕРЖАНИЕ


Введение

Приложения ManyChat — это способ подключения сторонних инструментов к ManyChat.

Для работы с ними необходимо понимать:

  • аутентификацию API
  • вызовы API
  • JSON

Если у вас есть опыт разработки, вы сможете воспользоваться этой статьей и приведенными примерами как всеобъемлющим руководством по созданию вашего первого приложения ManyChat.

Для клиентов без опыта разработки мы на данный момент не можем предложить помощь в обучении, однако вам могут оказаться полезными следующие ресурсы:


Рассмотрим принцип действия приложений ManyChat. Приложение состоит из названия, описания и JSON.

Название и описание приложения говорят сами за себя — см. рисунок ниже. На нем показано, как название приложения импортируется в список действий после установки:

JSON — это ключевое понятие для приложений ManyChat, поскольку именно он содержит спецификацию интеграции. Затем ManyChat исследует эту спецификацию, чтобы понять возможности вашего приложения, и преобразует JSON в нативные элементы интерфейса для конечных пользователей.

Типичное приложение состоит из следующих блоков:

  • auth — если платформа, к которой вы подключаете ManyChat, требует авторизации, настройте этот блок и укажите "auth": null
  • actions — каждое приложение должно содержать хотя бы одно действие
  • sources — это необязательный блок. Если необходимо, здесь можно настроить источник для переменных, используемых в ваших действиях.

Вот демонстрация, как ManyChat определяет заголовок действия и его описание:

Углубимся в тему и рассмотрим, как создается приложение.

Ниже приведен пошаговый процесс создания приложения (с примерами с открытым исходным кодом и юзкейсами). С технической спецификацией можно ознакомиться здесь.

Шаг 1. Создание приложения

Создадим простой пример приложения, генерирующего случайное число в заданном диапазоне.

Обратите внимание на следующие предварительные условия:

  • В качестве API будет использоваться https://csrng.net/documentation/csrng-lite/
  • Ожидается, что конечный пользователь задаст диапазон с помощью полей данных бота

Чтобы создать приложение, выполните следующие шаги:

  • Перейдите в раздел Приложения и нажмите на кнопку «Новое приложение»
  • Заполните следующие поля:
    • Название приложения: Random Number App

    • Описание приложения: Best Random Number Generation App

    • JSON приложения (см. проект в Glitch; если вы хотите поработать с этим приложением, используйте файл app_for_copy.json, поскольку в нем убраны комментарии. Поле для JSON приложения на данный момент поддерживает JSON только без комментариев):

      remix this

    • Нажмите на кнопку «Создать приложение»

Вот некоторые примеры импорта этих данных в ManyChat:

Формы в JSON → формы в UI


Данные, собранные через форму, используются в запросе: 

Сопоставление:

Шаг 2. Установка приложения

  • Нажмите на кнопку «Установить» в меню кнопки с тремя точками
  • Выберите аккаунт, к которому вы хотите это применить, и завершите установку.

Шаг 3. Тестирование приложения

  • Перейдите в конструктор сценариев и выберите свое приложение из списка «Действия»
  • Настройте действие


  • Создайте новый сценарий, как показано в примере:

  • Протестируйте сценарий:

Шаг 4. Публикация приложения

Когда приложение будет готово, вы можете отправить его на проверку и публикацию.

По нажатию кнопки «Опубликовать» запускается процесс проверки, которая проводится командой ManyChat и является необходимым условием публикации приложения. Мы проверим последнюю версию вашего приложения, проанализируем JSON приложения и примем решение одобрить или отклонить приложение.

  • Если ваше приложение будет одобрено для публикации:
    • Мы удалим предупреждение со страницы приложения
    • Присвоим приложению номер версии
    • Защитим эту версию от каких-либо изменений (случайных или преднамеренных), вносимых в версию «dev»
  • Если ваше приложение будет отклонено:
    • Мы сообщим, в чём проблема, и начнем процесс проверки заново, как только вы внесете необходимые изменения и нажмете кнопку «Опубликовать».

Когда ваше приложение станет публичным, вы можете выставить его в магазине приложений ManyChat. Это необязательно; за более подробной информацией обращайтесь по адресу devprogram@manychat.com


Что дальше

На первых 4 шагах мы разобрали основные понятия, связанные с созданием несложных приложений. Эти понятия применимы к любым приложениям, будь то генератор случайных чисел или приложения для синхронизации данных с вашей CRM. Для углубленного изучения мы рекомендуем тематические статьи, приведенные ниже. В них мы расскажем, как создать автоматизацию внутри приложения, заменить жестко запрограммированные значения статическими и динамическими источниками данных, добавить в приложение руководство для пользователей. Все эти возможности расширяют функциональность приложения и делают его более удобным для пользователя, повышая его конкурентоспособность в экосистеме ManyChat.


Как использовать блок auth

Для API случайных чисел ключ API не нужен, однако он нужен для других API.

Для создания подключения к этим API можно использовать блок auth.

Предварительные условия (в качестве примера мы будем использовать Taste Dive):

Попробуем создать приложение, которое требует ключ API, а затем использует его как параметр запроса:


Полный код примера можно посмотреть здесь: remix this

Настройка глобальных переменных внутри блока auth

С помощью блока auth также можно задавать глобальные переменные, такие как доменные имена, базовые URL и т. д.

Вы можете использовать любое количество объектов params. Все данные, вводимые пользователями, будут сохраняться и их можно будет использовать в действиях.

Рассмотрим пример для API ActiveCampaign:

"params": 
  [
    {
      "name": "base",
      "title": "Введите базовый URL Active Campaign"
    },
    {
      "name": "token",
      "title": "Введите токен Active Campaign"
    }
  ]

Тогда URL запроса действия будет выглядеть как https://[[base]]/api/3/

Это экономит время пользователей: исключается лишняя форма действия; данные для многократного использования достаточно указать один раз.

Как использовать payload

Некоторые конечные точки API требуют полезную нагрузку.

Чтобы в этих случаях можно было использовать JSON, можно добавить payload {}, как показано ниже. Значения для полезной нагрузки можно передавать из forms [[]] .

В этом случае мы создаем запись в CRM Pipedrive. Конечная точка API требует передачи полезной нагрузки с именем и адресом электронной почты. Когда конечный пользователь настраивает действия, он может выбрать пользовательские поля для имени и адреса электронной почты. Затем ManyChat вызывает действие и добавляет в полезную нагрузку значения пользовательских полей для определенного контакта.

Если хотите, можете использовать этот проект в качестве примера, вот ссылка на Glitch:   remix this

В некоторых случаях в полезную нагрузку не требуется передавать динамические значения. Так что элемент payload может выглядеть следующим образом:

Каждый раз, когда обрабатывается соответствующее действие, на указанный URL будет передаваться одна и та же полезная нагрузка.

Как использовать источники

enum:static

В приложении random-number-app-v1 мы использовали поля «Min» и «Max», заполняемые пользователем через пользовательские поля.

Если требуется передавать наши собственные значения, можно использовать концепцию источников.

Откройте пример в Glitch и обратите внимание на комментарии к блокам forms и sources: remix this

Вот как ManyChat оперирует этими данными:

enum:rpc

Для приложения similar-to-music-app мы использовали пользовательское поле для параметра q.

С помощью enum:rpc мы можем предоставить список музыкантов и ансамблей из этого API. Чтобы понять, как добавить в приложение источник enum:rpc, изучите этот проект в Glitch:   remix this

Вот пример реализованного кода:

Как использовать инструкции для пользователя

В некоторых случаях настройка действия приложения может требовать пошаговой инструкции. Если описания действия недостаточно для изложения всех необходимых тонкостей, вы можете добавить в блок actions поле guidance.

Это пример инструкции из трех шагов; для переноса строки (это необязательно) можно использовать \n

Пользователи увидят инструкцию в следующем виде:

Как делать поля необязательными

Иногда действие может вовсе обойтись без некоторых полей или эти поля можно заполнить значениями по умолчанию. Для упрощения настройки мы позволяем конфигурировать поля заранее с помощью нового параметра default.

Вы как разработчик приложения можете задать значение по умолчанию для определенного поля. Это сделает поле необязательным. Если пользователь не укажет собственное значение, при срабатывании этого действия всегда будет использоваться значение по умолчанию.

Форма действия выглядит следующим образом:

Пользователи приложения могут пропустить это поле:

Как использовать триггеры

Триггеры позволяют запускать сценарии, когда во внешнем приложении происходит определенное событие.

Это может быть, например:

  • Создание заказа контактом или оплата чего-либо вне ManyChat
  • Присвоение контакту тега в вашей CRM
  • Наступление события по расписанию

Если при наступлении этих событий требуется отправлять сценарии ManyChat, для этого можно использовать триггеры.

С точки зрения разработчика для использования триггеров необходимо выполнить несколько шагов:

  • Задать триггеры в JSON приложения (подробнее об этом — здесь)
"triggers": [
    {
      "name": "trigger_tag_added",
      "title": "Добавлен тег",
      "description": "Добавлен тег \"Сделка заключена\" в X CRM"
    }
  ]
  • Отправлять хук на следующую конечную точку https://manychat.com/apps/wh, добавляя заголовок авторизации с ключом приложения всякий раз, когда срабатывает событие. Полезная нагрузка должна иметь следующий формат:
curl -H "Authorization: Bearer <token>" \
-H "Content-type: application/json" \
-X POST \
-d '{"version": 1, "subscriber_id": <sub_id>, "trigger_name": <trigger>}' \
https://manychat.com/apps/wh

Как получить ключ приложения

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

Рекомендуем ясно и недвусмысленно сообщать клиентам, каким именно образом вы хотите получать ключ приложения (хотя обычный способ — это специальная страница на вашей стороне для настройки внешних интеграций)

Триггеры с контекстом

Триггер можно обогатить внешним контекстом. Рассмотрим, в чём разница:

Простой триггер

Триггер с контекстом

Заказ создан

Заказ создан, сумма заказа 107 USD

Контакт получил тег «лид»

Контакт получил тег «лид», вероятность сделки 90%


Вот пример JSON для создания триггера с внешним контекстом.

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

"triggers": [
  {
    "name": "trigger_tag_added",
    "title": "Добавлен тег",
    "context": [
      {
        "name": "deal_probability",
        "type": "number",
        "title": "Вероятность сделки"
      }
    ],
    "description": "Тег Deal добавлен в CRM"
  }
]

Вот пример сценария с триггером и контекстом. Этот контекст можно использовать в качестве условия, как часть узла контента и для персонализации автоматизаций.

curl -H "Authorization: Bearer <token>" \
-H "Accept: application/json" \
-X POST \
-d '{"version": 1, "subscriber_id": <sub_id>, "trigger_name": <trigger>, "context": { deal_probability: 90}}' \
https://manychat.com/apps/wh


Как использовать системные поля

Для удобства доступа к системным полям их можно задавать с помощью фигурных скобок {{ }}. Все данные собираются автоматически.

Вот пример приложения, показывающий, как собирать данные в системные поля без создания форм.

remix this

Резюме

  1. Изучите эту документацию и проекты в Glitch, чтобы понимать, как создается JSON приложений для различных задач
  2. Чтобы создать собственное приложение на основе наших примеров, нажмите на кнопку «Remix to Edit»
  3. Вставьте JSON в приложения ManyChat
  4. Установите свое приложение, чтобы увеличить результативность своей интеграции
  5. Поделитесь приложением с клиентами, чтобы заслужить почет и уважение