---
title: "Сценарии для агента и разработчика: от ключа до ответа клиенту | tuk-tuk.online"
nav_title: "Сценарии для агента"
url: https://docs.tuk-tuk.online/api/recipes
markdown: https://docs.tuk-tuk.online/api/recipes.md
section: "API для разработчиков"
description: "Готовые сценарии работы с API tuk-tuk.online: ответить клиенту, написать первым, собрать рассылку, подписаться на входящие, поставить отложенное сообщение, включить автоответчик. Каждый шаг двумя способами: инструмент MCP и curl."
keywords: ["API сценарии", "MCP примеры", "отправить сообщение API", "рассылка API", "вебхук входящих", "отложенное сообщение", "нейросеть в мессенджерах", "агент tuktuk", "cookbook API"]
lang: ru
product: tuk-tuk.online
app: https://lk.tuk-tuk.online
api_base: https://back.tuk-tuk.online
---

> [!AI] Кратко
> Пошаговые сценарии работы с API tuk-tuk.online для ИИ-агентов и разработчиков: ответить клиенту, написать первым, рассылка по сегменту, подписка на входящие события, отложенное сообщение, автоответчик на связках. Каждый шаг показан инструментом MCP и запросом curl.
>
> - Порядок для ответа клиенту: manifest → список каналов → поиск контакта → чтение истории → пауза ассистента → отправка.
> - Адресат сообщения: dialogId, либо phone/email/identifier вместе с channelId.
> - Рассылка: preview аудитории → создание черновика → start; завершённую копируют через duplicate, а не перезапускают.
> - Входящие получают подпиской на события (HMAC-SHA256 в X-Signature), а не поллингом.
> - Отложенная отправка: POST /messages/schedule, минимум 30 секунд вперёд.
> - По API нельзя: подключать каналы, выпускать ключи, платить, управлять правами: это делает человек в кабинете.
> - Ошибки: 401 ключ, 403 нет scope, 404 чужой объект, 422 отправка невозможна, 429 лимит ключа.
>
> Связанные страницы: https://docs.tuk-tuk.online/api/reference, https://docs.tuk-tuk.online/api/mcp-tools, https://docs.tuk-tuk.online/api/agents, https://docs.tuk-tuk.online/api/rest, https://docs.tuk-tuk.online/api/webhooks

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

Шесть законченных сценариев: от пустого ключа до ответа клиенту. Каждый шаг показан дважды: инструментом MCP (так делает нейросеть) и запросом curl (так делает ваш сервер). Справочник всех адресов: [эндпоинты](https://docs.tuk-tuk.online/api/reference) и [инструменты](https://docs.tuk-tuk.online/api/mcp-tools).

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

| Шаг | Где делается | Зачем |
|---|---|---|
| Выпустить ключ `tuk_sk_…` | Кабинет → [Настройки проекта → API](https://lk.tuk-tuk.online/settings) | Ключ нельзя выпустить по API: ключ, умеющий выпускать ключи, обесценивает права |
| Выдать ключу права | Там же, галочки scopes | Лишнее право повышает риск, начните с `messengers:read`, `contacts:read`, `messages:read`, `messages:send` |
| Подключить канал | Кабинет → [Каналы связи](https://lk.tuk-tuk.online/channels) | Пока только руками: OAuth-каналам нужен браузер, а токен бота нельзя присылать чужому агенту |
| Подключить MCP | Конфиг вашего клиента, [строка подключения](https://docs.tuk-tuk.online/api/mcp-tools) | Нейросеть увидит инструменты по правам ключа |

> [!TIP] Первое, что стоит вызвать после подключения, это `tuktuk_manifest` (`GET /manifest`). Он покажет, что доступно именно этому ключу, и дальше не придётся угадывать.

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

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

1. `tuktuk_list_channels`: через какой канал вообще можно говорить.
2. `tuktuk_find_contact` по телефону, email или имени: получить `dialogId`.
3. `tuktuk_read_messages`: прочитать переписку целиком, а не последнее сообщение.
4. `tuktuk_pause_assistant`: если в диалоге работает [ИИ-ассистент](https://docs.tuk-tuk.online/ai/assistants), заберите диалог себе, иначе клиент получит два ответа.
5. `tuktuk_send_message`: ответить.

```bash
# 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`, чтобы платформа знала, откуда писать.

```bash
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`.

> [!WARNING] Написать первым разрешает не платформа, а сам мессенджер. Telegram-бот не может начать диалог с тем, кто ему не писал; SMS и email могут. Тип канала виден в `GET /messengers` в поле `type`.

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

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

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

```bash
# 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` делает копию, иначе получившие однажды получат второй раз. Темп и окно берегут аккаунт от блокировки в мессенджере, [подробности](https://docs.tuk-tuk.online/broadcasts).

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

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

```bash
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 от тела):

```javascript
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](https://docs.tuk-tuk.online/api/webhooks). История доставок и повторы лежат в `GET /events/subscriptions/{id}/deliveries`.

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

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

```bash
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`, человеческое описание лежит в разделе [Цепочки](https://docs.tuk-tuk.online/chains).

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

| Правило | Почему |
|---|---|
| `Idempotency-Key` на каждой отправке | Обрыв связи и ретрай не должны отправить второе сообщение. Ключ живёт сутки |
| Проверяйте `canSend` в `GET /account` | При нулевом балансе и истёкшем тарифе отправка не пройдёт, причина в `blockedReason` |
| Ставьте ассистента на паузу, если ведёте диалог сами | Иначе клиент получит два ответа на один вопрос |
| Уважайте `transactional` в email | Служебное письмо (чек, код, доступ) проходит отписавшемуся, рекламное не проходит: отправка вернёт 422 |
| Читайте историю перед ответом | Клиент уже мог написать то, что вы собираетесь спросить |

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

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

| Действие | Где делает человек |
|---|---|
| Подключить или отключить канал | [Каналы связи](https://lk.tuk-tuk.online/channels) |
| Выпустить, изменить, отозвать ключ API | [Настройки проекта → API](https://lk.tuk-tuk.online/settings) |
| Пополнить баланс, сменить тариф | [Баланс](https://lk.tuk-tuk.online/balance) |
| Пригласить сотрудника, выдать права | [Пользователи](https://lk.tuk-tuk.online/users) |

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

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

| Код | Значение | Что делать |
|---|---|---|
| `401` | Ключ неверен или отозван | Остановиться, попросить новый ключ |
| `403` | Нет права (scope) | Показать человеку, какое право добавить в кабинете |
| `404` | Объекта нет или он чужой | Не повторять запрос |
| `422` | Запрос принят, но отправить нельзя | Прочитать `message`: отписка, пустой баланс, неподходящий канал |
| `429` | Лимит запросов ключа | Подождать, затем повторить |

Полный перечень ошибок и тела ответов: [REST API v1](https://docs.tuk-tuk.online/api/rest).