Публічний API Beta

Знаходьте розмови, що потребують уваги

Фільтруйте за awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority або tagIds. Фільтр «очікує відповіді» ігнорує внутрішні нотатки; «непрочитані» стосується конкретного автентифікованого колеги. «Не призначено» означає відсутність окремого відповідального, навіть якщо призначено команду. Теги збігаються з будь-яким переданим ID. Передайте propertyId (поле типу «Список» із list_properties) разом із propertyValues, щоб знайти контакти з будь-яким із цих варіантів; у REST повторюйте propertyValues для кожного варіанта.

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

Сортуйте за waitingSince, lastMessageAt, createdAt або бізнес-пріоритетом у напрямку asc чи desc. За однакових значень порядок визначають ID. Якщо фільтри не вказано, зберігаються compact=false і snoozed=any. У REST tagIds приймає ID через кому; MCP також приймає масив. waitingSince починається з першого вхідного повідомлення після останньої відповіді; подальші повідомлення та внутрішні нотатки його не скидають. Запускайте це сканування черги очікування за розкладом, навіть коли вебхуки не надходять, щоб старі гілки знову спливали.

Наздоганяйте зміни, не перечитуючи вхідні

Використовуйте GET /api/v1/sync з conversations:read. Надійна стрічка містить зміни розмов, теги, повідомлення, властивості контактів, спогади та записи про видалення. Кожен вміст також потребує власної області доступу на читання: тексти повідомлень — messages:read, а спогади — contact-memory:read. Облікові дані з обмеженнями отримують лише дозволені канали.

1. Почніть без курсора, переходьте за nextCursor, доки hasMore не стане false, і збережіть цей курсор.
2. Прочитайте поточні списки розмов і контактів та всю історію, потрібну для початкового стану.
3. Відтворіть зміни від збереженого курсора, щоб охопити все, що змінилося під час цього читання. Обробіть кожну сторінку, а потім збережіть nextCursor.

Усувайте дублікати за id події: доставка відбувається за принципом «щонайменше один раз», тож подальші дії потребують власного захисту від дублікатів. Запит без курсора охоплює останню годину, а не повний знімок. Події зберігаються 30 днів; HTTP 410 resync_required означає, що потрібно знову завантажити початковий стан. Робіть це також після розширення областей доступу або доступу до каналів. Використовуйте limit до 100 і maxBodyChars до 10 000 (за замовчуванням 500). Установіть compact=true, щоб отримувати поля повідомлень textPreview/textTruncated з обмеженням 200 символів замість body/bodyTruncated. Вебхуки можуть «будити» агента; стрічка залишається доступною і без підписок на вебхуки, і тоді, коли доставка вебхуків затримується.

Записуйте перевірки один раз і діліться результатом

Перш ніж повторювати дослідження, прочитайте list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Збережіть результат через record_conversation_check (PUT за тим самим шляхом), передавши key, result, checkedBy і необов’язковий reference для ID або URL картки. Наприклад: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. Sonny записує actorId автентифікованого користувача й позначку часу checkedAt. Повторне використання key замінює лише цю перевірку; це поточний стан, а не журнал історії. Читання потребує conversations:read, а запис — conversations:write, обидва в межах каналу розмови. Ці виклики не надсилають відповідь і не позначають, що продавець отримав відповідь.

Призначайте й оновлюйте роботу пакетами

Знаходьте активних колег і команди, яким можна призначати розмови, через GET /api/v1/members and /teams (members:read). Відповіді містять доступність і фактичний доступ до каналів, без адрес ел. пошти. Використовуйте conversations:write, щоб змінювати status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds або removeTagIds.

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

Розподіл по черзі (round robin) вибирає доступного учасника команди, який має доступ до каналу розмови. Якщо відповідного учасника немає, одиночне оновлення повертає 409, а елемент пакета завершується помилкою. Кожен пакет приймає до 100 унікальних ID і атомарно застосовує одне оновлення до кожної розмови. Перевіряйте кожен результат { id, ok, error? }: деякі елементи можуть завершитися помилкою. Пакети підпадають під поточний ліміт за кількістю запитів, без зваженого врахування кількості елементів.

