aircall-api 1.1.0__py3-none-any.whl

aircall/models/contact.py

@@ -0,0 +1,32 @@
+"""Contact models for Aircall API."""
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class PhoneNumber(BaseModel):
+    """Phone number associated with a contact"""
+    id: int
+    label: Optional[str] = None
+    value: str
+
+
+class Email(BaseModel):
+    """Email address associated with a contact"""
+    id: int
+    label: Optional[str] = None
+    value: str
+
+
+class Contact(BaseModel):
+    """Contact resource from Aircall API"""
+    id: int
+    direct_link: str
+    first_name: Optional[str] = None
+    last_name: Optional[str] = None
+    company_name: Optional[str] = None
+    description: Optional[str] = None
+    information: Optional[str] = None
+    is_shared: bool
+    phone_numbers: list[PhoneNumber] = []
+    emails: list[Email] = []

aircall/models/content.py

@@ -0,0 +1,42 @@
+"""Content models for Aircall API."""
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+
+class Utterance(BaseModel):
+    """A single sentence/utterance in a transcription"""
+    start_time: float
+    end_time: float
+    text: str
+    participant_type: Literal["external", "internal"]
+    user_id: Optional[int] = None
+    phone_number: Optional[str] = None
+
+
+class Content(BaseModel):
+    """Content object for transcription type"""
+    language: Literal[
+        "en", "en-US", "en-GB", "en-AU",
+        "fr-FR", "fr",
+        "es-ES", "es",
+        "de-DE", "de",
+        "nl-NL", "nl",
+        "it-IT", "it"
+    ]
+    utterances: list[Utterance] = []
+
+
+class SummaryContent(BaseModel):
+    """Content object for summary type"""
+    content: str
+
+
+class TopicsContent(BaseModel):
+    """Content object for topics type"""
+    content: list[str] = []
+
+
+class ActionItemsContent(BaseModel):
+    """Content object for action items type"""
+    content: str

aircall/models/conversation_intelligence.py

@@ -0,0 +1,66 @@
+"""Conversation Intelligence models for Aircall API."""
+from datetime import datetime
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel
+
+from aircall.models.participant import Participant
+
+
+class Playbook(BaseModel):
+    """Playbook definition object"""
+    # Define based on actual API response structure
+
+
+class PlaybookResultTopic(BaseModel):
+    """Playbook topic result"""
+    name: str
+    result: Any  # Define more specifically based on API structure
+
+
+class ConversationIntelligence(BaseModel):
+    """
+    Conversation Intelligence object for AI entities
+    (Transcription, Sentiment, Topics, Summary, Action Items, Playbook Results)
+    """
+    id: int
+    call_id: str
+    call_uuid: Optional[str] = None
+    number_id: Optional[int] = None
+    participants: Optional[list[Participant]] = None
+    type: Optional[Literal["call", "voicemail"]] = None
+    content: Optional[Any] = None  # Can be string, Array, or Object
+    call_created_at: Optional[datetime] = None
+    created_at: Optional[datetime] = None
+    created_by: Optional[int] = None
+    updated_at: Optional[datetime] = None
+    updated_by: Optional[int] = None
+    ai_generated: Optional[bool] = None
+    adherence_score: Optional[float] = None
+    playbook: Optional[Playbook] = None
+    playbook_result_topics: Optional[list[PlaybookResultTopic]] = None
+
+
+class RealtimeTranscriptionUtterance(BaseModel):
+    """Utterance object for realtime transcription webhook"""
+    participant_type: Literal["internal", "external"]
+    user_id: Optional[int] = None
+    timestamp: int
+    duration_ms: int
+    text: str
+    language: str
+
+
+class RealtimeTranscriptionCall(BaseModel):
+    """Call information for realtime transcription webhook"""
+    id: Optional[int] = None
+    uuid: str
+    number_id: int
+    direction: Literal["inbound", "outbound"]
+
+
+class RealtimeTranscription(BaseModel):
+    """Realtime transcription webhook event object"""
+    id: str
+    call: RealtimeTranscriptionCall
+    utterances: list[RealtimeTranscriptionUtterance]

aircall/models/dialer_campaign.py

