Policies

Policies define rules, constraints, and procedures that govern how the assistant behaves. Unlike knowledge base entries (which answer factual questions), policies establish behavioural guidelines: escalation triggers, verification steps, response constraints, and business rules.

Required scope: policy:read for GET endpoints, policy:write for write endpoints.

List entries

Retrieve all policy entries for a workspace. The response is a bare JSON array.

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/policy-entries" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

[
  {
    "id": "11223344-5566-4788-99aa-bbccddeeff00",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "topic": "escalation",
    "ruleText": "If the customer mentions legal action, litigation, or a lawyer, immediately flag the conversation for human review and do not attempt to resolve the issue autonomously.",
    "conditions": {
      "keywords": ["legal action", "litigation", "lawyer", "court"]
    },
    "sourceType": "manual",
    "status": "approved",
    "confidence": null,
    "createdAt": "2026-01-10T09:00:00.000Z",
    "updatedAt": "2026-01-10T09:00:00.000Z"
  }
]

Search entries

Search policy entries by semantic similarity. The response is a bare JSON array.

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/policy-entries/search?q=when%20to%20escalate" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

Parameter	Type	Required	Description
q	string	Yes	Search query. An empty query returns an empty array.

Response:

[
  {
    "id": "11223344-5566-4788-99aa-bbccddeeff00",
    "topic": "escalation",
    "ruleText": "If the customer mentions legal action, litigation, or a lawyer, immediately flag the conversation for human review and do not attempt to resolve the issue autonomously.",
    "conditions": {
      "keywords": ["legal action", "litigation", "lawyer", "court"]
    },
    "status": "approved"
  }
]

List pending entries

Retrieve policy entries awaiting human review. The response is a bare JSON array.

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/policy-entries/pending" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

[
  {
    "id": "aabbccdd-eeff-4788-9233-445566778899",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "topic": "order-verification",
    "ruleText": "Before looking up order details, always ask the customer to confirm their order number. Do not search by name or email alone.",
    "conditions": null,
    "sourceType": "extracted",
    "sourceConversationId": "c9f8e7d6-b5a4-3210-fedc-ba9876543210",
    "status": "pending_review",
    "confidence": 0.72,
    "createdAt": "2026-03-14T16:30:00.000Z",
    "updatedAt": "2026-03-14T16:30:00.000Z"
  }
]

Create entry

Create a new policy entry. Entries created via the API are set to approved status by default.

Required scope: policy:write

curl -X POST "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/policy-entries" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "pricing",
    "ruleText": "Never disclose wholesale pricing or volume discount tiers to end customers. If asked about bulk pricing, direct them to their account manager.",
    "sourceType": "manual",
    "conditions": {
      "accountTypes": ["end_customer"]
    }
  }'

Request body:

Field	Type	Required	Description
topic	string	Yes	Topic category for the policy
ruleText	string	Yes	The rule or instruction text
sourceType	string	Yes	Origin of the entry, e.g. "manual"
conditions	object	No	Optional structured conditions for contextual matching
sourceConversationId	string	No	The conversation this entry was derived from
confidence	number	No	A score between 0.0 and 1.0

Response:

{
  "id": "ffeeddcc-bbaa-4788-9776-554433221100",
  "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "topic": "pricing",
  "ruleText": "Never disclose wholesale pricing or volume discount tiers to end customers. If asked about bulk pricing, direct them to their account manager.",
  "conditions": {
    "accountTypes": ["end_customer"]
  },
  "sourceType": "manual",
  "status": "approved",
  "confidence": null,
  "createdAt": "2026-03-15T15:30:00.000Z",
  "updatedAt": "2026-03-15T15:30:00.000Z"
}

Update entry

Update an existing policy entry. Only the fields you include are changed.

Required scope: policy:write

curl -X PATCH "https://api.ohallo.eu/api/policy-entries/ffeeddcc-bbaa-4788-7766-554433221100" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "ruleText": "Never disclose wholesale pricing, volume discount tiers, or partner-specific rates to end customers. If asked about bulk pricing, direct them to their account manager or provide the general inquiry form link."
  }'

Response: Returns the full updated entry.

Approve entry

Approve a pending policy entry, making it active for the assistant.

Required scope: policy:write

curl -X POST "https://api.ohallo.eu/api/policy-entries/aabbccdd-eeff-4788-2233-445566778899/approve" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Reject entry

Reject a pending policy entry. Optionally include a reason.

Required scope: policy:write

curl -X POST "https://api.ohallo.eu/api/policy-entries/aabbccdd-eeff-4788-2233-445566778899/reject" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "This is too restrictive; we do allow order lookups by email for verified accounts."
  }'

Delete entry

Permanently delete a policy entry.

Required scope: policy:write

curl -X DELETE "https://api.ohallo.eu/api/policy-entries/ffeeddcc-bbaa-4788-7766-554433221100" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response: 200 OK with { "ok": true } on success.

Policy structure

Each policy entry has three key fields:

topic: A category string that groups related policies. The Policy Agent retrieves policies by topic based on the conversation’s classified intents. Examples: escalation, pricing, returns, verification, tone.

ruleText: The actual rule or instruction, written in natural language. Be specific and actionable. The assistant interprets this text literally, so avoid ambiguity.

conditions: Optional structured data for contextual matching. Conditions are free-form JSON and can represent any filtering criteria relevant to your business logic. The Policy Agent uses conditions to determine whether a policy applies to the current conversation context.

Effective policy writing

Good policies are specific, actionable, and testable:

Topic: returns
Rule: Accept return requests for items delivered within the last 30 days.
      Require the order number and reason for return. If the item is
      damaged, request a photo before processing.

Avoid vague policies that the assistant cannot act on consistently:

Topic: general
Rule: Be helpful and try to resolve issues.