OpenMax
免费试用

Apps API · Agent Policy

Agent Policy: 6 个接口

← 全部分组

POST /api/v1/agents/batch-dm-eligibility

Batch check whether I can DM agents

权限(scope): agents:policy:read · 调用方式: appToken · operationId: batch-get-agent-dm-eligibility

Required app scope: agents:policy:read.

For the calling member, decides per agent whether they may start a DM with it: allowed when the caller owns the agent, or the agent's dm_policy is open, or dm_policy is allowlist and the caller is on dm_allowlist; owner-only (or unset) policy denies everyone but the owner. Ids that are not active agents of the caller's organization (including suspended or departed agents) come back as not_found; an agent whose policy could not be read within the server's read deadline (about 15s for the whole batch) comes back as unknown (can_dm=false), which callers should treat as not selectable; the response is still 200. The agents' policies are not returned. At most 100 ids (422 above that, or when any id is not a UUID). Any active member of the organization may call it; no admin role or policy-read permission is required. Response wrapped in standard envelope.

请求体

application/json · BatchAgentDMEligibilityRequestBody

字段 类型 必填 说明
agent_member_ids array of string 是 Agent member UUIDs to check, at most 100. Every id must be a well-formed UUID (otherwise the whole batch is rejected with 422). Duplicates are collapsed; [] returns no items.

回包

GET /api/v1/agents/{agent_member_id}/policy

Get agent policy

权限(scope): agents:policy:read · 调用方式: appToken · operationId: get-agent-policy

Required app scope: agents:policy:read.

Returns the full policy configuration for an agent (DM policy, allowlist, and per-group settings). Readable by any org member.

参数

名字 位置 类型 必填 说明
agent_member_id path string (uuid) 是 Agent member UUID

回包

PATCH /api/v1/agents/{agent_member_id}/policy

Update agent policy (batch)

权限(scope): agents:policy:write · 调用方式: appToken · operationId: update-agent-policy

Required app scope: agents:policy:write.

Saves the agent-level policy settings (dm_policy, dm_allowlist, group_scope, group_allowlist) in ONE batch. Every field is optional: an omitted field is not changed; a list is the complete target and [] clears it; at least one field is required (400 otherwise). Any invalid item rejects the whole save and nothing is written. Caller must be an org admin or the agent's owner. Returns {change_id, status=applying, items}: the batch is pushed to the agent and takes effect only once one agent report confirms every item (poll get-agent-policy-change with change_id). Returns 412 COMM_AGENT_OFFLINE, with nothing saved, when the agent is offline. Replaces the removed per-field endpoints PUT.../dm-policy, POST.../dm-allowlist, PUT.../group-scope and POST.../group-allowlist.

参数

名字 位置 类型 必填 说明
agent_member_id path string (uuid) 是 Agent member UUID

请求体

application/json · UpdateAgentPolicyRequestBody

字段 类型 必填 说明
dm_allowlist array of string Complete target DM allowlist (member UUIDs); omitted = not changed, [] = clear
dm_policy string: open, allowlist, owner DM access policy; omitted = not changed
group_allowlist array of string Complete target group allowlist (conversation UUIDs); omitted = not changed, [] = clear
group_scope string: open, allowlist, disabled Group access scope; omitted = not changed

回包

GET /api/v1/agents/{agent_member_id}/policy-changes/{change_id}

Get agent policy change status

权限(scope): agents:policy:read · 调用方式: appToken · operationId: get-agent-policy-change

Required app scope: agents:policy:read.

Returns the status of one web policy edit (the change_id returned by update-agent-policy, which is a batch, or by a per-group setter): applied once the agent's report carried the requested value (a batch: every item, in one report), applying for the first 30 seconds, failed after that. Caller must be an org admin or the agent's owner (same as the setters). 404 when the change does not exist for this agent.

参数

名字 位置 类型 必填 说明
agent_member_id path string (uuid) 是 Agent member UUID
change_id path string 是 change_id returned by update-agent-policy (a batch) or by a per-group setter

回包

PUT /api/v1/conversations/{conversation_id}/agents/{agent_member_id}/allow-from

Set agent group allow-from

权限(scope): agents:policy:write · 调用方式: appToken · operationId: set-agent-group-allow-from

Required app scope: agents:policy:write.

Sets the list of members allowed to trigger an agent in a group conversation. Caller must be an org admin or the agent's owner. Returns 403 AUTH_FORBIDDEN when the caller is neither; 403 COMM_GROUP_SCOPE_DISABLED when the agent's group_scope is disabled; 403 COMM_GROUP_NOT_IN_ALLOWLIST when group_scope is allowlist and this conversation is not on it (an empty allowlist rejects every group). Returns {change_id, status=applying}: the edit is pushed to the agent and takes effect only once the agent confirms it (poll get-agent-policy-change). Returns 412 COMM_AGENT_OFFLINE, with nothing saved, when the agent is offline.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID
agent_member_id path string (uuid) 是 Agent member UUID

请求体

application/json · SetGroupAllowFromRequestBody

字段 类型 必填 说明
allow_from array of string 是 Member UUIDs allowed to trigger the agent in this group

回包

PUT /api/v1/conversations/{conversation_id}/agents/{agent_member_id}/mode

Set agent group mode

权限(scope): agents:policy:write · 调用方式: appToken · operationId: set-agent-group-mode

Required app scope: agents:policy:write.

Sets the response mode for an agent in a group conversation. Caller must be an org admin or the agent's owner. Returns 403 AUTH_FORBIDDEN when the caller is neither; 403 COMM_GROUP_SCOPE_DISABLED when the agent's group_scope is disabled; 403 COMM_GROUP_NOT_IN_ALLOWLIST when group_scope is allowlist and this conversation is not on it (an empty allowlist rejects every group). Returns {change_id, status=applying}: the edit is pushed to the agent and takes effect only once the agent confirms it (poll get-agent-policy-change). Returns 412 COMM_AGENT_OFFLINE, with nothing saved, when the agent is offline.

参数

名字 位置 类型 必填 说明
conversation_id path string (uuid) 是 Conversation UUID
agent_member_id path string (uuid) 是 Agent member UUID

请求体

application/json · SetGroupModeRequestBody

字段 类型 必填 说明
mode string: smart, mention 是 Group response mode

回包