Шаблоны ответов в чаты

В данном разделе описываются доступные методы для работы с шаблонами ответов в чаты.

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

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

Загрузка файлов в шаблоны, в данный момент не доступна.

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

Оглавление

Список шаблонов

Метод

GET /api/v4/chats/templates

Описание

Метод позволяет получить список шаблонов в аккаунте.

Ограничения

  • Метод возвращает только те шаблоны, которые были созданы текущей интеграцией
  • Метод доступен в соответствии только администратору аккаунта

GET параметры

Параметр Тип данных Описание
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 50)
filter[external_id] string или array Фильтр по внешнему идентификатору. Можно передать 1 строкой, или массив из нескольких идентификаторов

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
204 Шаблоны не найдены
401 Пользователь не авторизован

Параметры ответа

Метод возвращает коллекцию моделей шаблонов, рассмотрим ниже свойства модели.

Параметр Тип данных Описание
id int ID шаблона
account_id int ID аккаунта, которому принадлежит шаблон
name string Название шаблона
content string Тело шаблона, сообщение, которое отправляется пользователю
is_editable bool Может ли пользователь редактировать шаблон в интерфейсе amoCRM
buttons array Массив объектов кнопок
buttons[][type] string Тип кнопки, доступные варианты: inline (обычная текстовая кнопка), url (кнопка ссылка)
buttons[][text] string Текст, отображаемый в кнопке
buttons[][url] string Ссылка кнопки, доступно только для кнопки типа url
attachment object|null Объект добавленного файла в шаблон
attachment[id] string UUID файла, прикрепленного к шаблону
attachment[name] string Название файла, прикрепленного к шаблону, которое будет передано в мессенджер
attachment[type] string Тип прикрепленного файла. Возможные типы – picture, file, document, video
attachment[is_external] bool Показатель, что файл из сервиса файлов. Для всех шаблонов добавляемых с весны 2022 – true
created_at int Timestamp создания шаблона
updated_at int Timestamp последнего изменения шаблона
external_id string Внешний идентификатор шаблона. ID шаблона в вашей системе

Пример ответа

{
  "_page": 1,
  "_links": {
    "self": {
      "href": "https://example.amocrm.ru/api/v4/chats/templates?page=1&limit=50"
    },
    "next": {
      "href": "https://example.amocrm.ru/api/v4/chats/templates?page=2&limit=50"
    }
  },
  "_embedded": {
    "chat_templates": [
      {
        "id": 7349,
        "account_id": 29420107,
        "name": "Test template",
        "content": "New content. Contact name - {{contact.name}}",
        "created_at": 1640360627,
        "updated_at": 1640360627,
        "buttons": [
          {
            "text": "кнопка 1",
            "type": "inline"
          },
          {
            "text": "кнопка 2",
            "type": "inline"
          }
        ],
        "attachment": {
            "id": "5ee9417d-afb8-46eb-9388-0490c75d5ea1",
            "name": "Название файла",
            "type": "picture",
            "is_external": true
        },
        "is_editable": false,
        "external_id": "my_external_id",
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/chats/templates/7349"
          }
        }
      }
    ]
  }
}

Получение шаблона по ID

Метод

GET /api/v4/chats/templates/{id}

Описание

Метод позволяет получить данные конкретного шаблона по ID.

Ограничения

Метод доступен в соответствии с правами пользователя.

GET параметры

Дополнительные GET параметры отсутствуют.

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
404 Шаблон с указанным ID не существует
401 Пользователь не авторизован

Параметры ответа

Метод возвращает модель шаблона, рассмотрим ниже её свойства.

Параметр Тип данных Описание
id int ID шаблона
account_id int ID аккаунта, которому принадлежит шаблон
name string Название шаблона
content string Тело шаблона, сообщение, которое отправляется пользователю
is_editable bool Может ли пользователь редактировать шаблон в интерфейсе amoCRM
buttons array Массив объектов кнопок
buttons[][type] string Тип кнопки, доступные варианты: inline (обычная текстовая кнопка), url (кнопка ссылка)
buttons[][text] string Текст, отображаемый в кнопке
buttons[][url] string Ссылка кнопки, доступно только для кнопки типа url
attachment object|null Объект добавленного файла в шаблон
attachment[id] string UUID файла, прикрепленного к шаблону
attachment[name] string Название файла, прикрепленного к шаблону, которое будет передано в мессенджер
attachment[type] string Тип прикрепленного файла. Возможные типы – picture, file, document, video
attachment[is_external] bool Показатель, что файл из сервиса файлов. Для всех шаблонов добавляемых с весны 2022 – true
created_at int Timestamp создания шаблона
updated_at int Timestamp последнего изменения шаблона
external_id string Внешний идентификатор шаблона. ID шаблона в вашей системе