@@ -0,0 +1,21 @@
+"""Dialer Campaign models for Aircall API."""
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class DialerCampaignPhoneNumber(BaseModel):
+    """Phone number in a dialer campaign"""
+    id: int
+    number: str
+    called: bool
+    created_at: datetime
+
+
+class DialerCampaign(BaseModel):
+    """Dialer Campaign (Power Dialer) resource"""
+    id: int
+    number_id: Optional[str] = None
+    created_at: datetime
+    phone_numbers: list[DialerCampaignPhoneNumber] = []

aircall/models/integration.py

@@ -0,0 +1,20 @@
+"""Integration models for Aircall API."""
+from typing import TYPE_CHECKING, Optional
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from aircall.models.user import User
+
+
+class Integration(BaseModel):
+    """Integration object representing connection state with third-party services"""
+    name: str
+    custom_name: Optional[str] = None
+    logo: str
+    company_id: int
+    status: str
+    active: bool
+    number_ids: list[int] = []
+    numbers_count: int
+    user: Optional["User"] = None

aircall/models/ivr_option.py

@@ -0,0 +1,22 @@
+"""IVR Option model for Aircall API."""
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class IVROption(BaseModel):
+    """
+    IVR Option object representing IVR input from Smartflow-enabled number.
+
+    Read-only. Available within call object when fetch_call_timeline=true.
+    Only available for calls from last 2 months.
+    All timestamps are in ISO 8601 format.
+    """
+    id: str
+    title: str
+    key: str
+    branch: Optional[str] = None
+    created_at: datetime
+    transition_started_at: datetime
+    transition_ended_at: datetime

aircall/models/message.py

@@ -0,0 +1,52 @@
+"""Message models for Aircall API."""
+from datetime import datetime
+from typing import TYPE_CHECKING, Literal, Optional
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from aircall.models.contact import Contact
+    from aircall.models.number import Number
+
+
+class MediaDetail(BaseModel):
+    """Media file attached to a message"""
+    file_name: str
+    file_type: str
+    presigned_url: str
+
+
+class Message(BaseModel):
+    """
+    Message object for SMS, MMS, and WhatsApp communications.
+
+    Read-only. Not updatable or destroyable via API.
+    WhatsApp-specific attributes won't be present for SMS/MMS.
+    """
+    id: str
+    direct_link: str
+    direction: Literal["inbound", "outbound"]
+    external_number: str
+    body: str
+    status: str
+    raw_digits: str
+    media_details: list[MediaDetail] = []
+    created_at: datetime
+    updated_at: datetime
+    sent_at: Optional[datetime] = None
+
+    # Channel-specific fields
+    channel: Optional[Literal["whatsapp"]] = None  # null for SMS/MMS
+
+    # WhatsApp-specific fields
+    template_content: Optional[str] = None
+    type: Optional[str] = None
+    metadata: Optional[str] = None
+    parent_id: Optional[str] = None
+    whatsapp_message_category: Optional[Literal["marketing", "utility", "authentication"]] = None
+    whatsapp_message_type: Optional[Literal["regular", "free_entry_point", "free_customer_serivce"]] = None
+    recipient_country: Optional[str] = None
+
+    # Related objects
+    number: Optional["Number"] = None
+    contact: Optional["Contact"] = None

aircall/models/number.py

@@ -0,0 +1,55 @@
+"""Number models for Aircall API."""
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+from aircall.models.user import User
+
+
+class NumberMessages(BaseModel):
+    """
+    Music and Messages configuration for a Number.
+
+    Custom audio files can be uploaded with public URLs.
+    Check Aircall encoding recommendations first.
+    """
+    welcome: Optional[str] = None
+    waiting: Optional[str] = None
+    ringing_tone: Optional[str] = None
+    unanswered_call: Optional[str] = None  # Deprecated
+    after_hours: Optional[str] = None
+    ivr: Optional[str] = None
+    voicemail: Optional[str] = None
+    closed: Optional[str] = None  # Deprecated
+    callback_later: Optional[str] = None  # Deprecated
+
+
+class Number(BaseModel):
+    """
+    Number resource representing an Aircall phone number.
+
+    Numbers can be purchased and configured via Dashboard.
+    Note: Several fields are deprecated due to Smartflows migration.
+    """
+    id: int
+    direct_link: str
+    name: str
+    digits: str
+    e164_digits: Optional[str] = None  # Only in webhook events
+    created_at: datetime
+    country: str
+    time_zone: str
+
+    # Deprecated: No longer updated for Smartflows
+    open: Optional[bool] = None
+
+    availability_status: Optional[Literal["open", "custom", "closed"]] = None
+
+    # Deprecated: No longer supported
+    is_ivr: Optional[bool] = None
+
+    live_recording_activated: bool
+    users: list["User"] = []
+    priority: Optional[int] = None  # null, 0 (no priority), or 1 (top priority)
+    messages: Optional[NumberMessages] = None

