ccai-python 1.1.0__tar.gz → 1.2.0__tar.gz

{ccai_python-1.1.0 → ccai_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ccai-python
-Version: 1.1.0
+Version: 1.2.0
 Summary: Python client for CloudContactAI API
 Author: CloudContactAI LLC
 License: MIT
@@ -21,7 +21,7 @@ Dynamic: requires-python
 
 # CCAI Python Client
 
-Version: 1.1.0
+Version: 1.2.0
 
 A Python client for interacting with the CloudContactAI API.
 
@@ -70,6 +70,30 @@ campaign_response = ccai.sms.send(
 print(f"Campaign sent with ID: {campaign_response.campaign_id}")
 ```
 
+### SMS — Template-Controlled Accounts
+
+If an account has been configured to enforce template-only messaging, all campaigns must reference a pre-approved template ID. Sending a free-text message to such an account will result in a `422` error.
+
+```python
+# Send to multiple recipients using a template
+response = ccai.sms.send_with_template(
+    accounts=accounts,
+    template_id=12345,   # the ID of the approved template
+    title="My Campaign"
+)
+
+# Send to a single recipient using a template
+response = ccai.sms.send_single_with_template(
+    first_name="John",
+    last_name="Doe",
+    phone="+15551234567",
+    template_id=12345,
+    title="My Campaign"
+)
+```
+
+The message body is resolved server-side from the template. Variable substitution (e.g. `${firstName}`) is applied automatically using the recipient's account data.
+
 ### MMS
 
 ```python
@@ -88,7 +112,6 @@ def track_progress(status):
 # Create options with progress tracking
 options = SMSOptions(
     timeout=60,
-    retries=3,
     on_progress=track_progress
 )
 
@@ -316,22 +339,18 @@ def verify_and_handle_webhook(signature, client_id, event_hash, secret):
         print("Invalid signature")
 
 # Create a webhook handler for web frameworks
-def handle_message_sent(event):
-    print(f"Message sent: {event.message} to {event.to}")
-
-def handle_message_received(event):
-    print(f"Message received: {event.message} from {event.from_}")
+def handle_event(event):
+    if event.event_type == WebhookEventType.MESSAGE_SENT:
+        print(f"Message sent: {event.data.get('Message')} to {event.data.get('To')}")
+    elif event.event_type == WebhookEventType.MESSAGE_RECEIVED:
+        print(f"Message received: {event.data.get('Message')} from {event.data.get('From')}")
 
-handlers = {
-    'on_message_sent': handle_message_sent,
-    'on_message_received': handle_message_received
-}
-
-webhook_handler = ccai.webhook.create_handler(handlers)
+webhook_handler = ccai.webhook.create_handler({'on_event': handle_event})
 
 # Use with Flask
-from flask import Flask, request, jsonify
+import os
 import json
+from flask import Flask, request, jsonify
 
 app = Flask(__name__)
 
@@ -435,6 +454,8 @@ campaign = ccai.campaigns.create({
     "subUseCases": ["CUSTOMER_CARE", "TWO_FACTOR_AUTHENTICATION", "ACCOUNT_NOTIFICATION"],
     "description": "Security codes and support messaging.",
     "messageFlow": "Users opt-in via signup form at https://example.com/signup",
+    "termsLink": "https://example.com/terms",
+    "privacyLink": "https://example.com/privacy",
     "hasEmbeddedLinks": True,
     "hasEmbeddedPhone": False,
     "isAgeGated": False,
@@ -475,6 +496,8 @@ ccai.campaigns.delete(campaign["id"])
 
 > Note: `MIXED` and `LOW_VOLUME_MIXED` campaigns require 2–3 `subUseCases`.
 
+> `termsLink` and `privacyLink` are optional fields on the campaign dict.
+
 #### Sub-Use Cases
 
 `TWO_FACTOR_AUTHENTICATION`, `ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`, `FRAUD_ALERT`, `MARKETING`, `POLLING_VOTING`

{ccai_python-1.1.0 → ccai_python-1.2.0}/README.md

@@ -1,6 +1,6 @@
 # CCAI Python Client
 
-Version: 1.1.0
+Version: 1.2.0
 
 A Python client for interacting with the CloudContactAI API.
 
@@ -49,6 +49,30 @@ campaign_response = ccai.sms.send(
 print(f"Campaign sent with ID: {campaign_response.campaign_id}")
 ```
 
+### SMS — Template-Controlled Accounts
+
+If an account has been configured to enforce template-only messaging, all campaigns must reference a pre-approved template ID. Sending a free-text message to such an account will result in a `422` error.
+
+```python
+# Send to multiple recipients using a template
+response = ccai.sms.send_with_template(
+    accounts=accounts,
+    template_id=12345,   # the ID of the approved template
+    title="My Campaign"
+)
+
+# Send to a single recipient using a template
+response = ccai.sms.send_single_with_template(
+    first_name="John",
+    last_name="Doe",
+    phone="+15551234567",
+    template_id=12345,
+    title="My Campaign"
+)
+```
+
+The message body is resolved server-side from the template. Variable substitution (e.g. `${firstName}`) is applied automatically using the recipient's account data.
+
 ### MMS
 
 ```python
@@ -67,7 +91,6 @@ def track_progress(status):
 # Create options with progress tracking
 options = SMSOptions(
     timeout=60,
-    retries=3,
     on_progress=track_progress
 )
 
@@ -295,22 +318,18 @@ def verify_and_handle_webhook(signature, client_id, event_hash, secret):
         print("Invalid signature")
 
 # Create a webhook handler for web frameworks
-def handle_message_sent(event):
-    print(f"Message sent: {event.message} to {event.to}")
-
-def handle_message_received(event):
-    print(f"Message received: {event.message} from {event.from_}")
+def handle_event(event):
+    if event.event_type == WebhookEventType.MESSAGE_SENT:
+        print(f"Message sent: {event.data.get('Message')} to {event.data.get('To')}")
+    elif event.event_type == WebhookEventType.MESSAGE_RECEIVED:
+        print(f"Message received: {event.data.get('Message')} from {event.data.get('From')}")
 
-handlers = {
-    'on_message_sent': handle_message_sent,
-    'on_message_received': handle_message_received
-}
-
-webhook_handler = ccai.webhook.create_handler(handlers)
+webhook_handler = ccai.webhook.create_handler({'on_event': handle_event})
 
 # Use with Flask
-from flask import Flask, request, jsonify
+import os
 import json
+from flask import Flask, request, jsonify
 
 app = Flask(__name__)
 
@@ -414,6 +433,8 @@ campaign = ccai.campaigns.create({
     "subUseCases": ["CUSTOMER_CARE", "TWO_FACTOR_AUTHENTICATION", "ACCOUNT_NOTIFICATION"],
     "description": "Security codes and support messaging.",
     "messageFlow": "Users opt-in via signup form at https://example.com/signup",
+    "termsLink": "https://example.com/terms",
+    "privacyLink": "https://example.com/privacy",
     "hasEmbeddedLinks": True,
     "hasEmbeddedPhone": False,
     "isAgeGated": False,
@@ -454,6 +475,8 @@ ccai.campaigns.delete(campaign["id"])
 
 > Note: `MIXED` and `LOW_VOLUME_MIXED` campaigns require 2–3 `subUseCases`.
 
+> `termsLink` and `privacyLink` are optional fields on the campaign dict.
+
 #### Sub-Use Cases
 
 `TWO_FACTOR_AUTHENTICATION`, `ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`, `FRAUD_ALERT`, `MARKETING`, `POLLING_VOTING`

{ccai_python-1.1.0 → ccai_python-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ccai-python"
-version = "1.1.0"
+version = "1.2.0"
 description = "Python client for CloudContactAI API"
 readme = "README.md"
 requires-python = ">=3.10"

{ccai_python-1.1.0 → ccai_python-1.2.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='ccai',
-    version='1.1.0',
+    version='1.2.0',
     description='A CLI and Python client for sending SMS via CloudContactAI',
     author='CloudContactAI LLC',
     license='MIT',

{ccai_python-1.1.0 → ccai_python-1.2.0}/src/ccai_python/sms/sms.py

@@ -30,8 +30,9 @@ class Account(BaseModel):
 class SMSCampaign(BaseModel):
     """SMS campaign data model"""
     accounts: List[Account] = Field(..., description="List of recipient accounts")
-    message: str = Field(..., description="Message content with optional variables")
+    message: str = Field(default="", description="Message content with optional variables")
     title: str = Field(..., description="Campaign title")
+    template_id: Optional[int] = Field(default=None, alias="templateId", description="Optional template ID for template-controlled accounts")
 
 
 class SMSResponse(BaseModel):
@@ -99,11 +100,12 @@ class SMS:
         message: str,
         title: str,
         sender_phone: Optional[str] = None,
-        options: Optional[SMSOptions] = None
+        options: Optional[SMSOptions] = None,
+        template_id: Optional[int] = None
     ) -> SMSResponse:
         if not accounts:
             raise ValueError("At least one account is required")
-        if not message:
+        if not message and template_id is None:
             raise ValueError("Message is required")
         if not title:
             raise ValueError("Campaign title is required")
@@ -151,6 +153,8 @@ class SMS:
         }
         if sender_phone:
             payload["senderPhone"] = sender_phone
+        if template_id is not None:
+            payload["templateId"] = template_id
 
         try:
             if options and options.on_progress:
@@ -193,3 +197,28 @@ class SMS:
         )
         return self.send([account], message, title, sender_phone, options)
 
+    def send_with_template(
+        self,
+        accounts: List[Union[Account, Dict[str, str]]],
+        template_id: int,
+        title: str,
+        sender_phone: Optional[str] = None,
+        options: Optional[SMSOptions] = None
+    ) -> SMSResponse:
+        """Send SMS using a pre-approved template (for template-controlled accounts)."""
+        return self.send(accounts, "", title, sender_phone, options, template_id)
+
+    def send_single_with_template(
+        self,
+        first_name: str,
+        last_name: str,
+        phone: str,
+        template_id: int,
+        title: str,
+        sender_phone: Optional[str] = None,
+        options: Optional[SMSOptions] = None
+    ) -> SMSResponse:
+        """Send SMS to a single recipient using a pre-approved template."""
+        account = Account(first_name=first_name, last_name=last_name, phone=phone)
+        return self.send_with_template([account], template_id, title, sender_phone, options)
+

{ccai_python-1.1.0 → ccai_python-1.2.0}/src/ccai_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ccai-python
-Version: 1.1.0
+Version: 1.2.0
 Summary: Python client for CloudContactAI API
 Author: CloudContactAI LLC
 License: MIT
@@ -21,7 +21,7 @@ Dynamic: requires-python
 
 # CCAI Python Client
 
-Version: 1.1.0
+Version: 1.2.0
 
 A Python client for interacting with the CloudContactAI API.
 
@@ -70,6 +70,30 @@ campaign_response = ccai.sms.send(
 print(f"Campaign sent with ID: {campaign_response.campaign_id}")
 ```
 
+### SMS — Template-Controlled Accounts
+
+If an account has been configured to enforce template-only messaging, all campaigns must reference a pre-approved template ID. Sending a free-text message to such an account will result in a `422` error.
+
+```python
+# Send to multiple recipients using a template
+response = ccai.sms.send_with_template(
+    accounts=accounts,
+    template_id=12345,   # the ID of the approved template
+    title="My Campaign"
+)
+
+# Send to a single recipient using a template
+response = ccai.sms.send_single_with_template(
+    first_name="John",
+    last_name="Doe",
+    phone="+15551234567",
+    template_id=12345,
+    title="My Campaign"
+)
+```
+
+The message body is resolved server-side from the template. Variable substitution (e.g. `${firstName}`) is applied automatically using the recipient's account data.
+
 ### MMS
 
 ```python
@@ -88,7 +112,6 @@ def track_progress(status):
 # Create options with progress tracking
 options = SMSOptions(
     timeout=60,
-    retries=3,
     on_progress=track_progress
 )
 
@@ -316,22 +339,18 @@ def verify_and_handle_webhook(signature, client_id, event_hash, secret):
         print("Invalid signature")
 
 # Create a webhook handler for web frameworks
-def handle_message_sent(event):
-    print(f"Message sent: {event.message} to {event.to}")
-
-def handle_message_received(event):
-    print(f"Message received: {event.message} from {event.from_}")
+def handle_event(event):
+    if event.event_type == WebhookEventType.MESSAGE_SENT:
+        print(f"Message sent: {event.data.get('Message')} to {event.data.get('To')}")
+    elif event.event_type == WebhookEventType.MESSAGE_RECEIVED:
+        print(f"Message received: {event.data.get('Message')} from {event.data.get('From')}")
 
-handlers = {
-    'on_message_sent': handle_message_sent,
-    'on_message_received': handle_message_received
-}
-
-webhook_handler = ccai.webhook.create_handler(handlers)
+webhook_handler = ccai.webhook.create_handler({'on_event': handle_event})
 
 # Use with Flask
-from flask import Flask, request, jsonify
+import os
 import json
+from flask import Flask, request, jsonify
 
 app = Flask(__name__)
 
@@ -435,6 +454,8 @@ campaign = ccai.campaigns.create({
     "subUseCases": ["CUSTOMER_CARE", "TWO_FACTOR_AUTHENTICATION", "ACCOUNT_NOTIFICATION"],
     "description": "Security codes and support messaging.",
     "messageFlow": "Users opt-in via signup form at https://example.com/signup",
+    "termsLink": "https://example.com/terms",
+    "privacyLink": "https://example.com/privacy",
     "hasEmbeddedLinks": True,
     "hasEmbeddedPhone": False,
     "isAgeGated": False,
@@ -475,6 +496,8 @@ ccai.campaigns.delete(campaign["id"])
 
 > Note: `MIXED` and `LOW_VOLUME_MIXED` campaigns require 2–3 `subUseCases`.
 
+> `termsLink` and `privacyLink` are optional fields on the campaign dict.
+
 #### Sub-Use Cases
 
 `TWO_FACTOR_AUTHENTICATION`, `ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`, `FRAUD_ALERT`, `MARKETING`, `POLLING_VOTING`

{ccai_python-1.1.0 → ccai_python-1.2.0}/tests/test_sms.py

@@ -289,5 +289,47 @@ class TestSMS(unittest.TestCase):
             )
 
 
+    @patch.object(CCAI, 'request')
+    def test_send_with_template_id(self, mock_request):
+        """Test sending SMS with a template ID"""
+        mock_request.return_value = {
+            "id": "msg-tpl-1",
+            "status": "sent",
+            "campaign_id": "camp-tpl-1"
+        }
+
+        response = self.ccai.sms.send_with_template(
+            accounts=[self.account],
+            template_id=12345,
+            title="Template Campaign"
+        )
+
+        self.assertEqual(response.id, "msg-tpl-1")
+
+        call_args = mock_request.call_args
+        payload = call_args.kwargs.get("data") or call_args[1].get("data")
+        self.assertEqual(payload["templateId"], 12345)
+        self.assertEqual(payload["message"], "")
+
+    @patch.object(CCAI, 'request')
+    def test_send_single_with_template_id(self, mock_request):
+        """Test sending SMS to a single recipient with a template ID"""
+        mock_request.return_value = {"id": "msg-tpl-2", "status": "sent"}
+
+        response = self.ccai.sms.send_single_with_template(
+            first_name="Jane",
+            last_name="Smith",
+            phone="+14156961732",
+            template_id=99,
+            title="Single Template Campaign"
+        )
+
+        self.assertEqual(response.id, "msg-tpl-2")
+
+        call_args = mock_request.call_args
+        payload = call_args.kwargs.get("data") or call_args[1].get("data")
+        self.assertEqual(payload["templateId"], 99)
+
+
 if __name__ == '__main__':
     unittest.main()