Һәр тышкы кулланучыга бер диалог
Диалог ике нәрсә белән билгеләнә: API ачкычы һәм сез җибәргәнexternal_user_id. Сез диалогны беркайчан да үзегез ясамыйсыз; яңа external_user_id өчен беренче чат соравы аны ясый, ә шул ук тышкы кулланучыдан шул ук ачкыч аша килгән һәр соңгы хәбәр аны дәвам итә.
Белергә кирәкле нәтиҗәләр:
- Ачкыч буенча аерымлык. Ике төрле ачкыч аша килгән бер үк
external_user_id— ике төрле диалог, хәтта ике ачкыч та бер агентныкы булса да. Ачкыч башка ачкычның яки башка каналның (Telegram, виджет һ.б.) диалогларын беркайчан күрми. - Яңарту тарихны саклый. Ачкычны яңарту аның серен үзгәртә, идентификаторын түгел, шуңа күрә диалоглары аңа беркетелгән килеш кала.
external_user_id— сезнеке. Үз системагыздан 1-255 символлы тотрыклы идентификатор кулланыгыз. Аңа диалог янында сакланырга тиеш булмаган шәхси мәгълүматны салмагыз.- Бер вакытта бер җавап. Алдагы җавап әле ясалып торганда тышкы кулланучы өчен хәбәр килсә, API
Retry-After: 2белән409 conversation_busyҗавабын бирә. Көтегез һәм яңадан җибәрегез.
Диалоглар исемлеге
GET /v1/agents/{agent_id}/conversations ачкычның диалогларын кайтара, иң соңгы яңартылганнары башта. Аны read-only һәм full ачкычлар да чакыра ала.
last_message_preview — 160 символга кадәр кыскартылган соңгы кулланучы яки ассистент тексты, яки буш диалог өчен null.
Хәбәрләрне уку
GET /v1/agents/{agent_id}/conversations/{conversation_id}/messages бер диалогның хәбәрләрен кайтара, иң яңалары башта. user һәм assistant хәбәрләре генә кайтарыла; кораллар белән алмашулар, корал эшчәнлеге язмалары һәм система промпты беркайчан да ачылмый.
Һәр хәбәрдә
id, role (user яки assistant), type (text, image, file, …), content (текст; текст булмаган эчтәлек тексты яки исеме белән бирелә) һәм created_at бар.
Башка ачкычка яки каналга караган, яисә бөтенләй булмаган диалог идентификаторы — 404 conversation_not_found. API бу ике очракны аермый.
Битләү
Һәр исемлек —{"data": [...], "next_cursor": "..." | null}. Киләсе битне алу өчен next_cursor кыйммәтен cursor буларак кире җибәрегез һәм ул null булганда туктагыз. Курсорлар ябык (opaque); дөрес булмаган курсор — 422 validation_error.
Даталар
Даталар — ISO-8601. Вакыт поясы күрсәтелгән кыйммәтләр UTC-га күчерелә, күрсәтелмәгәннәре UTC дип укыла, әdate_to керми (эксклюзив). date_from кыйммәтеннән иртәрәк date_to — 422 validation_error.