Діліться контекстом клієнта із Sonny AI

Переглядайте, зберігайте й видаляйте спогади про контакт з contact-memory:read/write. Передавайте і contactId, і доступний sourceId; контакт повинен мати розмову в цьому джерелі. Збережені факти проходять ту саму перевірку, обробку дублікатів і обмеження, що й у застосунку, та записуються як спогади, додані вручну.

Читайте визначення властивостей на /api/v1/properties, а значення читайте чи встановлюйте на /api/v1/contacts/{contactId}/properties. MCP надає list_properties, get_contact_properties і set_contact_property. Вони потребують contacts:read/write і доступу до всіх каналів. Укажіть рівно один із propertyId або propertyName з рядковим значенням або null, щоб очистити значення. Значення типів «текст», «число», «URL», «дата» й «вибір» перевіряються за визначенням поля.

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

Фільтри властивостей шукають точний збіг збережених рядків; якщо вказано кілька властивостей, мають збігатися всі. Значення, додані через API, позначаються як дані API в Co-Pilot і автовідповідачі. Наявні правила для верифікованих клієнтів і джерел і далі діють. Звичайні значення внутрішніх полів, введені вручну, як і раніше не входять до цього контексту AI.

Читайте ті самі звіти, що й ваша команда

З reporting:read викликайте GET /api/v1/reporting/{kind}. Типи звітів: overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads і online-hours. Overview поєднує кількості, час відповіді та CSAT. Фільтри: period (1–365 днів, за замовчуванням 30), парні дати from/to (to не включається), granularity (day/month), source, assigneeId і tagId. Source приймає all, all-chat, all-email, website:{id} або email:{id}.

Звіти використовують ті самі запити, що й панель, і поточні перевірки доступу. Knowledge враховує дати й дозволені канали незалежно від вибраного джерела, відповідального чи тегу. Online hours вимірює присутність доступних колег у робочому просторі; кількість розмов у ньому й надалі обмежена каналами. Наявні ендпоінти /csat зберігають окрему область доступу csat:read і можуть описувати іншу вибірку.

Надсилайте файли з відповідями чи внутрішніми нотатками

Надайте attachments:write і завантажте для розмови файл розміром до 25 МБ. POST /api/v1/attachments приймає поля multipart file і conversationId. Відповідь містить id і expiresAt. Передайте до 10 attachmentIds у відповідь чи нотатку протягом години. Кожне завантаження прив’язане до вашого користувача й розмови та може бути використане лише один раз. Невикористані завантаження видаляються після завершення терміну дії.

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

Відповіді потребують messages:send; внутрішні нотатки потребують messages:write і ніколи не потрапляють до клієнтів. Підтримуються повідомлення лише з вкладеннями. Відповіді ел. поштою містять файли в межах ліміту розміру листа, а для решти — посилання на завантаження; листи з офлайн-чату містять посилання на файли. Посилання в листах працюють, доки існує вкладення, тож отримувачі можуть відкрити їх пізніше. Пересилання листа надає доступ до цих файлів. Перевіряйте emailDeliveryStatus, щоб виявити помилки доставки.

Авторизоване читання повідомлень містить downloadUrl, downloadExpiresAt, aiStatus, aiDescription та aiExtractedText, а також videoTranscripts для відео за посиланнями (Loom, Vimeo та інші). Посилання на завантаження діють 15 хвилин; щоб отримати нові, прочитайте повідомлення знову. Нові завантаження через API/MCP зберігаються приватно. Старіші вкладення залишаються публічними й позначаються access=legacy_public: їхня початкова URL-адреса не має терміну дії. Читання повідомлення запускає розпізнавання його зображень, якщо робочий простір має Sonny AI. Розпізнавання зображень і розшифровки відео завершуються невдовзі після надходження повідомлення: поки якісь із них ще тривають, відповідь починається з readsInProgress, де nextStep вказує точний виклик, який потрібно зробити. Передайте waitSeconds (до 30), щоб дочекатися їх в одному запиті. Повідомлення у віджеті й у реальному часі, які бачать клієнти, ніколи не містять витягнутого тексту чи розшифровок.