Сценарии для агента

Шесть законченных сценариев: от пустого ключа до ответа клиенту. Каждый шаг показан дважды: инструментом MCP (так делает нейросеть) и запросом curl (так делает ваш сервер). Справочник всех адресов: эндпоинты и инструменты.

#Что нужно один раз

#Сценарий 1. Ответить клиенту, который написал

Самый частый случай: человек написал в Telegram, отвечает нейросеть.

1. tuktuk_list_channels: через какой канал вообще можно говорить.
2. tuktuk_find_contact по телефону, email или имени: получить dialogId.
3. tuktuk_read_messages: прочитать переписку целиком, а не последнее сообщение.
4. tuktuk_pause_assistant: если в диалоге работает ИИ-ассистент, заберите диалог себе, иначе клиент получит два ответа.
5. tuktuk_send_message: ответить.

# 2. Найти контакт
curl -s "https://back.tuk-tuk.online/api/v1/contacts?phone=%2B79991234567" -H "Authorization: Bearer $TUK_KEY"

# 3. Прочитать историю (свежие сверху)
curl -s "https://back.tuk-tuk.online/api/v1/contacts/$DIALOG/messages?limit=30" -H "Authorization: Bearer $TUK_KEY"

# 4. Забрать диалог у ассистента
curl -s -X POST https://back.tuk-tuk.online/api/v1/assistants/pause-dialog \
  -H "Authorization: Bearer $TUK_KEY" -H "Content-Type: application/json" \
  -d '{"dialogId":"'$DIALOG'","minutes":60}'

# 5. Ответить
curl -s -X POST https://back.tuk-tuk.online/api/v1/messages \
  -H "Authorization: Bearer $TUK_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-$DIALOG-1" \
  -d '{"dialogId":"'$DIALOG'","text":"Здравствуйте! Записал вас на четверг, 15:00."}'

#Сценарий 2. Написать первым

Адресат задаётся одним из четырёх способов: dialogId, phone, email, identifier. Во всех случаях, кроме dialogId, нужен channelId, чтобы платформа знала, откуда писать.

curl -s -X POST https://back.tuk-tuk.online/api/v1/messages \
  -H "Authorization: Bearer $TUK_KEY" -H "Content-Type: application/json" \
  -d '{"channelId":"'$CHANNEL'","phone":"+79991234567","name":"Иван","text":"Ваш заказ готов"}'

Контакта ещё нет? Он заведётся сам, имя возьмётся из поля name. Инструмент MCP тот же: tuktuk_send_message.

#Сценарий 3. Рассылка по сегменту

Порядок обязателен: сначала посчитать аудиторию, потом создать, потом запустить.

1. tuktuk_preview_audience: сколько человек попадёт под фильтр.
2. tuktuk_create_broadcast: черновик с текстом, темпом и окном отправки.
3. tuktuk_start_broadcast: запуск.
4. tuktuk_broadcast_report: кто получил, кто нет и почему.

# 1. Сколько получателей
curl -s -X POST https://back.tuk-tuk.online/api/v1/broadcasts/preview \
  -H "Authorization: Bearer $TUK_KEY" -H "Content-Type: application/json" \
  -d '{"audience":{"tags":["клиент"],"activeWithinDays":90}}'

# 2-3. Создать и запустить
BID=$(curl -s -X POST https://back.tuk-tuk.online/api/v1/broadcasts -H "Authorization: Bearer $TUK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Сентябрьская акция","text":"Скидка 20% до пятницы","audience":{"tags":["клиент"]},"delayMinSec":20,"delayMaxSec":60}' | jq -r .id)
curl -s -X POST https://back.tuk-tuk.online/api/v1/broadcasts/$BID/start -H "Authorization: Bearer $TUK_KEY"

Завершённую рассылку не перезапускают: duplicate делает копию, иначе получившие однажды получат второй раз. Темп и окно берегут аккаунт от блокировки в мессенджере, подробности.

#Сценарий 4. Узнавать о входящих без поллинга

Платформа сама постучится на ваш адрес. Поллинг /contacts/{id}/messages в цикле даёт лишние запросы и задержку.

curl -s -X POST https://back.tuk-tuk.online/api/v1/events/subscriptions \
  -H "Authorization: Bearer $TUK_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/tuktuk","events":["message.inbound","dialog.created"]}'

В ответе придёт secret, он показывается один раз. Каждый запрос подписан заголовком X-Webhook-Signature (HMAC-SHA256 от тела):

import { createHmac, timingSafeEqual } from 'node:crypto';

function valid(rawBody, signature, secret) {
  const mine = createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(mine), b = Buffer.from(signature ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}

Полный список событий и формат тела: Event Webhooks. История доставок и повторы лежат в GET /events/subscriptions/{id}/deliveries.

#Сценарий 5. Отложенное действие

Агент живёт один ход, а напомнить нужно завтра. Отдайте время платформе.

curl -s -X POST https://back.tuk-tuk.online/api/v1/messages/schedule \
  -H "Authorization: Bearer $TUK_KEY" -H "Content-Type: application/json" \
  -d '{"dialogId":"'$DIALOG'","text":"Напоминаю о встрече в 15:00","sendAt":"2026-09-20T09:00:00Z"}'

Минимум 30 секунд вперёд. Очередь показывает tuktuk_list_scheduled, отменяет tuktuk_cancel_scheduled.

#Сценарий 6. Автоответчик без единого клика

Связки отвечают на входящие по сценарию: ветвления, задержки, ИИ, вебхуки.

1. tuktuk_chain_templates: готовые шаблоны.
2. tuktuk_create_chain_from_template: создать по шаблону.
3. tuktuk_toggle_chain: включить.

Своя схема собирается через POST /chains с массивом блоков; справочник 18 типов блоков отдаёт GET /chains/block-types, человеческое описание лежит в разделе Цепочки.

#Правила, которые берегут деньги и репутацию

#Что по API нельзя и где это делается руками

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

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

#Коды ответов, которые стоит обрабатывать

Полный перечень ошибок и тела ответов: REST API v1.