Assistant · مرجع الواجهة البرمجية

10 نقاط وصول. أسماء نقاط الوصول وأوصافها مأخوذة من ملف OpenAPI، لذلك تظهر بالإنجليزية.

POST /v1/assistant/chat
GET /v1/assistant/widget
GET /v1/assistant/settings
PUT /v1/assistant/settings
GET /v1/assistant/conversations
GET /v1/assistant/conversations/{conversation_id}
GET /v1/assistant/knowledge
POST /v1/assistant/knowledge
PUT /v1/assistant/knowledge/{doc_id}
DELETE /v1/assistant/knowledge/{doc_id}

POST/v1/assistant/chat

Shopping assistant (public key with the `assistant` scope)

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

جسم الطلب `application/json` `ChatRequest`

الاسم	النوع	إلزامي	الوصف
`conversation_id`	`string \| null`	لا	Omit to start a new conversation.
`message`	`string`	نعم	min length 1 · max length 2000
`locale`	`string`	لا	default "ar" · pattern ^[a-z]{2}$
`session`	`string \| null`	لا	max length 64
`context`	`map<string, string>`	لا	e.g. current product id or category page.
`stream`	`boolean`	لا	true = text/event-stream of ChatEvent objects.default false

الردود

200JSON, or SSE when stream=trueChatResponse

GET/v1/assistant/widget

Chat widget setup: on/off, white-label name, greeting (public key with the `assistant` scope)

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`locale`	`query`	`string`	لا	default "ar" · pattern ^[a-z]{2}$

الردود

200Successful ResponseAssistantWidgetConfig

GET/v1/assistant/settings

Assistant Settings Get

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

الردود

200Successful ResponseAssistantSettings-Output

PUT/v1/assistant/settings

Assistant Settings Put

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

جسم الطلب `application/json` `AssistantSettings-Input`

الاسم	النوع	إلزامي	الوصف
`enabled`	`boolean`	لا	default false
`display_name`	`string`	لا	White-label name, e.g. "Ask Store".max length 60
`tone`	`"friendly" \| "formal" \| "brief"`	لا	default "friendly"
`locales`	`string[]`	لا
`handover`	`map<string, string>`	لا	whatsapp/phone/email targets.
`monthly_budget_usd`	`number \| string \| null`	لا	Optional cap for the assistant INSIDE the store's total monthly AI budget (ADR 0006). When it is used up only the assistant stops; search and translation go on.min 0
`greeting`	`map<string, string>`	لا

الردود

200Successful ResponseAssistantSettings-Output

GET/v1/assistant/conversations

Assistant Conversations List

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`cursor`	`query`	`string \| null`	لا	max length 200
`limit`	`query`	`integer`	لا	default 50 · min 1 · max 200

الردود

200Successful ResponsePage_ConversationSummary_

GET/v1/assistant/conversations/{conversation_id}

Assistant Conversations Get

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`conversation_id`	`path`	`string`	نعم

الردود

200Successful ResponseConversationDetail

GET/v1/assistant/knowledge

Store FAQ and policies the assistant may use

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`cursor`	`query`	`string \| null`	لا	max length 200
`limit`	`query`	`integer`	لا	default 100 · min 1 · max 200

الردود

200Successful ResponsePage_KnowledgeDocOut_

POST/v1/assistant/knowledge

Knowledge Create

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

جسم الطلب `application/json` `KnowledgeDocIn`

الاسم	النوع	إلزامي	الوصف
`kind`	`"faq" \| "policy" \| "page"`	نعم
`locale`	`string`	نعم	pattern ^[a-z]{2}$
`title`	`string`	نعم	max length 300
`content`	`string`	نعم	max length 50000
`url`	`string \| null`	لا	max length 2048

الردود

201Successful ResponseKnowledgeDocOut

PUT/v1/assistant/knowledge/{doc_id}

Knowledge Update

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`doc_id`	`path`	`string`	نعم

جسم الطلب `application/json` `KnowledgeDocIn`

