aircall-api 1.1.0__py3-none-any.whl

aircall/resources/message.py

@@ -0,0 +1,80 @@
+"""Resource module for managing messages"""
+from aircall.resources.base import BaseResource
+from aircall.models import Message
+
+
+class MessageResource(BaseResource):
+    """
+    API Resource for Aircall Messages.
+
+    Handles SMS, MMS, and WhatsApp messaging operations.
+    All operations are scoped to a specific number.
+    """
+
+    def create_configuration(self, number_id: int, **kwargs) -> dict:
+        """
+        Create message configuration for a number.
+
+        Args:
+            number_id: The ID of the number
+            **kwargs: Configuration data
+
+        Returns:
+            dict: Configuration response
+        """
+        return self._post(f"/numbers/{number_id}/messages/configuration", json=kwargs)
+
+    def get_configuration(self, number_id: int) -> dict:
+        """
+        Fetch message configuration for a number.
+
+        Args:
+            number_id: The ID of the number
+
+        Returns:
+            dict: Configuration data
+        """
+        return self._get(f"/numbers/{number_id}/messages/configuration")
+
+    def delete_configuration(self, number_id: int) -> dict:
+        """
+        Delete message configuration for a number.
+
+        Args:
+            number_id: The ID of the number
+
+        Returns:
+            dict: Delete configuration response
+        """
+        return self._delete(f"/numbers/{number_id}/messages/configuration")
+
+    def send(self, number_id: int, to: str, body: str, **kwargs) -> Message:
+        """
+        Send a message from a number.
+
+        Args:
+            number_id: The ID of the number to send from
+            to: Recipient phone number
+            body: Message body
+            **kwargs: Additional message data (media_details, etc.)
+
+        Returns:
+            Message: The sent message object
+        """
+        data = {"to": to, "body": body, **kwargs}
+        response = self._post(f"/numbers/{number_id}/messages/send", json=data)
+        return Message(**response["message"])
+
+    def send_native(self, number_id: int, **kwargs) -> Message:
+        """
+        Send a native message (WhatsApp template) from a number.
+
+        Args:
+            number_id: The ID of the number to send from
+            **kwargs: Native message data (template_id, parameters, etc.)
+
+        Returns:
+            Message: The sent message object
+        """
+        response = self._post(f"/numbers/{number_id}/messages/native/send", json=kwargs)
+        return Message(**response["message"])

aircall/resources/number.py

@@ -0,0 +1,94 @@
+"""Number resource for managing Aircall phone numbers."""
+
+from aircall.resources.base import BaseResource
+from aircall.models import Number
+
+
+class NumberResource(BaseResource):
+    """
+    API resource for Aircall phone numbers.
+
+    Handles operations related to phone numbers including listing,
+    retrieving, updating, and checking registration status.
+    """
+
+    def list_numbers(self, page: int = 1, per_page: int = 20) -> list[Number]:
+        """
+        List all numbers with pagination.
+
+        Args:
+            page: Page number (default 1)
+            per_page: Results per page (default 20, max 50)
+
+        Returns:
+            list[Number]: List of Number objects
+
+        Note:
+            Response includes pagination metadata in 'meta' field:
+            - count: Items in current page
+            - total: Total items
+            - current_page: Current page number
+            - next_page_link: URL to next page (if available)
+            - previous_page_link: URL to previous page (if available)
+
+        Example:
+            >>> numbers = client.number.list_numbers(page=1, per_page=50)
+            >>> for number in numbers:
+            ...     print(number.name, number.digits)
+        """
+        response = self._get("/numbers", params={"page": page, "per_page": per_page})
+        return [Number(**n) for n in response["numbers"]]
+
+    def get(self, number_id: int) -> Number:
+        """
+        Retrieve a specific number by ID.
+
+        Args:
+            number_id: Unique identifier for the number
+
+        Returns:
+            Number: Number object
+
+        Raises:
+            Exception: If number not found (404) or other API error
+
+        Example:
+            >>> number = client.number.get(12345)
+            >>> print(number.name, number.digits)
+        """
+        response = self._get(f"/numbers/{number_id}")
+        return Number(**response["number"])
+
+    def update(self, number_id: int, **kwargs) -> Number:
+        """
+        Update a number's configuration.
+
+        Args:
+            number_id: Unique identifier for the number
+            **kwargs: Fields to update (e.g., name, priority)
+
+        Returns:
+            Number: Updated Number object
+
+        Example:
+            >>> number = client.number.update(12345, name="Sales Line", priority=1)
+            >>> print(number.name)  # "Sales Line"
+        """
+        response = self._put(f"/numbers/{number_id}", json=kwargs)
+        return Number(**response["number"])
+
+    def get_registration_status(self, number_id: int) -> dict:
+        """
+        Get registration status for a number.
+
+        Args:
+            number_id: Unique identifier for the number
+
+        Returns:
+            dict: Registration status information
+
+        Example:
+            >>> status = client.number.get_registration_status(12345)
+            >>> print(status)
+        """
+        return self._get(f"/numbers/{number_id}/registration_status")