aircall/models/participant.py

@@ -0,0 +1,38 @@
+"""Participant models for Aircall API."""
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+
+class Participant(BaseModel):
+    """
+    Participant in a conference call (Call Object).
+
+    Referenced as 'conference_participants' in Call APIs
+    and as 'participants' in call webhook events.
+    """
+    id: Optional[str] = None  # Contact or User ID (not present for external)
+    type: Literal["user", "contact", "external"]
+    name: Optional[str] = None  # Not present for external
+    phone_number: Optional[str] = None  # Not present for user type
+
+
+class ConversationIntelligenceParticipant(BaseModel):
+    """
+    Participant in Conversation Intelligence Object.
+
+    Used in transcription and sentiment events.
+    """
+    participant_type: Literal["internal", "external", "ai_voice_agent"]
+
+    # Not present for internal or ai_voice_agent
+    phone_number: Optional[str] = None
+
+    # Sentiment value (only for sentiment.created event)
+    value: Optional[Literal["NEUTRAL", "POSITIVE", "NEGATIVE"]] = None
+
+    # User ID (only for transcription.created, not for external/ai_voice_agent)
+    user_id: Optional[str] = None
+
+    # AI Voice Agent ID (only for transcription.created, only for ai_voice_agent type)
+    ai_voice_agent_id: Optional[str] = None

aircall/models/tag.py

@@ -0,0 +1,18 @@
+"""Tag models for Aircall API."""
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class Tag(BaseModel):
+    """
+    Tag resource for categorizing calls.
+
+    Can be created by Admins in Dashboard or via API.
+    Emojis cannot be used in Tag attributes (will be removed).
+    """
+    id: int
+    direct_link: str
+    name: str
+    color: str  # Hexadecimal format (e.g., "#FF5733")
+    description: Optional[str] = None

aircall/models/team.py

@@ -0,0 +1,20 @@
+"""Team models for Aircall API."""
+from datetime import datetime
+
+from pydantic import BaseModel
+
+from aircall.models.user import User
+
+
+class Team(BaseModel):
+    """
+    Team resource for grouping users.
+
+    Teams are used in call distributions of Numbers.
+    Name must be unique in a company (max 64 characters).
+    """
+    id: int
+    direct_link: str
+    name: str  # Max 64 characters, must be unique in company
+    created_at: datetime
+    users: list[User] = []

aircall/models/user.py

@@ -0,0 +1,48 @@
+"""User models for Aircall API."""
+from datetime import datetime
+from typing import TYPE_CHECKING, Literal, Optional
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from aircall.models.number import Number
+
+
+class User(BaseModel):
+    """
+    User resource representing an Aircall user.
+
+    Users can be Admins (Dashboard + Phone app access) or Agents (Phone app only).
+    Users are assigned to Numbers.
+    """
+    id: int
+    direct_link: str
+    name: str  # Result of first_name + last_name
+    email: str
+    created_at: datetime
+
+    # Availability fields
+    available: bool  # Based on working hours
+    availability_status: Literal["available", "custom", "unavailable"]
+    substatus: str  # always_open, always_closed, or specific reason
+
+    # Related resources
+    numbers: list["Number"] = []
+
+    # Settings
+    time_zone: str  # Default: Etc/UTC
+    language: str  # IETF language tag, default: en-US
+    wrap_up_time: int  # Timer after call ends (seconds)
+
+
+class UserAvailability(BaseModel):
+    """
+    Granular availability status for a user.
+
+    Use the dedicated endpoint to retrieve these statuses.
+    """
+    available: Optional[bool] = None  # Ready to answer calls
+    offline: Optional[bool] = None  # Not online
+    do_not_disturb: Optional[bool] = None  # DND toggled
+    in_call: Optional[bool] = None  # Currently on a call
+    after_call_work: Optional[bool] = None  # Tagging/wrapping up

