Для разработчиков

API

Message Gateway API

Интеграция транспортных модулей с поддержкой создания и отправки шаблонов WhatsApp Business

Интеграция транспортных модулей с поддержкой создания и отправки шаблонов WhatsApp Business

Скопировать ссылку на статью

Скопировано

Создание шаблонов сообщений предоставляет пользователям ряд преимуществ и значительно упрощает процесс взаимодействия с клиентами.

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

Система поддерживает использование как текстовых, так и медиа-шаблонов.

Текстовое тело доступно для обоих типов шаблонов и поддерживает использование twig-выражений. Эти выражения вычисляются при отправке сообщений из системы. Медиа-шаблоны предоставляют возможность добавить текстовый заголовок или файловое вложение (изображение, документ, видео). Текстовый заголовок также может быть параметризован с использованием twig-выражений, позволяя, например, добавить имя клиента для персонализации сообщения. В медиа-шаблонах можно добавлять кнопки быстрых ответов (до 10 штук) и функциональные кнопки для выполнения различных действий, таких как переход по URL или звонок. Для кнопок-ссылок также предусмотрена параметризация нагрузки с использованием twig-выражений.

Подробную информацию о доступных структурных компонентах шаблона можно найти в документации WhatsApp Business.

Для использования данной функциональности требуется поддержка со стороны модулей транспортов.

Для поддержки отправки шаблонных сообщений необходимо при создании или обновлении настроек канала указывать хотя бы одну из следущих настроек sending_policy.after_reply_timeout = 'template'либо sending_policy.new_customer = 't``emplate'.

Настройка sending_policy.after_reply_timeout активирует возможность отправки шаблона по истечении установленного временного окна для ответа на сообщение и может принимать одно из значений no,template. Установка первого значения не предполагает дальнейшего продолжения коммуникации со стороны менеджера в системе по окончании временного окна для ответа на диалог. Установка значения template делает доступным отправку шаблонных сообщений поста истечения временного окна, отведенного менеджеру на ответ (указанного в поле reply_deadlineпри отправке сообщения).

Настройка sending_policy.after_reply_timeout активирует возможность отправки шаблонного сообщения клиенту первым со стороны менеджера системы и может принимать одно из значений: no (запрещено начинать новый диалог с клиентом по номеру телефона при его отсутствии), text (доступна отправка текстового сообщения), template (доступна отправка шаблонного сообщения).

Для активации возможности создания шаблонов в системе необходимо явно указать поддержку данной функциональности у канала транспорта. При создании или обновлении настроек канала нужно установить значение поля settings.template.creation = true. Подключение хотя бы одного канала с этой настройкой делает доступной форму создания и редактирования шаблона (Настройки → Шаблоны чатов → Добавить).

Создание шаблона чатов в интерфейсе системы

При создании шаблона в системе модуль транспорта оповещается об этом путем вызова метода вебхука с типом template_create. URL вебхука указывается при конфигурировании интеграционного модуля (подробности описаны в статье). Пример тела запроса создания шаблона на вебхук:

{
  "type": "template_create",
  "meta": {
    "timestamp": 1704878609
  },
  "data": {
    "name": "greeting_template",
    "lang": "ru",
    "category": "marketing",
    "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
    "header": {
      "content": {
        "body": "{{1}}, thank you for your order!",
        "type": "text"
      }
    },
    "footer": "Thank you for being with us!",
    "buttons": {
      "items": [
        {
          "label": "Our website",
          "url": "<http://site.com/profile/{{1}>}",
          "type": "url"
        },
        {
          "label": "Our phone number",
          "phone": "79998887766",
          "type": "phone"
        },
        {
          "label": "Amazing!",
          "type": "plain"
        }
      ]
    },
    "example": {
      "body": [
        "ORDER-123"
      ],
      "header": [
        "Alex"
      ],
      "buttons": [
        ["111"],
        []
      ]
    },
    "channel_id": 1
  }
}

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

{
  "code": "f87e678f_660b_461a_b60a_a6194e2e0284#greeting_template#en"
}

После получения информации о созданном шаблоне через вебхук транспорт должен отправить созданный шаблон на верификацию провайдеру. Шаблон будет находиться в системе в статусе «Верифицируется» до получения статуса верификации от провайдера (подтверждение или отклонение). Максимальный срок ожидания верификации составляет до 2 рабочих дней.

Изменение статуса подтверждения шаблона

После подтверждения или отклонения шаблона со стороны провайдера модуль транспорта должен передать информацию об обновленном статусе шаблона в систему. Для этого используется метод обновления шаблона транспортного API PUT /channels/{channel_id}/templates/{template_code}. Пример тела HTTP-запроса на обновление шаблона:

