ManyChat Help Portal
Submit a ticket

Цель этого руководства — научить вас работать с нашим API-инструментарием и рассказать о возможностях динамических блоков и внешних запросов. В идеале после изучения этого руководства вы достигнете нового уровня понимания этих инструментов и сможете решать все возможные проблемы.

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

Чтобы работать с ними, необходимо владеть основами программирования, клиент-серверных соединений, приемами работы с API и структурой API-запросов. Всё это мы рассмотрим ниже.

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

1. Что такое API (Application Programming Interface — программный интерфейс приложения)?

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

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

2. Что такое узлы?

Сценарии состоят из узлов. Существует, например, узел контента (узел «Отправить сообщение»). Он состоит из блоков. Этот узел используется для отправки сообщений контактам ManyChat. Узлы разбираются на элементы, переводятся в формат, понятный Facebook, и отправляются в Facebook через API.

3. Что такое динамический узел?

Динамический блок заставляет ManyChat прервать обработку сценария, заняться другими действиями (например, к запросу внешнего сервера и т. п.), а затем продолжить выполнение сценария.

4. Запрос состоит из следующих элементов:

1. Метод или тип запроса (GET/POST/и т. д.),
2. Ссылка
3. Возможно, заголовок (в т. ч. ключи API и авторизация)
4. Возможно, тело (с контентом внутри), если это запрос POST.

Формат данных запроса дополняют два компонента:
1. Используемая версия протокола (на данный момент это v2).
2. Контент: сообщения, действия, быстрые ответы и т. д. Это то же самое, что и узел контента ManyChat. ManyChat поддерживает только те действия, которые доступны в Manychat. Здесь приведены некоторые примеры.

Запасной вариант срабатывает в случае неправильного ответа сервера в блоке «API-запрос» — обычно это происходит, если сервер возвращает ошибку. Если админ задаст какой-либо контент для запасного варианта, этот контент доставляется тем контактам, для которых имел место отказ запроса.

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

5. Что такое JSONPath?

Это синтаксис для выбора полей и значений из документа JSON, полученного из внешней системы, и занесения их в пользовательские поля.
Сопоставление ответов позволяет сохранять эти значения в сопоставленные им пользовательские поля путем ввода выражения пути JSONPath к этим значениям.
JSONPath используют все наши интеграции (Hubspot, ConvertKit) и сам Facebook.

6. Как используется наш открытый API?

С его помощью можно в любой момент изменять состояние контактов и отправлять им сообщения — в сущности он позволяет выполнять определенные действия извне ManyChat. Открытый API предназначен для работы с внешними событиями, о которых ManyChat ничего не знает, и о которых необходимо уведомить контактов. 

Например, предположим, что у вас служба доставки. Информация об отслеживании отправления обновилась и вы знаете, чей это заказ. Вы можете вызвать этот метод для данного конкретного контакта и уведомить его сообщением.

7. В чем отличие метода POST от метода GET?

Метод POST изменяет данные контакта, например «Задать значение пользовательского поля», «Отправить сообщение», «Задать значение поля данных бота». Метод POST также используется для передачи на сервер параметров, необходимых для выполнения определенных действий.

Рассмотрим, например, вызов API «setCustomField»: чтобы задать определенное значение пользовательского поля для определенного контакта, необходимо передать на сервер идентификатор контакта, имя поля и значение, которое требуется присвоить полю.

Метод GET используется для получения данных контакта или страницы через запросы «Получить пользователя», «Получить поле данных бота» и т. п. В случае подобных запросов мы ожидаем получить ответ от внешнего сервера немедленно. У запросов GET нет тела запроса.

Более простой пример: GET находит и возвращает значение пользовательского поля, POST изменяет значение пользовательского поля или отправляет его куда-нибудь.

Вызов «SendContent» принимает входящие сообщения в том же формате JSON, который используется для блока «API-запрос».

Обратите внимание: методы POST и GET могут использоваться для одинаковых действий и запросов, однако в общепринятой практике метод GET должен получать данные откуда-нибудь, а метод POST — изменять или отправлять данные.

8. Каково назначение блока «API-запрос»?

Самая базовая цель блока «API-запрос» заключается в том, чтобы обратиться на внешний сервер, получить там JSON-код, преобразовать его в сообщение и отправить это сообщение пользователю.

Блок «API-запрос» можно использовать для вызова нашего API, однако это не главное его назначение, и мы не гарантируем, что такие вызовы будут работать правильно и что наш API вернет что-то в блок «API-запрос». Практически все такие запросы могут быть реализованы через обычный внутренний интерфейс.

Важное замечание об использовании Node_Buttons: если динамический блок пытается обращаться к нашему открытому API с кодом, включающим в себя кнопку/быстрый ответ «Перейти к узлу», он не будет работать. Блок «API-запрос» работает в контексте сценария, однако когда он вызывает открытый API, он покидает этот контекст и не может найти свой сценарий.

9. Каково назначение внешнего запроса?

Наиболее базовое назначение внешнего запроса — это обращение к внешнему серверу с одной из следующих целей:
1. Сохранение на нем каких-либо данных
2. Изменение на нем данных
3. Получение данных с сервера и возврат их в ManyChat через сопоставление ответов.
4. Комбинация вышеперечисленных целей.

