aircall-api 1.1.0__py3-none-any.whl

aircall/__init__.py

@@ -0,0 +1,38 @@
+"""Aircall API Python SDK."""
+
+from aircall.client import AircallClient
+from aircall.exceptions import (
+    AircallAPIError,
+    AircallConnectionError,
+    AircallError,
+    AircallPermissionError,
+    AircallTimeoutError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    UnprocessableEntityError,
+    ValidationError,
+)
+from aircall.logging_config import configure_logging
+
+__all__ = [
+    # Client
+    "AircallClient",
+    # Base exceptions
+    "AircallError",
+    "AircallAPIError",
+    # API exceptions
+    "AuthenticationError",
+    "AircallPermissionError",
+    "NotFoundError",
+    "ValidationError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "ServerError",
+    # Connection exceptions
+    "AircallConnectionError",
+    "AircallTimeoutError",
+    # Logging
+    "configure_logging",
+]

aircall/client.py

@@ -0,0 +1,273 @@
+"""Aircall API client."""
+
+import base64
+import logging
+import time
+import requests
+from requests.exceptions import Timeout, ConnectionError as RequestsConnectionError
+
+from aircall.exceptions import (
+    AircallAPIError,
+    AircallConnectionError,
+    AircallTimeoutError,
+    AuthenticationError,
+    #AircallPermissionError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    UnprocessableEntityError,
+    ValidationError,
+)
+from aircall.resources import (
+    CallResource,
+    CompanyResource,
+    ContactResource,
+    DialerCampaignResource,
+    IntegrationResource,
+    MessageResource,
+    NumberResource,
+    TagResource,
+    TeamResource,
+    UserResource,
+    WebhookResource,
+)
+
+
+class AircallClient:
+    """
+    Main client for interacting with the Aircall API.
+
+    Handles authentication and provides access to all API resources.
+
+    Example:
+        >>> client = AircallClient(api_id="your_id", api_token="your_token")
+        >>> numbers = client.number.list()
+        >>> number = client.number.get(12345)
+    """
+
+    def __init__(
+        self,
+        api_id: str,
+        api_token: str,
+        timeout: int = 30,
+        verbose: bool = False
+    ) -> None:
+        """
+        Initialize the Aircall API client.
+
+        Args:
+            api_id: Your Aircall API ID
+            api_token: Your Aircall API token
+            timeout: Default request timeout in seconds (default: 30)
+            verbose: Enable verbose logging for debugging (default: False)
+                    When True, sets the logger level to DEBUG
+        """
+        self.base_url = "https://api.aircall.io/v1"
+        credentials = base64.b64encode(f"{api_id}:{api_token}".encode()).decode('utf-8')
+        self.timeout = timeout
+
+        # Initialize logger
+        self.logger = logging.getLogger('aircall.client')
+
+        # If verbose is enabled, set logger to DEBUG level
+        if verbose:
+            self.logger.setLevel(logging.DEBUG)
+            # Ensure handlers exist for the aircall logger
+            aircall_logger = logging.getLogger('aircall')
+            if not aircall_logger.handlers:
+                handler = logging.StreamHandler()
+                formatter = logging.Formatter(
+                    fmt='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    datefmt='%Y-%m-%d %H:%M:%S'
+                )
+                handler.setFormatter(formatter)
+                aircall_logger.addHandler(handler)
+                aircall_logger.setLevel(logging.DEBUG)
+
+        self.session = requests.Session()
+        self.session.headers.update({"Authorization": f"Basic {credentials}"})
+
+        self.logger.info("Aircall client initialized")
+
+        # Initialize resources
+        self.call = CallResource(self)
+        self.company = CompanyResource(self)
+        self.contact = ContactResource(self)
+        self.dialer_campaign = DialerCampaignResource(self)
+        self.integration = IntegrationResource(self)
+        self.message = MessageResource(self)
+        self.number = NumberResource(self)
+        self.tag = TagResource(self)
+        self.team = TeamResource(self)
+        self.user = UserResource(self)
+        self.webhook = WebhookResource(self)
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict = None,
+        json: dict = None,
+        timeout: int = None
+    ) -> dict:
+        """
+        Make an HTTP request to the Aircall API.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            endpoint: API endpoint (e.g., "/numbers", "/contacts/123")
+            params: Query parameters as dict (e.g., {"page": 1, "per_page": 50})
+            json: Request body as dict for POST/PUT requests
+            timeout: Request timeout in seconds (uses self.timeout if not specified)
+
+        Returns:
+            dict: Parsed JSON response
+
+        Raises:
+            ValidationError: When request validation fails (400)
+            AuthenticationError: When authentication fails (401 or 403)
+            NotFoundError: When resource is not found (404)
+            UnprocessableEntityError: When server cannot process request (422)
+            RateLimitError: When rate limit is exceeded (429)
+            ServerError: When server returns 5xx error
+            AircallConnectionError: When connection to API fails
+            AircallTimeoutError: When request times out
+            AircallAPIError: For other API errors
+        """
+        url = self.base_url + endpoint
+
+        # Log the request details
+        self.logger.debug("Request: %s %s", method, url)
+        if params:
+            self.logger.debug("  Query params: %s", params)
+        if json:
+            self.logger.debug("  Request body: %s", json)
+
+        start_time = time.time()
+
+        try:
+            # Use requests library to handle params and json automatically
+            response = self.session.request(
+                method=method,
+                url=url,
+                params=params,  # requests converts dict to query string
+                json=json,      # requests converts dict to JSON body and sets Content-Type
+                timeout=timeout or self.timeout
+            )
+        except Timeout as e:
+            elapsed = time.time() - start_time
+            self.logger.error(
+                "Request timeout: %s %s - Failed after %ss (elapsed: %.2fs)",
+                method, url, timeout or self.timeout, elapsed
+            )
+            raise AircallTimeoutError(
+                f"Request to {url} timed out after {timeout or self.timeout} seconds"
+            ) from e
+        except RequestsConnectionError as e:
+            elapsed = time.time() - start_time
+            self.logger.error(
+                "Connection error: %s %s - %s (elapsed: %.2fs)",
+                method, url, str(e), elapsed
+            )
+            raise AircallConnectionError(
+                f"Failed to connect to {url}: {str(e)}"
+            ) from e
+
+        elapsed = time.time() - start_time
+
+        # Handle successful responses
+        if 200 <= response.status_code < 300:
+            self.logger.debug(
+                "Response: %s %s %s (took %.2fs)",
+                response.status_code, method, url, elapsed
+            )
+            if response.status_code == 204:  # No Content
+                return {}
+            return response.json()
+
+        # Parse error response
+        error_data = None
+        error_message = response.reason
+        try:
+            error_data = response.json()
+            if isinstance(error_data, dict):
+                # Try to get message from various possible fields
+                error_message = error_data.get('message') or error_data.get('error') or error_message
+        except Exception:
+            # If response is not JSON, use text content
+            if response.text:
+                error_message = response.text
+
+        # Map status codes to appropriate exceptions based on Aircall API docs
+        status_code = response.status_code
+
+        # Log the error response
+        self.logger.warning(
+            "API error: %s %s %s - %s (took %.2fs)",
+            status_code, method, url, error_message, elapsed
+        )
+
+        if status_code == 400:
+            # Invalid payload/Bad Request
+            raise ValidationError(
+                error_message,
+                status_code=status_code,
+                response_data=error_data
+            )
+        if status_code == 401:
+            raise AuthenticationError(
+                error_message,
+                status_code=status_code,
+                response_data=error_data
+            )
+        if status_code == 403:
+            # Forbidden - Invalid API key or Bearer access token
+            raise AuthenticationError(
+                error_message,
+                status_code=status_code,
+                response_data=error_data
+            )
+        if status_code == 404:
+            # Not found - Id does not exist
+            raise NotFoundError(
+                error_message,
+                status_code=status_code,
+                response_data=error_data
+            )
+        if status_code == 422:
+            # Server unable to process the request
+            raise UnprocessableEntityError(
+                error_message,
+                status_code=status_code,
+                response_data=error_data
+            )
+        if status_code == 429:
+            # Rate limit exceeded
+            retry_after = response.headers.get('Retry-After')
+            if retry_after:
+                self.logger.warning(
+                    "Rate limit exceeded: %s %s - Retry after %ss",
+                    method, url, retry_after
+                )
+            else:
+                self.logger.warning("Rate limit exceeded (no retry-after header)")
+            raise RateLimitError(
+                error_message,
+                status_code=status_code,
+                response_data=error_data,
+                retry_after=int(retry_after) if retry_after else None
+            )
+        if 500 <= status_code < 600:
+            # Server errors
+            raise ServerError(
+                error_message,
+                status_code=status_code,
+                response_data=error_data
+            )
+        else:
+            # Generic API error for other status codes
+            raise AircallAPIError(
+                error_message,
+                status_code=status_code,
+                response_data=error_data
+            )