aircall/resources/tag.py

@@ -0,0 +1,83 @@
+"""Resource module for managing tags"""
+from aircall.resources.base import BaseResource
+from aircall.models import Tag
+
+
+class TagResource(BaseResource):
+    """
+    API Resource for Aircall Tags.
+
+    Tags are used to categorize calls and can be created by Admins.
+    Note: Emojis cannot be used in tag attributes and will be removed.
+    """
+
+    def list_tags(self, page: int = 1, per_page: int = 20) -> list[Tag]:
+        """
+        List all tags with pagination.
+
+        Args:
+            page: Page number (default 1)
+            per_page: Results per page (default 20, max 50)
+
+        Returns:
+            list[Tag]: List of Tag objects
+        """
+        response = self._get("/tags", params={"page": page, "per_page": per_page})
+        return [Tag(**t) for t in response["tags"]]
+
+    def get(self, tag_id: int) -> Tag:
+        """
+        Get a specific tag by ID.
+
+        Args:
+            tag_id: The ID of the tag to retrieve
+
+        Returns:
+            Tag: The tag object
+        """
+        response = self._get(f"/tags/{tag_id}")
+        return Tag(**response["tag"])
+
+    def create(self, name: str, color: str, description: str = None) -> Tag:
+        """
+        Create a new tag.
+
+        Args:
+            name: Tag name (emojis will be removed)
+            color: Tag color in hexadecimal format (e.g., "#FF5733")
+            description: Optional tag description
+
+        Returns:
+            Tag: The created tag object
+        """
+        data = {"name": name, "color": color}
+        if description:
+            data["description"] = description
+        response = self._post("/tags", json=data)
+        return Tag(**response["tag"])
+
+    def update(self, tag_id: int, **kwargs) -> Tag:
+        """
+        Update a tag.
+
+        Args:
+            tag_id: The ID of the tag to update
+            **kwargs: Tag fields to update (name, color, description)
+
+        Returns:
+            Tag: The updated tag object
+        """
+        response = self._put(f"/tags/{tag_id}", json=kwargs)
+        return Tag(**response["tag"])
+
+    def delete(self, tag_id: int) -> dict:
+        """
+        Delete a tag.
+
+        Args:
+            tag_id: The ID of the tag to delete
+
+        Returns:
+            dict: Delete response
+        """
+        return self._delete(f"/tags/{tag_id}")

aircall/resources/team.py