الاسم	النوع	إلزامي	الوصف
`kind`	`"faq" \| "policy" \| "page"`	نعم
`locale`	`string`	نعم	pattern ^[a-z]{2}$
`title`	`string`	نعم	max length 300
`content`	`string`	نعم	max length 50000
`url`	`string \| null`	لا	max length 2048

الردود

200Successful ResponseKnowledgeDocOut

DELETE/v1/assistant/knowledge/{doc_id}

Knowledge Delete

يحتاج إلى مفتاح أو جلسة في لوحة التحكم

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`doc_id`	`path`	`string`	نعم

الردود

200Successful ResponseDeleted

أشكال البيانات في هذه الصفحة

ChatRequest

الاسم	النوع	إلزامي	الوصف
`conversation_id`	`string \| null`	لا	Omit to start a new conversation.
`message`	`string`	نعم	min length 1 · max length 2000
`locale`	`string`	لا	default "ar" · pattern ^[a-z]{2}$
`session`	`string \| null`	لا	max length 64
`context`	`map<string, string>`	لا	e.g. current product id or category page.
`stream`	`boolean`	لا	true = text/event-stream of ChatEvent objects.default false

ChatResponse

الاسم	النوع	إلزامي	الوصف
`conversation_id`	`string`	نعم
`message_id`	`string`	نعم
`answer`	`string`	نعم
`products`	`ProductCard[]`	لا	Live prices and stock from the index.
`comparison`	`object \| null`	لا	Table when comparing 2-4 products.
`sources`	`Source[]`	لا
`follow_up_questions`	`string[]`	لا
`handover`	`Handover \| null`	لا
`refused`	`"off_topic" \| "injection" \| "budget" \| "unavailable" \| null`	لا

ProductCard

Display fields. Connectors that render their own cards use only `id`.

الاسم	النوع	إلزامي
`id`	`string`	نعم
`name`	`map<string, string>`	نعم
`url`	`string \| null`	لا
`image_url`	`string \| null`	لا
`price`	`string`	نعم
`sale_price`	`string \| null`	لا
`currency`	`string`	نعم
`in_stock`	`boolean`	نعم
`brand`	`string \| null`	لا
`category`	`map<string, string> \| null`	لا

Source

الاسم	النوع	إلزامي	الوصف
`type`	`"product" \| "faq" \| "policy" \| "page"`	نعم
`id`	`string`	نعم
`title`	`string \| null`	لا
`fields`	`string[]`	لا	Catalog fields the answer used (price, size, ...).

Handover

الاسم	النوع	إلزامي
`channel`	`"whatsapp" \| "phone" \| "email"`	نعم
`url`	`string \| null`	لا
`summary`	`string`	نعم

AssistantWidgetConfig

What the shopper-side chat widget needs (public key, `assistant` scope). No budget, no targets.

الاسم	النوع	إلزامي	الوصف
`enabled`	`boolean`	نعم	false: the widget hides the chat button.
`display_name`	`string`	نعم	White-label name, e.g. "Ask Store" (default "Ask <store name>").
`greeting`	`string`	نعم
`locale`	`string`	نعم
`handover_channels`	`"whatsapp" \| "phone" \| "email"[]`	لا

AssistantSettings-Output

الاسم	النوع	إلزامي	الوصف
`enabled`	`boolean`	لا	default false
`display_name`	`string`	لا	White-label name, e.g. "Ask Store".max length 60
`tone`	`"friendly" \| "formal" \| "brief"`	لا	default "friendly"
`locales`	`string[]`	لا
`handover`	`map<string, string>`	لا	whatsapp/phone/email targets.
`monthly_budget_usd`	`string \| null`	لا	Optional cap for the assistant INSIDE the store's total monthly AI budget (ADR 0006). When it is used up only the assistant stops; search and translation go on.
`greeting`	`map<string, string>`	لا

AssistantSettings-Input