{
  "name": "greeting_template",
  "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
  "verification_status": "rejected",
  "rejection_reason": "scam",
  "header": {
    "content": {
      "type": "text",
      "body": "{{1}}, thank you for your order!"
    }
  },
  "footer": "Thank you for being with us!",
  "buttons": {
    "items": [
      {
        "type": "url",
        "label": "Our website",
        "url": "<http://site.com/profile/{{1}>}"
      },
      {
        "type": "phone",
        "label": "Our phone number",
        "phone": "79998887766"
      },
      {
        "type": "plain",
        "label": "Amazing!"
      }
    ]
  }
}

В указанной выше структуре поле verification_status может принимать одно из следующих значений:

approved - шаблон подтвержден провайдером и может быть использован при отправке сообщений;
pending - шаблон находится в стадии ожидания подтверждения от провайдера;
rejected - шаблон отклонен провайдером.

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

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

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

abusive_content - в шаблоне присутствует оскорбительный контент, нецензурные выражения и т.д.
incorrect_category - некорректно определена категория шаблона (см. документацию WhatsApp по категориям).
invalid_format - некорректный формат шаблона.
scam - контент определен транспортом как мошеннический.

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

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

Редактирование шаблона

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

{
  "type": "template_update",
  "meta": {
    "timestamp": 1704881744
  },
  "data": {
    "name": "greeting_template",
    "lang": "ru",
    "category": "marketing",
    "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
    "header": {
      "content": {
        "body": "{{1}}, thank you for your order!",
        "type": "text"
      }
    },
    "footer": "Thank you for being with us!",
    "buttons": {
      "items": [
        {
          "label": "Our website",
          "url": "<http://site.com/profile/{{1}>}",
          "type": "url"
        },
        {
          "label": "Our phone number",
          "phone": "79998887766",
          "type": "phone"
        },
        {
          "label": "Amazing!",
          "type": "plain"
        }
      ]
    },
    "example": {
      "body": [
        "ORDER-123"
      ],
      "header": [
        "Alex"
      ],
      "buttons": [
        ["111"],
        []
      ]
    },
    "channel_id": 1,
    "code": "f87e678f_660b_461a_b60a_a6194e2e0284#greeting_template#en"
  }
}

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

Создание шаблонов на стороне провайдера

Пользователям также доступна возможность создания и редактирования шаблонов на стороне провайдера.

Для передачи информации о созданном шаблоне используется метод создания шаблона POST /channels/{channel_id}/templates в транспортном API чатов. Пример тела HTTP запроса на создание шаблона:

{
  "code": "GREETING_TEMPLATE",
  "name": "Greeting",
  "type": "media",
  "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
  "verification_status": "approved",
  "header": {
    "content": {
      "type": "image"
    }
  },
  "examples": {
    "header": [
      "<https://image.com/image>"
    ],
    "body": [
      "ORDER-123"
    ]
  },
  "footer": "Thank you for being with us",
  "buttons": {
    "items": [
      {
        "type": "url",
        "label": "Our website",
        "url": "<https://website.com/profile/{{1}>}"
      },
      {
        "type": "phone",
        "label": "Our phone",
        "phone": "79998887766"
      },
      {
        "type": "plain",
        "label": "Amazing!"
      }
    ]
  }
}

Копирование и удаление шаблона

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

При удалении последней из копий шаблонов в системе, привязанной к данному шаблону транспорта, также происходит его удаление. Модуль транспорта оповещается об этом с помощью вебхука типа template_delete.

Пример тела вебхука:

{
  "type": "template_delete",
  "meta": {
    "timestamp": 1704882331
  },
  "data": {
    "channel_id": 1,
    "code": "f87e678f_660b_461a_b60a_a6194e2e0284#greeting_template#en",
    "lang": "ru"
  }
}

Отправка шаблонных сообщений

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

{
  "type": "message_sent",
  "meta": {
    "timestamp": 1704882857
  },
  "data": {
    "external_user_id": "79998887766",
    "external_chat_id": "",
    "channel_id": 1,
    "type": "text",
    "content": "Max, thank you for your order!\\n\\nOrder #ORDER-111 has been successfully placed. Thank you for your purchase!\\n\\nThank you for being with us!",
    "quote_external_id": null,
    "quote_content": null,
    "in_app_id": 1000,
    "user": {
      "id": 216,
      "first_name": "Ilya",
      "last_name": "",
      "avatar": ""
    },
    "customer": {
      "first_name": "",
      "last_name": "",
      "avatar": ""
    },
    "template": {
      "code": "f87e678f_660b_461a_b60a_a6194e2e0284#greeting_template#en",
      "variables": {
        "header": {
          "type": "text",
          "args": [
            "Max"
          ]
        },
        "body": {
          "args": [
            "ORDER-111"
          ]
        },
        "buttons": [
          {
            "type": "url",
            "title": "Our website",
            "args": [
              "987"
            ]
          },
          {
            "type": "phone",
            "title": "Our phone number"
          },
          {
            "type": "plain",
            "title": "Amazing!"
          }
        ]
      }
    },
    "attachments": {
      "suggestions": [
        {
          "type": "url",
          "title": "Our website",
          "payload": "<http://site.com/profile/987>"
        },
        {
          "type": "phone",
          "title": "Our phone number",
          "payload": "79998887766"
        },
        {
          "type": "text",
          "title": "Amazing!"
        }
      ]
    }
  }
}

