Сообщения
Сообщения
Базовая единица коммуникации для ваших агентов.
Сообщения
Базовая единица коммуникации для ваших агентов.
В экосистеме Agent Inbox Message — это представление обычного письма, ориентированное на API. Это структурированный объект со всем привычным: отправитель, получатели, тема и тело.
Каждое Message живёт внутри Thread, чтобы беседы оставались упорядоченными. При отправке нового Message создаётся новый Thread. При ответе новое Message добавляется в существующий Thread — как в обычной почтовой переписке.
В Agent Inbox удобно подключать людей к диалогам агента: в любое сообщение можно добавить реального человека в cc или bcc, чтобы построить сценарий «человек в контуре» для контроля, эскалаций или проверки качества.
С ресурсом Message можно работать по-разному: отправлять новые письма и просматривать историю переписки.
Сначала инициализируйте клиент Agent Inbox с API-ключом — через него выполняются все вызовы API.
MessageЧтобы начать новую беседу, отправьте Message из одного из ваших ящиков. Будет создан новый Thread, а в ответ вернётся объект Message.
Лимит получателей: при каждой отправке или ответе не более 50 получателей в сумме по полям to, cc и bcc. При превышении API вернёт ошибку.
Messages в InboxМожно получить список всех Messages в конкретном Inbox — удобно для истории переписки.
MessageОтвет на существующее Message добавляет новое Message в тот же Thread.
В ответе inbox_id — это ящик, с которого вы отправляете. В отличие от
сценария send, здесь нужно явно указать один из потенциально многих Inboxes.
MessageДетали конкретного Message запрашиваются по его ID вместе с inbox_id, к которому оно относится.
При получении ответов и пересылок для только нового текста используйте extracted_text или extracted_html — цитируемая история отрезается автоматически.
Скопируйте один из блоков ниже в Cursor или Claude, чтобы за один раз передать полное описание API сообщений.
При отправке Message тело можно задать в двух форматах: text — простой текст, html — разметка со стилями.
text: обычная строка без форматирования. Запасной вариант для клиентов без HTML.html: HTML-документ для оформления, цветов, шрифтов и изображений.Рекомендация: всегда отправляйте и text, и html.
Современные клиенты чаще показывают HTML, но не все умеют его рендерить — текстовый вариант гарантирует читаемость. Кроме того, это заметно улучшает доставляемость.
Чтобы стилизовать HTML в Message, встраивайте CSS в тег <style> внутри <head> тела запроса — так надёжнее для Gmail, Outlook и Apple Mail.
Пример аккуратного заголовка письма в HTML:
textПоля text и preview у входящего Message берутся из MIME-части text/plain. Некоторые клиенты — в частности Gmail и Outlook — пересылают письма только в HTML без текстовой части. Тогда text и preview могут отсутствовать.
При обработке входящих сообщений считайте основным источником html, а text — опциональным.
MessagesПериодический список Messages возможен, но для входящей почты агентам эффективнее вебхуки. Настроив endpoint, вы получаете уведомление сразу при новом Message и можете сразу реагировать.
В Agent Inbox нет отдельного endpoint «пометить прочитанным» — состояние читается через метки. Так обычно избегают повторной обработки одних и тех же писем агентом.
Если агент использует вебхуки, сразу после обработки помечайте сообщение как read (или processed). После перезапуска или повторной обработки фильтруйте по labels=["unread"], чтобы пропускать уже обработанные письма.