الاسم	النوع	إلزامي	الوصف
`enabled`	`boolean`	لا	default false
`display_name`	`string`	لا	White-label name, e.g. "Ask Store".max length 60
`tone`	`"friendly" \| "formal" \| "brief"`	لا	default "friendly"
`locales`	`string[]`	لا
`handover`	`map<string, string>`	لا	whatsapp/phone/email targets.
`monthly_budget_usd`	`number \| string \| null`	لا	Optional cap for the assistant INSIDE the store's total monthly AI budget (ADR 0006). When it is used up only the assistant stops; search and translation go on.min 0
`greeting`	`map<string, string>`	لا

Page_ConversationSummary_

الاسم	النوع	إلزامي	الوصف
`data`	`ConversationSummary[]`	نعم
`next_cursor`	`string \| null`	لا
`total`	`integer \| null`	لا	Present when cheap to count.

ConversationSummary

الاسم	النوع	إلزامي
`id`	`string`	نعم
`locale`	`string`	نعم
`started_at`	`string (date-time)`	نعم
`message_count`	`integer`	نعم
`handover`	`string`	نعم
`clicked`	`boolean`	نعم
`cost_usd`	`string`	نعم

ConversationDetail

الاسم	النوع	إلزامي
`id`	`string`	نعم
`locale`	`string`	نعم
`started_at`	`string (date-time)`	نعم
`message_count`	`integer`	نعم
`handover`	`string`	نعم
`clicked`	`boolean`	نعم
`cost_usd`	`string`	نعم
`messages`	`ConversationMessage[]`	نعم
`summary`	`string \| null`	لا

ConversationMessage

الاسم	النوع	إلزامي
`id`	`string`	نعم
`role`	`"user" \| "assistant"`	نعم
`content`	`string`	نعم
`sources`	`Source[]`	لا
`product_ids`	`string[]`	لا
`flagged`	`string \| null`	لا
`created_at`	`string (date-time)`	نعم

Page_KnowledgeDocOut_

الاسم	النوع	إلزامي	الوصف
`data`	`KnowledgeDocOut[]`	نعم
`next_cursor`	`string \| null`	لا
`total`	`integer \| null`	لا	Present when cheap to count.

KnowledgeDocOut

الاسم	النوع	إلزامي	الوصف
`kind`	`"faq" \| "policy" \| "page"`	نعم
`locale`	`string`	نعم	pattern ^[a-z]{2}$
`title`	`string`	نعم	max length 300
`content`	`string`	نعم	max length 50000
`url`	`string \| null`	لا	max length 2048
`id`	`string`	نعم
`updated_at`	`string (date-time)`	نعم

KnowledgeDocIn

الاسم	النوع	إلزامي	الوصف
`kind`	`"faq" \| "policy" \| "page"`	نعم
`locale`	`string`	نعم	pattern ^[a-z]{2}$
`title`	`string`	نعم	max length 300
`content`	`string`	نعم	max length 50000
`url`	`string \| null`	لا	max length 2048

Deleted

الاسم	النوع	إلزامي	الوصف
`deleted`	`boolean`	لا	default true
`id`	`string`	نعم

جسم الطلب application/json ChatRequest

الردود

المعاملات

الردود

الردود

جسم الطلب application/json AssistantSettings-Input

الردود

المعاملات

الردود

المعاملات

الردود

المعاملات

الردود

جسم الطلب application/json KnowledgeDocIn

الردود

المعاملات

جسم الطلب application/json KnowledgeDocIn

الردود

المعاملات

الردود

أشكال البيانات في هذه الصفحة

ChatRequest

ChatResponse

ProductCard

Source

Handover

AssistantWidgetConfig

AssistantSettings-Output

AssistantSettings-Input

Page_ConversationSummary_

ConversationSummary

ConversationDetail

ConversationMessage

Page_KnowledgeDocOut_

KnowledgeDocOut

KnowledgeDocIn

Deleted

جسم الطلب `application/json` `ChatRequest`

جسم الطلب `application/json` `AssistantSettings-Input`

جسم الطلب `application/json` `KnowledgeDocIn`

جسم الطلب `application/json` `KnowledgeDocIn`