@@ -0,0 +1,92 @@
+"""Resource module for managing teams"""
+from aircall.resources.base import BaseResource
+from aircall.models import Team
+
+
+class TeamResource(BaseResource):
+    """
+    API Resource for Aircall Teams.
+
+    Teams are used to group users for call distribution.
+    Team names must be unique within a company (max 64 characters).
+    """
+
+    def list_teams(self, page: int = 1, per_page: int = 20) -> list[Team]:
+        """
+        List all teams with pagination.
+
+        Args:
+            page: Page number (default 1)
+            per_page: Results per page (default 20, max 50)
+
+        Returns:
+            list[Team]: List of Team objects
+        """
+        response = self._get("/teams", params={"page": page, "per_page": per_page})
+        return [Team(**t) for t in response["teams"]]
+
+    def get(self, team_id: int) -> Team:
+        """
+        Get a specific team by ID.
+
+        Args:
+            team_id: The ID of the team to retrieve
+
+        Returns:
+            Team: The team object
+        """
+        response = self._get(f"/teams/{team_id}")
+        return Team(**response["team"])
+
+    def create(self, name: str, **kwargs) -> Team:
+        """
+        Create a new team.
+
+        Args:
+            name: Team name (max 64 characters, must be unique in company)
+            **kwargs: Additional team data
+
+        Returns:
+            Team: The created team object
+        """
+        data = {"name": name, **kwargs}
+        response = self._post("/teams", json=data)
+        return Team(**response["team"])
+
+    def delete(self, team_id: int) -> dict:
+        """
+        Delete a team.
+
+        Args:
+            team_id: The ID of the team to delete
+
+        Returns:
+            dict: Delete response
+        """
+        return self._delete(f"/teams/{team_id}")
+
+    def add_user(self, team_id: int, user_id: int) -> dict:
+        """
+        Add a user to a team.
+
+        Args:
+            team_id: The ID of the team
+            user_id: The ID of the user to add
+
+        Returns:
+            dict: Add user response
+        """
+        return self._post(f"/teams/{team_id}/users/{user_id}")
+
+    def remove_user(self, team_id: int, user_id: int) -> dict:
+        """
+        Remove a user from a team.
+
+        Args:
+            team_id: The ID of the team
+            user_id: The ID of the user to remove
+
+        Returns:
+            dict: Remove user response
+        """
+        return self._delete(f"/teams/{team_id}/users/{user_id}")

aircall/resources/user.py

@@ -0,0 +1,129 @@
+"""Resource module for managing users"""
+from aircall.resources.base import BaseResource
+from aircall.models import User, UserAvailability
+
+
+class UserResource(BaseResource):
+    """
+    API Resource for Aircall Users.
+
+    Handles operations relating to users including availability and outbound calls.
+    """
+
+    def list_users(self, page: int = 1, per_page: int = 20) -> list[User]:
+        """
+        List all users with pagination.
+
+        Args:
+            page: Page number (default 1)
+            per_page: Results per page (default 20, max 50)
+
+        Returns:
+            list[User]: List of User objects
+        """
+        response = self._get("/users", params={"page": page, "per_page": per_page})
+        return [User(**u) for u in response["users"]]
+
+    def get(self, user_id: int) -> User:
+        """
+        Get a specific user by ID.
+
+        Args:
+            user_id: The ID of the user to retrieve
+
+        Returns:
+            User: The user object
+        """
+        response = self._get(f"/users/{user_id}")
+        return User(**response["user"])
+
+    def create(self, email: str, **kwargs) -> User:
+        """
+        Create a new user.
+
+        Args:
+            email: User email address
+            **kwargs: Additional user data (name, time_zone, language, etc.)
+
+        Returns:
+            User: The created user object
+        """
+        data = {"email": email, **kwargs}
+        response = self._post("/users", json=data)
+        return User(**response["user"])
+
+    def update(self, user_id: int, **kwargs) -> User:
+        """
+        Update a user.
+
+        Args:
+            user_id: The ID of the user to update
+            **kwargs: User fields to update
+
+        Returns:
+            User: The updated user object
+        """
+        response = self._put(f"/users/{user_id}", json=kwargs)
+        return User(**response["user"])
+
+    def delete(self, user_id: int) -> dict:
+        """
+        Delete a user.
+
+        Args:
+            user_id: The ID of the user to delete
+
+        Returns:
+            dict: Delete response
+        """
+        return self._delete(f"/users/{user_id}")
+
+    def get_availabilities(self) -> dict:
+        """
+        Retrieve availability status for all users.
+
+        Returns:
+            dict: Dictionary of user availabilities
+        """
+        return self._get("/users/availabilities")
+
+    def get_availability(self, user_id: int) -> UserAvailability:
+        """
+        Check availability of a specific user.
+
+        Args:
+            user_id: The ID of the user
+
+        Returns:
+            UserAvailability: Granular availability status
+        """
+        response = self._get(f"/users/{user_id}/availability")
+        return UserAvailability(**response)
+
+    def start_call(self, user_id: int, to: str, **kwargs) -> dict:
+        """
+        Start an outbound call for a user.
+
+        Args:
+            user_id: The ID of the user making the call
+            to: Phone number to call
+            **kwargs: Additional call parameters
+
+        Returns:
+            dict: Call response
+        """
+        data = {"to": to, **kwargs}
+        return self._post(f"/users/{user_id}/calls", json=data)
+
+    def dial(self, user_id: int, **kwargs) -> dict:
+        """
+        Dial a number for a user.
+
+        Args:
+            user_id: The ID of the user
+            **kwargs: Dial parameters
+
+        Returns:
+            dict: Dial response
+        """
+        return self._post(f"/users/{user_id}/dial", json=kwargs)

