Developer Guide

This guide describes the data model and API for Style Suggestions in Deepdesk Agent Assist.

Data Model

StyleSuggestion

The configuration model for a style suggestion rule stored in the database.

Field	Type	Required	Description
id	integer	Yes	Unique identifier for the style suggestion
title	string	Yes	Short title describing the style rule
message	string	Yes	The suggestion text shown to agents
keywords	array[string]	Yes	List of keywords or phrases that trigger this suggestion

Schema Definition:

class StyleSuggestion(BaseModel):
    id: int
    title: str
    message: str
    keywords: list[str]

KeywordMatch

Represents a detected keyword match in an agent's message.

Field	Type	Required	Description
keyword	string	Yes	The matched keyword or phrase from the message
title	string	Yes	Title of the triggered style rule
suggestion	string	Yes	The guidance text to show the agent

Schema Definition:

class KeywordMatch(BaseModel):
    keyword: str
    title: str
    suggestion: str

API Reference

Detect Style Suggestions

Detects style breaks in a message for a given profile and returns matching suggestions.

POST /api/v2/style-suggestions

Request Body

Field	Type	Required	Description
profile_code	string	Yes	The profile code to load style rules for
message	string	Yes	The agent message to analyze

Request Schema:

class StyleSuggestionRequest(BaseModel):
    profile_code: str
    message: str

Authentication

This endpoint requires one of the following authentication methods:

• OAuth2 with conversations:read scope
• Bearer token (HTTPBearer)
• API Key Cookie (access_token_cookie)

Response

Returns a StyleSuggestionResponse containing matched keywords.

Success Response (200 OK):

{
  "keyword_matches": [
    {
      "keyword": "can't",
      "title": "Avoid negative phrasing",
      "suggestion": "Try phrasing in positive terms, e.g., 'We are able to...' instead of 'We can't...'"
    }
  ]
}

Response Schema:

class StyleSuggestionResponse(BaseModel):
    keyword_matches: list[KeywordMatch]

Error Response (422 Validation Error):

{
  "detail": [
    {
      "loc": ["body", "profile_code"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Example Request

curl -X POST "https://api.deepdesk.com/api/v2/style-suggestions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_code": "retail-en",
    "message": "We can'\''t process this kind of request right now."
  }'

Architecture Overview

• Backend exposes a REST API (POST /api/v2/style-suggestions) for keyword detection
• Frontend displays style suggestions to agents and sends a "style suggested" event
• When an agent sends a message, the ingestion pipeline detects style breaks and sends a style breaks found event

Detection Logic

The style detection engine uses the following rules:

• Case-insensitive regex search
• Word boundaries are enforced so partial words do not trigger (e.g., can won't match inside candy)
• Multi-word keywords are supported; spaces in the keyword are matched with \s+ for flexible whitespace
• Quote characters in keywords are relaxed to match similar quote styles
• Template placeholders wrapped in curly braces { ... } are ignored via negative lookbehind/lookahead

Analytics

For reporting, Deepdesk tracks style suggestion usage and compliance. When the backend detects style breaks in agent messages, it emits the style breaks found event to the analytics pipeline.

Event Destinations:

Destination	Table/Dataset
ClickHouse	events table
BigQuery (deprecated)	{PROJECT}.{ACCOUNT_CODE}_analytics_dataset.events_v2

Event Payload Fields:

Field	Description
event_id	Unique event identifier
conversation_id	Associated conversation ID
profile_code	Profile code for the conversation
platform_session_id	CX platform session ID
platform	CX platform identifier
agent_*	Agent-related fields (ID, name, email)
time_utc	ISO 8601 timestamp
data	JSON string containing {"style_breaks": [{"title", "trigger"}]}

info

The event payload contains the external agent ID as received from the CX platform.

OAuth2 Scopes

Scope	Description
conversations:read	Required for detecting style suggestions

Operational Notes

• Only suggestions that are ENABLED and associated with the relevant Profile will be effective
• Curate keyword lists to minimize false positives; prefer specific phrases where possible
• For dynamic placeholders in templates, wrap them in {} to avoid matching as style breaks

---

For an overview, see the Overview. For agent usage, see the User Guide.