Response Types

Data models for Apala API client.

All models use Pydantic for type safety and validation.

class apala_client.models.AuthResponse(**data)[source]

Authentication response from the server.

Parameters:: data (Any)

access_token: str

refresh_token: str

token_type: str

expires_in: int

company_id: str

company_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.RefreshResponse(**data)[source]

Token refresh response from the server.

Parameters:: data (Any)

access_token: str

expires_in: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.CandidateMessageResponse(**data)[source]

Candidate message in processing response.

Parameters:: data (Any)

content: str

channel: str

message_id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.MessageProcessingResponse(**data)[source]

Message processing response from the server.

Parameters:: data (Any)

company: str

customer_id: str

candidate_message: CandidateMessageResponse

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.MessageOptimizationResponse(**data)[source]

Message optimization response from the server.

Parameters:: data (Any)

message_id: str

optimized_message: str

recommended_channel: str

original_message: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.FeedbackResponse(**data)[source]

Feedback submission response from the server.

Parameters:: data (Any)

id: str

message_id: str

customer_responded: bool

score: int

actual_sent_message: Optional[str]

inserted_at: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.FeedbackItemResponse(**data)[source]

Individual feedback item in bulk response.

Parameters:: data (Any)

id: str

message_id: str

customer_responded: bool

score: int

actual_sent_message: Optional[str]

inserted_at: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.BulkFeedbackResponse(**data)[source]

Bulk feedback submission response from the server.

Parameters:: data (Any)

success: bool

count: int

feedback: List[FeedbackItemResponse]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.Message(**data)[source]

Represents a customer message.

Parameters:: data (Any)

content: str

channel: str

message_id: Optional[str]

send_timestamp: Optional[str]

reply_or_not: bool

classmethod validate_channel(v)[source]

Validate channel is one of the allowed values.

Parameters:: v (str)
Return type:: str

model_post_init(_Message__context)[source]

Generate message_id and timestamp if not provided.

Parameters:: _Message__context (Any)
Return type:: None

to_dict()[source]

Convert to dictionary for API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.MessageFeedback(**data)[source]

Represents feedback for a processed message.

Parameters:: data (Any)

original_message_id: str

sent_message_content: str

customer_responded: bool

quality_score: int

time_to_respond_ms: Optional[int]

to_dict()[source]

Convert to dictionary for API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.MessageHistory(**data)[source]

Represents a collection of customer messages and a candidate response.

Parameters:: data (Any)

messages: List[Message]

candidate_message: Message

customer_id: str

zip_code: str

company_guid: str

classmethod validate_uuid(v)[source]

Validate UUID format.

Parameters:: v (str)
Return type:: str

to_processing_dict()[source]

Convert to dictionary for message processing API requests.

Return type:: Dict[str, Any]

to_optimization_dict()[source]

Convert to dictionary for message optimization API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The Apala API provides fully typed responses using TypedDict for compile-time type safety and IDE autocomplete support.

Authentication Types

AuthResponse

class apala_client.models.AuthResponse(**data)[source]

Authentication response from the server.

Parameters:: data (Any)

access_token: str

refresh_token: str

token_type: str

expires_in: int

company_id: str

company_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Response from the authentication endpoint when exchanging an API key for JWT tokens.

Fields:

access_token (str): JWT access token for API requests
refresh_token (str): JWT refresh token for obtaining new access tokens
token_type (str): Token type, typically “Bearer”
expires_in (int): Access token expiration time in seconds
company_id (str): Your company’s unique identifier
company_name (str): Your company’s display name

Example:

from apala_client import ApalaClient
from apala_client.models import AuthResponse

client = ApalaClient(api_key="your-key")
auth_response: AuthResponse = client.authenticate()

# Type-safe access to response fields
token: str = auth_response["access_token"]
company: str = auth_response["company_name"]
expires: int = auth_response["expires_in"]

RefreshResponse

class apala_client.models.RefreshResponse(**data)[source]

Token refresh response from the server.

Parameters:: data (Any)

access_token: str

expires_in: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Response from the token refresh endpoint.

Fields:

access_token (str): New JWT access token
expires_in (int): New token expiration time in seconds

Example:

from apala_client.models import RefreshResponse

refresh_response: RefreshResponse = client.refresh_access_token()
new_token: str = refresh_response["access_token"]

Message Processing Types

MessageProcessingResponse

class apala_client.models.MessageProcessingResponse(**data)[source]

Message processing response from the server.

Parameters:: data (Any)

