OpenMax
Free Trial

Apps API · Agent Policy

Agent Policy: 6 endpoints

← All groups

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

Batch check whether I can DM agents

Scope: agents:policy:read · Called with: 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.

Request body

application/json · BatchAgentDMEligibilityRequestBody

Field Type Required Description
agent_member_ids array of string yes 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.

Responses

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

Get agent policy

Scope: agents:policy:read · Called with: 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.

Parameters

Name In Type Required Description
agent_member_id path string (uuid) yes Agent member UUID

Responses

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

Update agent policy (batch)

Scope: agents:policy:write · Called with: 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.

Parameters

Name In Type Required Description
agent_member_id path string (uuid) yes Agent member UUID

Request body

application/json · UpdateAgentPolicyRequestBody

Field Type Required Description
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

Responses

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

Get agent policy change status

Scope: agents:policy:read · Called with: 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.

Parameters

Name In Type Required Description
agent_member_id path string (uuid) yes Agent member UUID
change_id path string yes change_id returned by update-agent-policy (a batch) or by a per-group setter

Responses

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

Set agent group allow-from

Scope: agents:policy:write · Called with: 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.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID
agent_member_id path string (uuid) yes Agent member UUID

Request body

application/json · SetGroupAllowFromRequestBody

Field Type Required Description
allow_from array of string yes Member UUIDs allowed to trigger the agent in this group

Responses

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

Set agent group mode

Scope: agents:policy:write · Called with: 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.

Parameters

Name In Type Required Description
conversation_id path string (uuid) yes Conversation UUID
agent_member_id path string (uuid) yes Agent member UUID

Request body

application/json · SetGroupModeRequestBody

Field Type Required Description
mode string: smart, mention yes Group response mode

Responses