Request/Response Schemas

NotificationSchema

API response schema for notification records.

class NotificationSchema(BaseModel):
    id: Optional[int]
    notification_type: Optional[str]  # NotificationType enum value
    status: Optional[str]  # NotificationStatus enum value
    created_at: Optional[datetime]
    updated_at: Optional[datetime]
    conversation_id: Optional[int]
    context: Optional[dict]
    requested_fields: Optional[List[str]]  # From NOTIFICATION_CONFIG
    answered_fields: Optional[List[str]]  # From NOTIFICATION_CONFIG

Usage: Returned by GET /api/v1/notification/notifications endpoint

Special Fields: - requested_fields: Populated from NOTIFICATION_CONFIG based on type - answered_fields: Populated from NOTIFICATION_CONFIG based on type

NotificationRequestSchema

Request schema for creating notifications via API.

class NotificationRequestSchema(BaseModel):
    notification_type: NotificationType
    conversation_id: int
    context: Dict[str, str]

Usage: Request body for notification creation endpoints

Validation: - notification_type must be valid NotificationType enum value - conversation_id must reference existing conversation - context must include all fields from NOTIFICATION_CONFIG.requested_fields

Context Schemas

UserQuestionContext

Context schema for user_question_request notifications.

class UserQuestionContext(BaseModel):
    question: str  # Customer's question
    document_id: int  # Auto-generated Document ID
    lead_phone: str  # Customer phone number
    lead_name: Optional[str]  # Customer name (if available)

Field Descriptions:

• question: The exact question text from the customer
• document_id: ID of the created Document (category: UserQuestion) where Q&A will be stored
• lead_phone: Customer's phone number (formatted with + prefix)
• lead_name: Customer's profile name or extracted first name

Usage: - Validated when creating user_question_request notifications - Document is created first, then ID added to context - Context passed to campaign for variable substitution

Answer Schemas

These schemas define the expected answer format from merchant admins.

UserQuestionAnswerSchema

Answer payload for user_question_request notifications.

class UserQuestionAnswerSchema(BaseModel):
    """Answer payload expected from a merchant admin for a user question.

    This is stored on the Notification as the JSON schema and used to validate
    responses provided via the AnswerNotification tool.
    """
    answer: str

Field Descriptions:

• answer: The admin's answer to the customer's question

Usage: 1. Stored as answer_model_json_schema on Notification record 2. Included in assistant instruction message to merchant admins 3. Validated by AnswerNotificationTool when admin responds 4. Answer text is: - Stored in the associated Document's content field - Localized to customer's language via AI - Sent to customer via campaign (>24h) or Voyager (≤24h)

Example:

{
    "answer": "We are open Monday through Friday, 9am to 5pm EST"
}

UserSupportRequestAnswerSchema

Answer payload for user_support_request notifications.

class UserSupportRequestAnswerSchema(BaseModel):
    """Answer payload expected from a merchant admin for a support request.

    agent_response_to_customer is the exact text the admin wants sent to the
    customer (we will localize/format as needed before sending). resolution_notes
    are optional internal notes for audit/history.
    """
    agent_response_to_customer: str
    resolution_notes: Optional[str] = None

Field Descriptions:

• agent_response_to_customer: Admin's response text to send to customer
• Required field
• Will be localized to customer's language

• Used for campaign variable or Voyager context

• resolution_notes: Internal notes about the resolution

• Optional field
• NOT sent to customer
• Stored in notification context for audit/history
• Visible in admin dashboard for tracking

Usage: 1. Stored as answer_model_json_schema on Notification record 2. Included in assistant instruction message to merchant admins 3. Validated by AnswerNotificationTool when admin responds 4. agent_response_to_customer is: - Localized to customer's language via AI - Sent via campaign template (>24h) or Voyager (≤24h) 5. resolution_notes stored in notification context only

Example:

{
    "agent_response_to_customer": "Please send us your order number and we'll process the refund within 3-5 business days",
    "resolution_notes": "Customer eligible for full refund, item arrived damaged"
}

Schema Usage in Notification Flow

1. Request Phase

When creating a notification:

# The answer schema is stored as JSON schema
notification = Notification(
    notification_type=NotificationType.user_support_request.value,
    answer_model_json_schema=UserSupportRequestAnswerSchema.model_json_schema()
)

The schema is then included in the assistant instruction message sent to merchant admins.

2. Answer Phase

When merchant admin responds:

# Tool validates answer against stored schema
answer_data = json.loads(answer_json)
jsonschema.validate(
    instance=answer_data,
    schema=notification.answer_model_json_schema
)

3. Localization Phase

Admin's answer is localized for customer:

class LocalizedResponse(BaseModel):
    continuation_fragment: str  # For template variables
    full_sentence: str  # For direct messaging

# AI generates both variants
localized = ai_client.get_structured_output(
    messages=[...],
    schema=LocalizedResponse,
    model=CosmoModel.GPT41Mini
)

Fragment vs. Sentence:

• continuation_fragment: Fits after template clause
• Example: "informed you that we'll process your refund"

• Used in: "Our team has reviewed your request and {{customer_response_text}}"

• full_sentence: Standalone response

• Example: "We have reviewed your request and informed you that we'll process your refund within 3-5 business days."
• Used when sending direct via Voyager (≤24h window)

Validation Rules

At Request Time

Validated by request_notification: - All requested_fields must be present in context - Notification type must exist in NOTIFICATION_CONFIG - Conversation must exist - Context must match type-specific schema (e.g., UserQuestionContext)

At Answer Time

Validated by AnswerNotificationTool and answer_notification: - Notification must exist and be answerable - All answered_fields must be present in context - Answer JSON must be valid JSON - Answer must match notification's answer_model_json_schema - Notification must not be already answered (if allow_multiple_answers=False)

Related Schemas

Campaign Variables

Notification campaigns use variables defined in Campaign Models:

Request Campaigns: - lead_phone: Customer phone number - question: Question text (user_question_request) - support_request_type: Classified type (user_support_request) - support_request_reason: Support reason (user_support_request)

Answer Campaigns: - lead_name: Customer name - answer: Localized answer (user_question_request) - customer_response_text: Localized response fragment (user_support_request)

Message other_data

Notification-related messages include these fields in Message.other_data:

{
    "campaign_id": int,
    "notification_id": int,
    "notification_id_prefixed": str
}

Used for tracking notification lineage through message history.