Особенности в работе с шаблонами, поддерживающими файловые вложения

При создании шаблонов с файловыми вложениями в заголовках структура запросов и вебхуков изменяется - вместо передачи поля headerс информацией о текстовом заголовке добавляется поле attachmentsс информацией о прикрепленном файле. На данный момент поддерживаются следующие типы файлов:

Тип вложения	Разрешенные типы файлов	Макс. размер файла
Документ	`pdf`	100 Мб
Изображение	`jpeg`, `jpg`, `png`	5 Мб
Видео	`mp4`	16 Мб

Допустимые типы при работе с вложениями:

image- изображение;
document- документы;
video- видео-файлы.

Ниже приведены примеры тела вебхуков и запросов к транспортному API при работе с медиа-вложениями (на примере типа image).

Пример тела вебхука template_create на создание шаблона:

{
                "code": "GREETING_TEMPLATE",
                "name": "Greeting",
                "type": "media",
                "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
                "verification_status": "approved",
                "header": {
                    "content": {
                        "type": "image"
                    }
                },
                "examples": {
                    "header": ["https://image.com/image"],
                    "body": ["ORDER-123"]
                },
                "footer": "Thank you for being with us",
                "buttons": {
                    "items": [
                        {
                            "type": "url",
                            "label": "Our website",
                            "url": "https://website.com/profile/{{1}}"
                        },
                        {
                            "type": "phone",
                            "label": "Our phone",
                            "phone": "79998887766"
                        },
                        {
                            "type": "plain",
                            "label": "Amazing!"
                        }
                    ]
                }
            }

Пример тела HTTP запроса на обновление шаблона из метода PUT /channels/{channel_id}/templates/{template_code} транспортного API:

            {
  "name": "Template name",
  "body": "Order #{{1}} has been successfully placed. Thank you for your purchase!",
  "verification_status": "rejected",
  "rejection_reason": "scam",
  "header": {
    "content": {
      "type": "image"
    }
  },
  "footer": "Thank you for being with us!",
  "buttons": {
    "items": [
      {
        "type": "url",
        "label": "Our website",
        "url": "http://site.com/profile/{{1}}"
      },
      {
        "type": "phone",
        "label": "Our phone number",
        "phone": "79998887766"
      },
      {
        "type": "plain",
        "label": "Amazing!"
      }
    ]
  }
}

Пример тела вебхука message_sent на редактирование шаблона:

{
  "type": "message_sent",
  "meta": {
    "timestamp": 1704889793
  },
  "data": {
    "external_user_id": "79998887766",
    "external_chat_id": "",
    "channel_id": 83,
    "type": "image",
    "content": "Order #ORDER-111 has been successfully placed. Thank you for your purchase!\n\nThank you for being with us!",
    "quote_external_id": null,
    "quote_content": null,
    "in_app_id": 1000,
    "user": {
      "id": 216,
      "first_name": "Ilya",
      "last_name": "",
      "avatar": ""
    },
    "customer": {
      "first_name": "",
      "last_name": "",
      "avatar": ""
    },
    "items": [
      {
        "id": "bfd530ae-42e7-4a10-94fb-d56383afcac4",
        "size": 87346,
        "caption": "demo_file.jpg",
        "height": 900,
        "width": 900
      }
    ],
    "template": {
      "variables": {
        "header": {
          "type": "image",
          "attachments": [
            {
              "id": "bfd530ae-42e7-4a10-94fb-d56383afcac4",
              "caption": "demo_file.jpg"
            }
          ]
        },
        "body": {
          "args": [
            "ORDER-111"
          ]
        },
        "buttons": [
          {
            "type": "url",
            "title": "Our website",
            "args": [
              "987"
            ]
          },
          {
            "type": "phone",
            "title": "Our phone number"
          },
          {
            "type": "plain",
            "title": "Amazing!"
          }
        ]
      }
    },
    "attachments": {
      "suggestions": [
        {
          "type": "url",
          "title": "Our website",
          "payload": "http://site.com/profile/987"
        },
        {
          "type": "phone",
          "title": "Our phone number",
          "payload": "79998887766"
        },
        {
          "type": "text",
          "title": "Amazing!"
        }
      ]
    }
  }
}

Благодарим за отзыв.

Была ли статья полезна?

Нет

Да

Предыдущая статья

Transport API

Transport API - список API методов для создания транспортов.

Интеграция транспортных модулей с поддержкой создания и отправки шаблонов WhatsApp Business Скопировать ссылку на статью Скопировано