Як муколама барои ҳар корбари беруна
Муколама бо ду чиз муайян мешавад: калиди API ваexternal_user_id, ки шумо мефиристед. Шумо ҳеҷ гоҳ муколамаро ба таври возеҳ намесозед; аввалин дархости чат барои external_user_id-и нав онро месозад ва ҳар паёми минбаъда аз ҳамон корбари беруна тавассути ҳамон калид онро идома медиҳад.
Оқибатҳое, ки донистан лозим аст:
- Ҷудокунӣ аз рӯи калид. Ҳамон
external_user_id, ки тавассути ду калиди гуногун мерасад, ду муколамаи гуногун аст, ҳатто вақте ки ҳарду калид ба ҳамон агент тааллуқ доранд. Калид ҳеҷ гоҳ муколамаҳои калиди дигар ё канали дигарро (Telegram, виҷет ва ғайра) намебинад. - Навсозӣ таърихро нигоҳ медорад. Навсозии калид махфии онро тағйир медиҳад, на идентификатори онро, бинобар ин муколамаҳои он пайваста мемонанд.
external_user_idаз они шумост. Идентификатори устувори системаи худро истифода баред, 1-255 аломат. Ба он маълумоти шахсиеро нагузоред, ки намехоҳед дар паҳлӯи муколама нигоҳ дошта шавад.- Як ҷавоб дар як вақт. Агар паём барои корбари беруна ҳангоми тавлиди ҷавоби пешина расад, API
409 conversation_busyбоRetry-After: 2ҷавоб медиҳад. Интизор шавед ва аз нав фиристед.
Рӯйхати муколамаҳо
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 бармегарданд; мубодилаи абзорҳо, сатрҳои фаъолияти абзорҳо ва system prompt ҳеҷ гоҳ ошкор намешаванд.
Ҳар паём
id, role (user ё assistant), type (text, image, file, …), content (матн; муҳтавои ғайриматнӣ ҳамчун матн ё номи он нишон дода мешавад) ва created_at дорад.
Идентификатори муколамае, ки ба калид ё канали дигар тааллуқ дорад ё вуҷуд надорад, 404 conversation_not_found аст. API ин ду ҳолатро фарқ намекунад.
Саҳифабандӣ
Ҳар рӯйхат{"data": [...], "next_cursor": "..." | null} аст. next_cursor-ро ҳамчун cursor баргардонед, то саҳифаи навбатиро гиред, ва вақте ки он null мешавад, қатъ кунед. Курсорҳо норавшананд; курсори нодуруст 422 validation_error аст.
Санаҳо
Санаҳо ISO-8601 мебошанд. Қиматҳои дорои минтақаи вақт ба UTC табдил мешаванд, қиматҳои бе минтақаи вақт ҳамчун UTC хонда мешаванд, ваdate_to истисноӣ аст. date_to, ки аз date_from пештар аст, 422 validation_error аст.