aircall/resources/webhook.py

@@ -0,0 +1,82 @@
+"""Resource module for managing webhooks"""
+from aircall.resources.base import BaseResource
+from aircall.models import Webhook
+
+
+class WebhookResource(BaseResource):
+    """
+    API Resource for Aircall Webhooks.
+
+    Webhooks are used to receive event notifications from Aircall.
+    Use the token field to authenticate incoming webhook requests.
+    """
+
+    def list_webhooks(self, page: int = 1, per_page: int = 20) -> list[Webhook]:
+        """
+        List all webhooks with pagination.
+
+        Args:
+            page: Page number (default 1)
+            per_page: Results per page (default 20, max 50)
+
+        Returns:
+            list[Webhook]: List of Webhook objects
+        """
+        response = self._get("/webhooks", params={"page": page, "per_page": per_page})
+        return [Webhook(**w) for w in response["webhooks"]]
+
+    def get(self, webhook_id: str) -> Webhook:
+        """
+        Get a specific webhook by ID.
+
+        Args:
+            webhook_id: The UUID of the webhook to retrieve
+
+        Returns:
+            Webhook: The webhook object
+        """
+        response = self._get(f"/webhooks/{webhook_id}")
+        return Webhook(**response["webhook"])
+
+    def create(self, url: str, events: list[str], custom_name: str = "Webhook", **kwargs) -> Webhook:
+        """
+        Create a new webhook.
+
+        Args:
+            url: Valid URL to your web server
+            events: List of event names to subscribe to
+            custom_name: Custom name for the webhook (default: "Webhook")
+            **kwargs: Additional webhook data
+
+        Returns:
+            Webhook: The created webhook object
+        """
+        data = {"url": url, "events": events, "custom_name": custom_name, **kwargs}
+        response = self._post("/webhooks", json=data)
+        return Webhook(**response["webhook"])
+
+    def update(self, webhook_id: str, **kwargs) -> Webhook:
+        """
+        Update a webhook.
+
+        Args:
+            webhook_id: The UUID of the webhook to update
+            **kwargs: Webhook fields to update (url, events, custom_name, active, etc.)
+
+        Returns:
+            Webhook: The updated webhook object
+        """
+        response = self._put(f"/webhooks/{webhook_id}", json=kwargs)
+        return Webhook(**response["webhook"])
+
+    def delete(self, webhook_id: str) -> dict:
+        """
+        Delete a webhook.
+
+        Args:
+            webhook_id: The UUID of the webhook to delete
+
+        Returns:
+            dict: Delete response
+        """
+        return self._delete(f"/webhooks/{webhook_id}")