Developer Guide

This guide describes the data model and API for Pinned Messages in Deepdesk Agent Assist.

Data Model

PinnedMessage

Field	Type	Required	Description
id	string	Yes	Unique identifier for the pinned message
image	string | null	Yes	URL of an optional image associated with the message
image_sizes	object | null	Yes	Dictionary of image URLs keyed by size (e.g., small, large)
position	integer	Yes	Display order; lower numbers appear first
message	string	Yes	The full message text shown to agents and sent to customers
title	string	Yes	Short label for quick identification in the agent interface

Schema Definition:

class PinnedMessage(BaseModel):
    id: str
    image: str | None
    image_sizes: dict[str, str] | None
    position: int
    message: str
    title: str

API Reference

Get Pinned Messages

Retrieves all active pinned messages for a specific profile.

GET /api/v2/profiles/{profile_code}/pinned-messages

Path Parameters

Parameter	Type	Required	Description
profile_code	string	Yes	The unique code identifying the profile

Authentication

This endpoint requires one of the following authentication methods:

• OAuth2 with pinned-messages:read scope
• Bearer token (HTTPBearer)
• API Key Cookie (access_token_cookie)

Response

Returns an array of PinnedMessage objects.

Success Response (200 OK):

[
  {
    "id": "pm_12345",
    "image": "https://cdn.example.com/images/notice.png",
    "image_sizes": {
      "small": "https://cdn.example.com/images/notice_sm.png",
      "large": "https://cdn.example.com/images/notice_lg.png"
    },
    "position": 1,
    "message": "Due to scheduled maintenance, our systems will be unavailable from 2:00 AM to 4:00 AM EST tonight.",
    "title": "Scheduled Maintenance"
  },
  {
    "id": "pm_12346",
    "image": null,
    "image_sizes": null,
    "position": 2,
    "message": "Thank you for contacting us! Our current response time is approximately 5 minutes.",
    "title": "Response Time Notice"
  }
]

Error Response (422 Validation Error):

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

Example Request

curl -X GET "https://api.deepdesk.com/api/v2/profiles/my-profile/pinned-messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Integration

How Pinned Messages Are Displayed

The frontend retrieves pinned messages from the backend and displays them alongside regular AI recommendations in all supported platform integrations. Pinned messages typically appear at the top of the suggestion list, ordered by their position field.

Lifecycle

1. Creation: Administrators create pinned messages through the management interface
2. Activation: Messages are immediately available to agents upon creation
3. Ordering: The position field determines display order (ascending)
4. Deactivation: When no longer needed, messages are disabled and removed from the agent interface

info

Pinned Messages are designed for rapid deployment and removal to support dynamic operational needs such as service outages, promotions, or policy updates.

OAuth2 Scopes

Scope	Description
pinned-messages:read	Read access to pinned messages
pinned-messages:write	Write access to pinned messages (for management APIs)

---

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