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. |
回包
200OK —application/json·DataResponseBatchAgentDMEligibilityResultBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·GetPolicyResponseBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·UpdateAgentPolicyResponseBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·GetPolicyChangeResponseBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·SetGroupAllowFromResponseBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·SetGroupModeResponseBodydefaultError —application/problem+json·D8Error
