Действия для изменения данных

Создайте действие#

Используйте действие для изменения записи в своей системе, например отмены заказа. Откройте Агент → Действия, настройте секрет в Вошедшие клиенты и добавьте действие: уникальное имя, описание условий вызова, публичный HTTPS endpoint и строковые входные параметры. Имя cancel_order становится инструментом change_cancel_order. Изменения существующих полей сохраняются автоматически; дождитесь индикатора сохранения.

Для закрытых записей оставьте включённым требование входа клиента. Endpoint также обязан проверить принадлежность записи по подтверждённому ID клиента. Имя, email или номер заказа в чате не подтверждают личность. Если отключить требование, customer может быть null: разрешайте лишь изменения, доступные анонимному посетителю. Платежи не входят в эту функцию.

Выберите одобрение владельца#

Подтверждение клиента обязательно во всех режимах:

Владелец сайта может одобрить или отклонить запрос в Агент → Действия → Запросы на одобрение. Если подключены личные Telegram-уведомления владельца, в сообщении также есть кнопки Одобрить / Отклонить. Они работают только в привязанном личном чате владельца; просроченные и повторные нажатия не запускают действие снова. Срок одобрения — 24 часа после подтверждения клиента. Клиент получает результат, включая отказ или истечение срока. Журнал последних запусков показывает статус, время, номер результата и ID клиента.

Какой запрос получает endpoint#

Предложение модели не отправляет запрос. После подтверждения клиента и необходимого одобрения владельца Make Agent Fast отправляет:

POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b

{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}

В action нет префикса change_. Оба ID и заголовок идемпотентности сохраняются при повторах. input содержит только объявленные строки с удалёнными пробелами по краям. customer — null либо проверенный объект с id и необязательными email/name.

Используйте проверку подписи lookup: HMAC-SHA256 с секретом агента по "maf-webhook-v1:" + timestamp + "." + rawBody, hex в нижнем регистре с префиксом v1=. До записи проверяйте исходные байты, свежесть времени, ожидаемые сайт/действие и права клиента на запись. Атомарно выполняйте проверку дубликата по x-maf-idempotency-key вместе с изменением и сохраняйте результат. Повторный запрос должен возвращать сохранённый итог без повторного изменения записи. Блокировка платформы не заменяет дедупликацию в вашей системе.

Верните результат#

Ответьте 2xx JSON с обязательным status (done, pending или failed) и необязательными message, reference, card:

{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}

Необязательная карточка статуса требует title и fields; kind: "status" можно опустить. Как в lookup, поддерживаются status: { label, tone }, reference, asOf и link: { label, url }. tone: neutral, success, warning или danger; ссылка должна быть безопасным HTTPS URL. Неизвестные поля схемы отклоняются. Используйте короткий обычный текст. Итог определяет внешний status: текст карточки не превращает ожидание в успех.

Отправляйте done только после завершения изменения, pending — во время обработки, failed — при установленной ошибке. Тайм-ауты, сетевые ошибки, 5xx и неверные ответы дают неопределённый статус unknown. Проверка повторяет выполнение через минуту, затем через пять минут, максимум три попытки с тем же ключом. Очередь может увеличить задержку. HTTP 4xx завершает запуск ошибкой без повторов. Когда попытки при неопределённом результате исчерпаны, запуск помечается как неудачный и владелец получает уведомление, но это не доказывает отсутствие изменений в вашей системе. Проверьте её перед новым запуском. pending не вызывает повторного выполнения.

Отправьте подписанный итоговый callback#

Когда результат pending или unknown определён, отправьте POST на https://makeagent.fast/api/agent/actions/RUN_ID/callback. Используйте тот же контракт ответа со status: "done" или "failed"; pending здесь не принимается.

Контракт callback обновлён 2026-10-14: подписывайте maf-callback-v1: + runId + : + timestamp + . + rawBody. Если тело содержит runId, он должен совпадать с ID запуска в пути; несовпадение возвращает 400. Подпись другого запуска или прежнего формата возвращает 403.

import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);

Используйте секрет агента на сервере и run ID исходного запроса. Для callback нужен отдельный префикс maf-callback-v1:, а не префикс исходящих запросов. Расхождение времени допускается в пределах пяти минут. Неверная подпись даёт 403, неверное тело — 400, уже конечное или несовместимое состояние — 409. Повторный callback не перезаписывает итог. При ротации секрета обновите также настройки подписи идентификации и endpoint.

Подтверждение клиента и карточки результата#

Клиент проверяет точные параметры и нажимает Подтвердить или Отменить. Предложение действует 15 минут; новое предложение того же действия в том же разговоре заменяет прежнее. Токен подтверждения привязан к запуску, сайту и посетителю. Сообщение «да» или обычная карточка подтверждения не разрешают изменение. Кнопки репетиции неактивны и не вызывают endpoint.

Открытый веб-виджет опрашивает незавершённые результаты сначала каждые пять секунд, затем каждые 30 секунд, до 24 часов. Карточка показывает запрос, ожидание владельца, выполнение, обработку, проверку неизвестного результата, успех, ошибку, отказ, отмену или истечение срока. Только done подтверждает завершение.

В каналах предложения работают только в личных чатах, не в группах и каналах. Отложенные результаты идут через надёжную очередь: поддерживаются обычные личные чаты Telegram-бота; WhatsApp, Messenger, Instagram и Telegram Business требуют зафиксированного входящего сообщения за последние 24 часа. Условие проверяется повторно при отправке. Для гостевых запросов Telegram, Discord и KakaoTalk отложенная доставка недоступна. Закрытое окно или отключённое соединение могут помешать доставке, но результат остаётся в истории запуска.

Ограничения и тестирование#

На контролируемом endpoint проверьте подтверждение, отмену, одобрение, тайм-аут, повторный ключ и итоговый callback. Проверяйте записи системы, а не только текст карточки. Репетиция не делает внешнюю запись и не является проверкой выполнения endpoint. Испытайте каждый нужный личный канал до того, как полагаться на доставку.