company: str

customer_id: str

candidate_message: CandidateMessageResponse

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Response from the message processing endpoint.

Fields:

company (str): Company GUID that processed the message
customer_id (str): Customer UUID
candidate_message (CandidateMessageResponse): Processed message details

Example:

from apala_client.models import MessageProcessingResponse

response: MessageProcessingResponse = client.message_process(...)

# Type-safe field access
company_id: str = response["company"]
customer_id: str = response["customer_id"]
message_info = response["candidate_message"]

CandidateMessageResponse

class apala_client.models.CandidateMessageResponse(**data)[source]

Candidate message in processing response.

Parameters:: data (Any)

content: str

channel: str

message_id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Nested type representing the processed candidate message.

Fields:

content (str): The message content
channel (str): Communication channel
message_id (str): Unique message identifier

Example:

from apala_client.models import CandidateMessageResponse

candidate: CandidateMessageResponse = response["candidate_message"]

message_id: str = candidate["message_id"]
content: str = candidate["content"]
channel: str = candidate["channel"]

MessageOptimizationResponse

class apala_client.models.MessageOptimizationResponse(**data)[source]

Message optimization response from the server.

Parameters:: data (Any)

message_id: str

optimized_message: str

recommended_channel: str

original_message: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Response from the message optimization endpoint.

Fields:

optimized_message (str): AI-enhanced message content
recommended_channel (str): Optimal communication channel
original_message (str): Original message for comparison

Example:

from apala_client.models import MessageOptimizationResponse

optimization: MessageOptimizationResponse = client.optimize_message(...)

original: str = optimization["original_message"]
improved: str = optimization["optimized_message"]
channel: str = optimization["recommended_channel"]

Feedback Types

FeedbackResponse

class apala_client.models.FeedbackResponse(**data)[source]

Feedback submission response from the server.

Parameters:: data (Any)

id: str

message_id: str

customer_responded: bool

score: int

actual_sent_message: Optional[str]

inserted_at: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Response from feedback submission endpoints.

Fields:

success (bool): Whether feedback was successfully recorded
message (str): Human-readable status message
feedback_id (int): Unique identifier for the feedback record
received_at (str): ISO timestamp when feedback was received

Example:

from apala_client.models import FeedbackResponse

feedback_response: FeedbackResponse = client.submit_single_feedback(feedback)

success: bool = feedback_response["success"]
feedback_id: int = feedback_response["feedback_id"]
timestamp: str = feedback_response["received_at"]

Type Safety Benefits

Using TypedDict provides several advantages:

IDE Autocomplete

Your IDE can provide intelligent autocomplete for response fields:

auth_response = client.authenticate()
# IDE shows: access_token, refresh_token, company_name, etc.
token = auth_response["access_token"]

Compile-Time Error Detection

mypy catches type errors during development:

# This will cause a mypy error:
auth_response = client.authenticate()
invalid_field = auth_response["nonexistent_field"]  # Error!

Runtime Safety

TypedDict prevents accessing non-existent fields:

# This raises a KeyError at runtime:
response = client.authenticate()
bad_field = response["missing_key"]  # KeyError!

Documentation Through Types

The types serve as executable documentation:

def process_auth_response(response: AuthResponse) -> str:
    # Developers know exactly what fields are available
    return f"Company {response['company_name']} authenticated"

Working with Typed Responses

Basic Usage

from apala_client import ApalaClient
from apala_client.models import AuthResponse, MessageProcessingResponse

client = ApalaClient(api_key="your-key")

# Fully typed authentication
auth: AuthResponse = client.authenticate()
company_name: str = auth["company_name"]

# Fully typed message processing
result: MessageProcessingResponse = client.message_process(...)
message_id: str = result["candidate_message"]["message_id"]

Error Handling with Types

import requests
from apala_client.models import AuthResponse

try:
    auth_response: AuthResponse = client.authenticate()
    token = auth_response["access_token"]
except requests.HTTPError as e:
    print(f"Authentication failed: {e.response.status_code}")
except KeyError as e:
    print(f"Unexpected response format: {e}")

Type Checking

Enable mypy in your project to catch type errors:

# Install mypy
pip install mypy

# Check your code
mypy your_project.py

IDE Configuration

For the best experience, use an IDE that supports Python type hints:

VS Code: Install the Python extension
PyCharm: Type hints supported out of the box
Vim/Neovim: Use coc.nvim or similar plugins

This ensures you get full autocomplete and error detection while developing with the Apala API.