Skip to main content

Як муколама барои ҳар корбари беруна

Муколама бо ду чиз муайян мешавад: калиди 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 аст.