Пример ответа

{
  "id": 7349,
  "account_id": 29420107,
  "name": "Test template",
  "content": "New content. Contact name - {{contact.name}}",
  "created_at": 1640360627,
  "updated_at": 1640360627,
  "buttons": [
    {
      "text": "кнопка 1",
      "type": "inline"
    },
    {
      "text": "кнопка 2",
      "type": "inline"
    }
  ],
  "attachment": {
    "id": "5ee9417d-afb8-46eb-9388-0490c75d5ea1",
    "name": "Название файла",
    "type": "picture",
    "is_external": true
  },
  "is_editable": false,
  "external_id": "my_external_id",
  "_links": {
    "self": {
      "href": "https://example.amocrm.ru/api/v4/chats/templates/7349"
    }
  }
}

Добавление шаблона

Метод

POST /api/v4/chats/templates

Описание

Метод позволяет добавлять шаблоны в аккаунт пакетно.

Ограничения

Метод доступен только администратору.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля – name, content

Параметр Тип данных Описание
name string Название шаблона
content string Тело шаблона, сообщение, которое отправляется пользователю. Можно использовать маркеры Salesbot.
is_editable bool Может ли пользователь редактировать шаблон в интерфейсе amoCRM. По умолчанию – false
buttons array Массив объектов кнопок
buttons[][type] string Тип кнопки, доступные варианты: inline (обычная текстовая кнопка), url (кнопка ссылка)
buttons[][text] string Текст, отображаемый в кнопке
buttons[][url] string Ссылка кнопки, доступно только для кнопки типа url
attachment object|null Объект добавленного файла в шаблон
attachment[id] string UUID файла из API файлов, прикрепленного к шаблону
attachment[name] string Название файла, прикрепленного к шаблону, которое будет передано в мессенджер
attachment[type] string Тип прикрепленного файла. Возможные типы – picture, file, document, video
external_id string Внешний идентификатор шаблона. ID шаблона в вашей системе
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр

Пример запроса

[
  {
    "name": "Hello template",
    "content": "Hello {{contact.name}}",
    "external_id": "my_external_id_for_hello",
    "buttons": [
      {
        "type": "inline",
        "text": "button 1"
      },
      {
        "type": "inline",
        "text": "button 2"
      }
    ],
    "attachment": {
      "id": "c2b77f70-d0d6-484a-8f6e-583f70a08cce",
      "name": "Название изображения",
      "type": "picture"
    }
  }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Шаблоны были успешно созданы
422 Запрос не может быть обработан, превышен лимит шаблонов
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод возвращает коллекцию шаблонов, которые были созданы.

Метод возвращает модель шаблона, рассмотрим ниже её свойства.

Параметр Тип данных Описание
id int ID шаблона
account_id int ID аккаунта, которому принадлежит шаблон
name string Название шаблона
content string Тело шаблона, сообщение, которое отправляется пользователю
is_editable bool Может ли пользователь редактировать шаблон в интерфейсе amoCRM
buttons array Массив объектов кнопок
buttons[][type] string Тип кнопки, доступные варианты: inline (обычная текстовая кнопка), url (кнопка ссылка)
buttons[][text] string Текст, отображаемый в кнопке
buttons[][url] string Ссылка кнопки, доступно только для кнопки типа url
attachment object|null Объект добавленного файла в шаблон
attachment[id] string UUID файла из API файлов, прикрепленного к шаблону
attachment[name] string Название файла, прикрепленного к шаблону, которое будет передано в мессенджер
attachment[type] string Тип прикрепленного файла. Возможные типы – picture, file, document, video
created_at int Timestamp создания шаблона
updated_at int Timestamp последнего изменения шаблона
external_id string Внешний идентификатор шаблона. ID шаблона в вашей системе

Пример ответа

{
  "_total_items": 1,
  "_embedded": {
    "chat_templates": [
      {
        "id": 7351,
        "account_id": 29420107,
        "name": "Hello template",
        "content": "Hello {{contact.name}}",
        "created_at": 1640362536,
        "updated_at": 1640362536,
        "buttons": [
          {
            "type": "inline",
            "text": "button 1"
          },
          {
            "type": "inline",
            "text": "button 2"
          }
        ],
        "attachment": {
          "id": "c2b77f70-d0d6-484a-8f6e-583f70a08cce",
          "name": "Название изображения",
          "type": "picture"
        },
        "is_editable": false,
        "external_id": "my_external_id_for_hello",
        "request_id": "0",
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/chats/templates/7351"
          }
        }
      }
    ]
  }
}

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