aircall/exceptions.py

@@ -0,0 +1,55 @@
+"""Custom exceptions for the Aircall API client."""
+
+
+class AircallError(Exception):
+    """Base exception for all Aircall errors"""
+
+
+class AircallAPIError(AircallError):
+    """Raised when the API returns an error response"""
+
+    def __init__(self, message, status_code=None, response_data=None):
+        self.message = message
+        self.status_code = status_code
+        self.response_data = response_data
+        super().__init__(self.message)
+
+
+class AuthenticationError(AircallAPIError):
+    """Raised when authentication fails (401)"""
+
+
+class AircallPermissionError(AircallAPIError):
+    """Raised when user lacks permission (403)"""
+
+
+class NotFoundError(AircallAPIError):
+    """Raised when resource not found (404)"""
+
+
+class ValidationError(AircallAPIError):
+    """Raised when request validation fails (400)"""
+
+
+class UnprocessableEntityError(AircallAPIError):
+    """Raised when server unable to process the request (422)"""
+
+
+class RateLimitError(AircallAPIError):
+    """Raised when rate limit exceeded (429)"""
+
+    def __init__(self, message, retry_after=None, **kwargs):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after  # Seconds until can retry
+
+
+class ServerError(AircallAPIError):
+    """Raised when server returns 5xx error"""
+
+
+class AircallConnectionError(AircallError):
+    """Raised when connection to API fails"""
+
+
+class AircallTimeoutError(AircallError):
+    """Raised when request times out"""