Внешний запрос может также использоваться для вызова нашего открытого API с какими-либо заранее заданными значениями. Например, для переноса значения пользовательского поля из одного пользователя в другого в пределах одного бота.
Пример уведомления.

10. Каково назначение ключа API?

Это код, используемый для идентификации пользователя, разработчика или вызывающей программы на сайте. ManyChat предоставляет ключ API (функция PRO) для использования с открытым API аккаунта. Ключ открытого API можно получить в разделе «Настройки -> API».

Существует также Открытый API профиля, используемый для подключения к чему-либо, не связанному с конкретным ботом, например к шаблонам. Для этого API необходим отдельный ключ, который можно получить здесь.

Возможные неполадки

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

1. Если вы не понимаете, что происходит, загуглите ошибку.
Серьезно, зачастую решение легко находится на форуме Stack Overflow или на каком-нибудь сайте по программированию, в частности на форумах поддержки Facebook. Не забывайте, что ошибки инструментов для разработки не уникальны для ManyChat, они общие для всех подобных инструментов. Вот, например, список кодов состояния протокола HTTP для часто встречающихся ошибок.

2. Настоятельно рекомендуем ознакомиться с нашими вызовами API и примерами кода JSON.

Эти две ссылки отвечают на все вопросы о возможностях нашего открытого API. Если вы не находите метода, который пытаетесь найти, то такого метода не существует. Но вы можете запросить новую функцию здесь.

3. С помощью инструмента Jsonlint можно поискать в коде JSON проблемы, которые пропустило наше средство проверки, но это случается редко. Помните, что может быть необходимо снять флажок «Encode to JSON» (Кодировать в JSON), а вставленные пользовательские поля не нужно заключать в кавычки "".

Что значит флажок «Encode to JSON»?
У всех сайтов есть определенный протокол для получения запросов. У большинства из них множество флагов, фильтров и декодеров, которые преобразуют код JSON, отправляемый из нашей системы, в вид, который может обработать данный сайт. Некоторые из них принимают только строгий код JSON. Кодирование в JSON позволяет преобразовывать значение поля в JSON — это также необходимо, если в теле запроса только переменные, например {{Full Subscriber Data}}.

4. На этом сайте можно проверить и быстро протестировать любой запрос к API.

5. Ссылки на ресурсы, которые помогут вам найти ответ на любой вопрос о JSONPath (сопоставлении запросов):

Советы и ограничения:

1. Чтобы проверить, как блок «API-запрос» работает с сообщением с внешнего сервера, вы можете создать свой за пару минут — просто выполните действия, описанные в этой статье.

2. Вы также можете протестировать вызов API (вызов ManyChat или сервиса клиента) в своем аккаунте ManyChat.
Если это метод POST, вы можете редактировать тело запроса, пока не будет достигнуто рабочее решение.
Если это вызов API ManyChat, вам потребуется собственный токен API в заголовке; а если авторизация требуется в сервисе клиента, используйте те заголовки, которые клиент задал в своих инструментах разработки.

3. Если сервер клиента не требует авторизации и вы хотите смотреть ответ, который он возвращает, на новой вкладке, вы можете установить расширение для Google Chrome, например JSON Formatter и просматривать ответ сервера в структурированном виде:

4. Вы также можете скопировать ответ сервера с вкладки или из инструмента разработки и воспользоваться внешним средством форматирования JSON (например этим):

Этот инструмент также умеет выделять парные скобки.

5. Экспериментируйте с нашими инструментами для разработки, чтобы разобраться, как они работают — попробуйте создать запросы, повторяющие функциональность интерфейса ManyChat, например отправку сообщения, задание значения пользовательского поля и т. д.

Важно знать:

1. На длину URL запроса установлено ограничение 2000 символов.

2. Если пользовательское поле заполняется внутри карточки контакта, ограничение — 4000 символов. Однако если вы сохраняете значение из сообщения контакта в Messenger с помощью блока «Ввод данных», ограничение составляет около 20 000 — это максимальная длина сообщения в Messenger. Для API и полей данных бота ограничения не установлено.

3. Время ожидания ограничено 10 секундами. Изменить это невозможно.

4. В адресе запроса обязательно нужно указывать «https://», даже если существует поле, где это уже указано.

5. В URL запроса поддерживается только «https».

6. Не существует возможности распознать сообщение об ошибке, если возвращенный код — не «200 OK», и каким-либо образом отреагировать на каждую конкретную ошибку.

7. Не существует возможности отображать ответы на поля при тестировании запроса — это возможно, только при тестировании инструмента для разработки от лица контакта или при тестировании (предварительном просмотре) сценария.

8. Отображать на поля можно только код JSON, XML и т. п. Другие коды можно в лучшем случае отправлять в виде строки внутри кода JSON, и это считается костылем.

9. Для добавления переносов строки в сообщения внутри контента "content" -> "messages" следует использовать «/n».

Примеры настройки

1. В этом сценарии демонстрируется отправка уведомления пользователю бота, не являющемуся админом.

2. В этом сценарии демонстрируется работа генератора случайных чисел.

3. Вы можете получить текущий статус контакта с помощью этого метода API. Статус берется из поля «status» в объекте данных. У активного контакта status = active.