Метод

PATCH /api/v4/chats/templates
PATCH /api/v4/chats/templates/{id}

Описание

Метод позволяет редактировать шаблоны пакетно.
Также вы можете добавить ID шаблоны в метод для редактирования конкретного шаблона (/api/v4/chats/templates/{id}).
При редактировании пакетно передается массив из объектов, при редактировании одного шаблона, передается просто модель.

Ограничения

Метод доступен только администраторам аккаунта

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля отсутствуют

Параметр Тип данных Описание
id int ID шаблона
name string Название шаблона
content string Тело шаблона, сообщение, которое отправляется пользователю. Можно использовать маркеры Salesbot.
is_editable bool Может ли пользователь редактировать шаблон в интерфейсе amoCRM. По умолчанию – false
buttons array Массив объектов кнопок
buttons[][type] string Тип кнопки, доступные варианты: inline (обычная текстовая кнопка), url (кнопка ссылка)
buttons[][text] string Текст, отображаемый в кнопке
buttons[][url] string Ссылка кнопки, доступно только для кнопки типа url
attachment object|null Объект добавленного файла в шаблон
attachment[id] string UUID файла из API файлов, прикрепленного к шаблону
attachment[name] string Название файла, прикрепленного к шаблону, которое будет передано в мессенджер
attachment[type] string Тип прикрепленного файла. Возможные типы – picture, file, document, video
external_id string Внешний идентификатор шаблона. ID шаблона в вашей системе
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр

Пример запроса

[
  {
    "id": 7351,
    "name": "My new name",
    "content": "My new content",
    "buttons": [
      {
        "type": "inline",
        "text": "кнопка 1"
      },
      {
        "type": "inline",
        "text": "кнопка 2"
      }
    ],
    "attachment": {
      "id": "c2b77f70-d0d6-484a-8f6e-583f70a08cce",
      "name": "Название изображения",
      "type": "picture"
    },
    "is_editable": true
  }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Шаблон были успешно изменены
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

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

Пример ответа

{
  "_total_items": 1,
  "_embedded": {
    "chat_templates": [
      {
        "id": 7351,
        "account_id": 29420107,
        "name": "My new name",
        "content": "My new content",
        "created_at": 1640362536,
        "updated_at": 1640363257,
        "buttons": [
          {
            "type": "inline",
            "text": "кнопка 1"
          },
          {
            "type": "inline",
            "text": "кнопка 2"
          }
        ],
        "attachment": {
          "id": "c2b77f70-d0d6-484a-8f6e-583f70a08cce",
          "name": "Название изображения",
          "type": "picture"
        },
        "is_editable": true,
        "external_id": "my_external_id_for_hello",
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/chats/templates/7351"
          }
        }
      }
    ]
  }
}

Удаление шаблонов

Метод

DELETE /api/v4/chats/templates
DELETE /api/v4/chats/templates/{id}

Описание

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

Ограничения

  • Метод доступен только с правами администратора аккаунта

Заголовок запроса

Content-Type: application/json

Параметры запроса

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

При удалении нескольких шаблонов, нужно передать объекты для удаления с ID шаблонов.

Параметр Тип данных Описание
id int ID шаблона

Пример запроса

[
  {
    "id": 7351
  }
]

HTTP коды ответа

Код ответа Условие
204 Шаблоны была успешно удалены
403 Не хватает прав для вызова данного метода
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод не возвращает тело