Как правильно заполнить шаблон Webhook

При настройке интеграции через Webhook, вам нужно написать специальный шаблон: в нем прописываются значения, которые бот будет отправлять в сообщении. В Пачке поддерживается два формата таких шаблонов: Mustache и Liquid.

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

‍

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

‍

Пример данных в формате JSON:

{
  "name": "Vadim Grushev",
  "age": 25,
  "isStudent": false,
  "hobbies": ["reading", "gardening"],
  "address": {
    "street": "123 Main Street",
    "city": "Anytown"
  }
}

К полям, которые вы описываете в шаблонах, можно применять форматирование (как к сообщениям в Пачке). Например, если мы напишем {{"**{{description}}**"}}, то бот отправит значение этого поля с форматированием «жирный текст».

Откуда брать поля для заполнения шаблона

Для того чтобы узнать, какие поля указывать в шаблоне, нужно посмотреть структуру **JSON **запроса, которая приходит от стороннего сервиса. Для этого можно воспользоваться специальным сервисом для создания тестовых Webhook:

1. Откройте https://webhook.site/
2. Скопируйте адрес из поля «Your unique URL»
3. Вставьте скопированный адрес в сервис, который хотите подключить к Пачке. Его нужно вставить на этапе настройке Webhook. Если вы уже настроили интеграцию с Пачкой, то просто замените Webhook URL Пачки на скопированный адрес
4. Сделайте триггерное действие в сервисе, который вы подключаете. Вы его настраивали при создании Webhook.
5. После этого на странице отобразится запрос в формате JSON, который прислал сервис.
6. Выберите те поля, которые вы хотите отобразить в сообщениях бота. Вставьте их в ваш Liquid или Mustache шаблон.

Mustache —

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

Синтаксис Mustache

В шаблоне Mustache все поля заключаются в двойные скобки {{"{{name}}"}}

JSON запрос:

{
  "name": "Roman",
  "age": 10
}

Mustache шаблон:

Привет, {{name}}!

Сообщение от бота:

Привет, Roman!

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

JSON запрос:

{
  "Student": {
    "Requisites": {
      "Name": "Artem"
    }
  }
}

Mustache шаблон:

{{#Student}}
  {{#Requisites}}
    {{Name}}
  {{/Requisites}}
{{/Student}}

Сообщение от бота:

Artem

Пример Mustache шаблона:

JSON:

{
  "user": {
    "id": "12345",
    "userName": "Vadim Grushev"
  },
  "issue": {
    "id": "10000",
    "fields": {
      "title": "Очень важная задача",
      "description": "Что-то что нужно сделать срочно",
      "project": {
        "name": "Pachca"
      }
    }
  }
}

Mustache шаблон:

Новое событие в проекте {{#issue}}{{#fields}}{{#project}}**{{name}}**{{/project}}{{/fields}}{{/issue}}

{{#user}}**{{userName}}**{{/user}}

**Название задачи**

{{#issue}}{{#fields}}{{title}}{{/fields}}{{/issue}}

**Описание задачи**

{{#issue}}{{#fields}}{{description}}{{/fields}}{{/issue}}

Сообщение от бота:

Новое событие в проекте **Pachca**

**Vadim Grushev**

**Название задачи**

Очень важная задача

**Описание задачи**

Что-то что нужно сделать срочно

Больше методов работы с Mustache можно найти по ссылке.

Liquid —

это язык шаблонов, который позволяет создать единый шаблон и динамически его изменять. В отличие от Mustache, позволяет использовать логические операторы if, else и тд. Например, с его помощью, можно присылать разные сообщения, в зависимости от того положительный или отрицательный отзыв оставил клиент.

Синтаксис Liquid

Объекты — представляют из себя структуру данных, описывающую поля из JSON. Для доступа к объектам и их свойствам используются двойные фигурные скобки {{"{{ object.field }}"}}

JSON запрос:

{
  "student": {
    "requisites": {
      "name": "Anton"
    }
  }
}

Liquid шаблон:

{{student.requisites.name}}

Сообщение от бота:

Anton

Теги — используются для определения логики, которая позволяет выводить разные поля, в зависимости от описанных условий. Теги и свойства объектов заключаются в одинарные фигурные скобки с процентным разделителем {{"{%"}} elsif {{"%}"}}

JSON запрос:

{
  "student": {
    "requisites": {
      "name": "Dima"
    }
  }
}

Liquid шаблон:

{% assign Name = student.requisites.name %}
{% if Name != "" and Name != null %}
  Hey {{Name}}!
{% else %}
  Hi Stranger!
{% endif %}

Сообщение от бота:

Hey Dima!

‍

Фильтры — используются для изменения вывода переменных и объектов. Фильтры описываются в одинарных фигурных скобках и отделяются от объектов вертикальной чертой {{"{{ | }}"}}

Liquid шаблон:

{{ "CALM DOWN!" | downcase }}

Сообщение от бота:

calm down!

Пример Liquid шаблона:

JSON запрос:

{
  "application": {
    "id": "12345",
    "name": "Заявка на таблицу сравнения",
    "contact": {
      "number": "+799999999999",
      "call": true
    }
  }
}

Liquid шаблон:

{% assign Source = application.name%}
{% if Source contains 'демо' %}
{% assign heading = "**Новая заявка на демонстрацию**" %}
{% elseif Source contains 'таблицу' %}
{% assign heading = "**Новая заявка на таблицу**" %}
{% endif %}
{{heading}}

{% if application.contact.call == true  %}
	"Связаться по телефону:"
{% else %}
	"Написать в мессенджер:"
{% endif %}

{{application.contact.number}}

Сообщение от бота:

**Новая заявка на таблицу**

Связаться по телефону:
+799999999999

Больше методов работы с Liquid можно найти по ссылке.