aircall/logging_config.py

@@ -0,0 +1,81 @@
+"""Logging configuration for the Aircall API SDK."""
+
+import logging
+import sys
+from typing import Optional
+
+
+def setup_logger(
+    name: str,
+    level: Optional[int] = None,
+    handler: Optional[logging.Handler] = None
+) -> logging.Logger:
+    """
+    Set up a logger with consistent formatting.
+
+    Args:
+        name: Logger name (typically __name__)
+        level: Logging level (defaults to WARNING if not set)
+        handler: Custom handler (defaults to StreamHandler if not set)
+
+    Returns:
+        logging.Logger: Configured logger instance
+    """
+    logger = logging.getLogger(name)
+
+    # Only configure if no handlers exist (avoid duplicate handlers)
+    if not logger.handlers:
+        if level is None:
+            level = logging.WARNING
+
+        logger.setLevel(level)
+
+        if handler is None:
+            handler = logging.StreamHandler(sys.stdout)
+
+        # Create formatter with timestamp, level, and message
+        formatter = logging.Formatter(
+            fmt='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+    return logger
+
+
+def configure_logging(level: Optional[int] = None) -> None:
+    """
+    Configure logging for the entire Aircall SDK.
+
+    This sets the logging level for all Aircall loggers.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+               If None, defaults to WARNING
+
+    Example:
+        >>> import logging
+        >>> from aircall.logging_config import configure_logging
+        >>> configure_logging(logging.DEBUG)
+    """
+    if level is None:
+        level = logging.WARNING
+
+    # Configure the root aircall logger
+    root_logger = logging.getLogger('aircall')
+    root_logger.setLevel(level)
+
+    # If no handlers exist on root, add a default one
+    if not root_logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        formatter = logging.Formatter(
+            fmt='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        handler.setFormatter(formatter)
+        root_logger.addHandler(handler)
+
+
+# Create default logger for the SDK
+logger = setup_logger('aircall')

aircall/models/__init__.py

@@ -0,0 +1,83 @@
+"""Aircall API models."""
+
+# Core resources
+from aircall.models.call import Call, CallComment
+from aircall.models.company import Company
+from aircall.models.contact import Contact, Email, PhoneNumber
+from aircall.models.number import Number, NumberMessages
+from aircall.models.tag import Tag
+from aircall.models.team import Team
+from aircall.models.user import User, UserAvailability
+
+# AI and Intelligence
+from aircall.models.ai_voice_agent import AIVoiceAgent
+from aircall.models.content import (
+    ActionItemsContent,
+    Content,
+    SummaryContent,
+    TopicsContent,
+    Utterance,
+)
+from aircall.models.conversation_intelligence import (
+    ConversationIntelligence,
+    RealtimeTranscription,
+    RealtimeTranscriptionCall,
+    RealtimeTranscriptionUtterance,
+)
+
+# Communication
+from aircall.models.message import MediaDetail, Message
+from aircall.models.webhook import Webhook
+
+# Campaign and Compliance
+from aircall.models.dialer_campaign import DialerCampaign, DialerCampaignPhoneNumber
+
+# Call-related
+from aircall.models.ivr_option import IVROption
+from aircall.models.participant import (
+    ConversationIntelligenceParticipant,
+    Participant,
+)
+
+# Integration
+from aircall.models.integration import Integration
+
+__all__ = [
+    # Core resources
+    "User",
+    "UserAvailability",
+    "Call",
+    "CallComment",
+    "Contact",
+    "PhoneNumber",
+    "Email",
+    "Number",
+    "NumberMessages",
+    "Team",
+    "Tag",
+    "Company",
+    # AI and Intelligence
+    "AIVoiceAgent",
+    "ConversationIntelligence",
+    "RealtimeTranscription",
+    "RealtimeTranscriptionCall",
+    "RealtimeTranscriptionUtterance",
+    "Content",
+    "Utterance",
+    "SummaryContent",
+    "TopicsContent",
+    "ActionItemsContent",
+    # Communication
+    "Message",
+    "MediaDetail",
+    "Webhook",
+    # Campaign and Compliance
+    "DialerCampaign",
+    "DialerCampaignPhoneNumber",
+    # Call-related
+    "Participant",
+    "ConversationIntelligenceParticipant",
+    "IVROption",
+    # Integration
+    "Integration",
+]

aircall/models/ai_voice_agent.py

@@ -0,0 +1,49 @@
+"""AI Voice Agent models for Aircall API."""
+from datetime import datetime
+from typing import Any, Dict, Literal, Optional
+
+from pydantic import BaseModel
+
+
+class AIVoiceAgent(BaseModel):
+    """
+    AI Voice Agent object representing calls handled by AI agents.
+
+    Accessible through webhook events:
+    - ai_voice_agent.started
+    - ai_voice_agent.ended
+    - ai_voice_agent.escalated
+    - ai_voice_agent.summary
+
+    Read-only. Not updatable or destroyable via API.
+    """
+    id: int  # Same value as call_id
+    call_id: int  # Same value as id
+    call_uuid: str
+    ai_voice_agent_id: str
+    ai_voice_agent_name: str
+    ai_voice_agent_session_id: str
+    number_id: int
+
+    # Only for started/ended events
+    external_caller_number: Optional[str] = None
+    aircall_number: Optional[str] = None
+
+    # Timestamps (Unix timestamps)
+    created_at: datetime
+    started_at: Optional[datetime] = None  # Only for started/ended events
+    ended_at: Optional[datetime] = None  # Only for ended event
+
+    # Only for ended event
+    call_end_reason: Optional[Literal[
+        "answered",
+        "escalated",
+        "disconnected",
+        "caller_hung_up"
+    ]] = None
+
+    # Only for escalated event
+    escalation_reason: Optional[str] = None
+
+    # Only for summary event - answers to intake questions
+    extracted_data: Optional[Dict[str, Any]] = None

aircall/models/call.py

@@ -0,0 +1,94 @@
+"""Call models for Aircall API."""
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+from aircall.models.contact import Contact
+from aircall.models.ivr_option import IVROption
+from aircall.models.number import Number
+from aircall.models.participant import Participant
+from aircall.models.tag import Tag
+from aircall.models.team import Team
+from aircall.models.user import User
+
+
+class CallComment(BaseModel):
+    """
+    Comment (Note) on a call.
+
+    Can be created by Agents or via API.
+    """
+    id: int
+    content: str
+    posted_at: datetime
+    posted_by: Optional["User"] = None  # Null if posted via API
+
+
+class Call(BaseModel):
+    """
+    Call resource representing phone interactions.
+
+    Three types:
+    - Inbound: External person → Agent
+    - Outbound: Agent → External person
+    - Internal: Agent → Agent (not in Public API)
+
+    Note: Call id is Int64 data type.
+    """
+    id: int  # Int64
+    sid: Optional[str] = None  # Only in Call APIs (same as call_uuid)
+    call_uuid: Optional[str] = None  # Only in Webhook events (same as sid)
+    direct_link: str
+
+    # Timestamps (Unix timestamps)
+    started_at: datetime
+    answered_at: Optional[datetime] = None  # Null if not answered
+    ended_at: Optional[datetime] = None
+
+    duration: int  # Seconds (ended_at - started_at, includes ringing)
+    status: Literal["initial", "answered", "done"]
+    direction: Literal["inbound", "outbound"]
+    raw_digits: str  # International format or "anonymous"
+
+    # Media URLs (valid for limited time)
+    asset: Optional[str] = None  # Secured webpage for recording/voicemail
+    recording: Optional[str] = None  # Direct MP3 URL (1 hour validity)
+    recording_short_url: Optional[str] = None  # Short URL (3 hours validity)
+    voicemail: Optional[str] = None  # Direct MP3 URL (1 hour validity)
+    voicemail_short_url: Optional[str] = None  # Short URL (3 hours validity)
+
+    archived: Optional[bool] = None
+    missed_call_reason: Optional[Literal[
+        "out_of_opening_hours",
+        "short_abandoned",
+        "abandoned_in_ivr",
+        "abandoned_in_classic",
+        "no_available_agent",
+        "agents_did_not_answer"
+    ]] = None
+
+    cost: Optional[str] = None  # Deprecated - U.S. cents
+
+    # Related objects
+    number: Optional["Number"] = None
+    user: Optional["User"] = None  # Who took or made the call
+    contact: Optional["Contact"] = None
+    assigned_to: Optional["User"] = None
+    teams: list["Team"] = []  # Only for inbound calls
+
+    # Transfer information
+    transferred_by: Optional["User"] = None
+    transferred_to: Optional["User"] = None  # First user of team if transferred to team
+    external_transferred_to: Optional[str] = None  # Only via call.external_transferred event
+    external_caller_number: Optional[str] = None  # Only via call.external_transferred event
+
+    # Collections
+    comments: list[CallComment] = []
+    tags: list["Tag"] = []
+
+    # Conference participants (referred as conference_participants in APIs)
+    participants: list[Participant] = []
+
+    # IVR options (requires fetch_call_timeline query param)
+    ivr_options_selected: list["IVROption"] = []

aircall/models/company.py

@@ -0,0 +1,14 @@
+"""Company model for Aircall API."""
+from pydantic import BaseModel
+
+
+class Company(BaseModel):
+    """
+    Company object representing an Aircall company.
+
+    Read-only. Not updatable or destroyable via API.
+    Can only be modified via Aircall Dashboard.
+    """
+    name: str
+    users_count: int
+    numbers_count: int