aircall/models/webhook.py

@@ -0,0 +1,22 @@
+"""Webhook Model File"""
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+
+class Webhook(BaseModel):
+    """
+    Webhook resource for receiving event notifications.
+
+    Composed of a custom_name and list of events.
+    Use the token field to identify which Aircall account sent the webhook.
+    """
+    webhook_id: str = Field(..., description="UUID identifier for the webhook")
+    direct_link: str
+    created_at: datetime
+    custom_name: str = "Webhook"  # Default value
+    url: str  # Valid URL to web server
+    active: bool = True  # Default is true
+    token: str  # Unique token for authentication
+    events: list[str] = []  # List of registered event names

aircall/resources/__init__.py

@@ -0,0 +1,29 @@
+"""Aircall API resource classes."""
+
+from aircall.resources.base import BaseResource
+from aircall.resources.call import CallResource
+from aircall.resources.company import CompanyResource
+from aircall.resources.contact import ContactResource
+from aircall.resources.dialer_campaign import DialerCampaignResource
+from aircall.resources.integration import IntegrationResource
+from aircall.resources.message import MessageResource
+from aircall.resources.number import NumberResource
+from aircall.resources.tag import TagResource
+from aircall.resources.team import TeamResource
+from aircall.resources.user import UserResource
+from aircall.resources.webhook import WebhookResource
+
+__all__ = [
+    "BaseResource",
+    "CallResource",
+    "CompanyResource",
+    "ContactResource",
+    "DialerCampaignResource",
+    "IntegrationResource",
+    "MessageResource",
+    "NumberResource",
+    "TagResource",
+    "TeamResource",
+    "UserResource",
+    "WebhookResource",
+]

aircall/resources/base.py

@@ -0,0 +1,77 @@
+"""Base resource class for all Aircall API resources."""
+
+import logging
+
+
+class BaseResource:
+    """
+    Base class for all API resource classes.
+
+    Provides common functionality for making API requests and helper methods
+    that all resource classes can use.
+    """
+
+    def __init__(self, client):
+        """
+        Initialize the resource with a client instance.
+
+        Args:
+            client: AircallClient instance
+        """
+        self._client = client
+        self._logger = logging.getLogger(f'aircall.resources.{self.__class__.__name__}')
+
+    def _get(self, endpoint: str, params: dict = None, **kwargs) -> dict:
+        """
+        Make a GET request.
+
+        Args:
+            endpoint: API endpoint
+            params: Query parameters
+            **kwargs: Additional arguments passed to _request()
+
+        Returns:
+            dict: Parsed JSON response
+        """
+        return self._client._request("GET", endpoint, params=params, **kwargs)
+
+    def _post(self, endpoint: str, json: dict = None, **kwargs) -> dict:
+        """
+        Make a POST request.
+
+        Args:
+            endpoint: API endpoint
+            json: Request body
+            **kwargs: Additional arguments passed to _request()
+
+        Returns:
+            dict: Parsed JSON response
+        """
+        return self._client._request("POST", endpoint, json=json, **kwargs)
+
+    def _put(self, endpoint: str, json: dict = None, **kwargs) -> dict:
+        """
+        Make a PUT request.
+
+        Args:
+            endpoint: API endpoint
+            json: Request body
+            **kwargs: Additional arguments passed to _request()
+
+        Returns:
+            dict: Parsed JSON response
+        """
+        return self._client._request("PUT", endpoint, json=json, **kwargs)
+
+    def _delete(self, endpoint: str, **kwargs) -> dict:
+        """
+        Make a DELETE request.
+
+        Args:
+            endpoint: API endpoint
+            **kwargs: Additional arguments passed to _request()
+
+        Returns:
+            dict: Parsed JSON response
+        """
+        return self._client._request("DELETE", endpoint, **kwargs)