DEVEXP-794: Conversation Messages Send - Snippets

MIGRATION_GUIDE.md

@@ -93,6 +93,39 @@ sinch_client = SinchClient(
 sinch_client.configuration.conversation_region = "eu"
 ```
 
+### [`Conversation`](https://github.com/sinch/sinch-sdk-python/tree/main/sinch/domains/conversation)
+
+#### Replacement models
+
+##### Messages (send, get, delete, list)
+
+| Old class | New class |
+|-----------|-----------|
+| `sinch.domains.conversation.models.message.requests.SendConversationMessageRequest` | `send()`: pass `app_id`, `message` (dict or [`SendMessageRequestBodyDict`](sinch/domains/conversation/models/v1/messages/types/send_message_request_body_dict.py)), and either `contact_id` or `recipient_identities`. Internally uses [`SendMessageRequest`](sinch/domains/conversation/models/v1/messages/internal/request/send_message_request.py), [`SendMessageRequestBody`](sinch/domains/conversation/models/v1/messages/internal/request/send_message_request_body.py). For typed payloads use `send_text_message()`, `send_card_message()`, etc.
+| `sinch.domains.conversation.models.message.responses.SendConversationMessageResponse` | [`SendMessageResponse`](sinch/domains/conversation/models/v1/messages/response/types/send_message_response.py) (`message_id`, optional `accepted_time` as `datetime`) |
+| `sinch.domains.conversation.models.message.requests.GetConversationMessageRequest` | `get(message_id, messages_source=None, **kwargs)`. Internally uses [`MessageIdRequest`](sinch/domains/conversation/models/v1/messages/internal/request/message_id_request.py). |
+| `sinch.domains.conversation.models.message.responses.GetConversationMessageResponse` | [`ConversationMessageResponse`](sinch/domains/conversation/models/v1/messages/response/types/__init__.py) (Union of app/contact message response types) |
+| `sinch.domains.conversation.models.message.requests.DeleteConversationMessageRequest` | `delete(message_id, messages_source=None, **kwargs)`. Internally uses [`MessageIdRequest`](sinch/domains/conversation/models/v1/messages/internal/request/message_id_request.py). |
+| `sinch.domains.conversation.models.message.responses.DeleteConversationMessageResponse` | `None` (method returns `None`) |
+| `sinch.domains.conversation.models.message.requests.ListConversationMessagesRequest` | `list()` with individual parameters: `conversation_id`, `contact_id`, `app_id`, `page_size`, `page_token`, `view`, `messages_source`, `only_recipient_originated` (signature aligned with V1 where available) |
+| `sinch.domains.conversation.models.message.responses.ListConversationMessagesResponse` | Response type for `list()` (messages list, next_page_token) |
+
+#### Replacement APIs
+
+The Conversation domain API access remains `sinch_client.conversation`; message operations are under `sinch_client.conversation.messages`. Recipient is specified with exactly one of `contact_id` or `recipient_identities` (list of `{channel, identity}`).
+
+##### Messages API
+
+| Old method | New method in `conversation.messages` |
+|------------|----------------------------------------|
+| `send()` with `SendConversationMessageRequest` | Use convenience methods: `send_text_message()`, `send_card_message()`, `send_carousel_message()`, `send_choice_message()`, `send_contact_info_message()`, `send_list_message()`, `send_location_message()`, `send_media_message()`, `send_template_message()`<br>Or `send()` with `app_id`, `message` (dict or `SendMessageRequestBodyDict`), and either `contact_id` or `recipient_identities` |
+| `get()` with `GetConversationMessageRequest` | `get()` with `message_id: str` parameter |
+| `delete()` with `DeleteConversationMessageRequest` | `delete()` with `message_id: str` parameter |
+| `list()` with `ListConversationMessagesRequest` | In Progress |
+| — |  **New in V2:** `update()` with `message_id`, `metadata`, and optional `messages_source`|
+
+<br>
+
 ### [`SMS`](https://github.com/sinch/sinch-sdk-python/tree/main/sinch/domains/sms)
 
 #### Replacement models

examples/snippets/conversation/messages/send/snippet.py

@@ -0,0 +1,41 @@
+"""
+Sinch Python Snippet
+
+TODO: Update links when v2 is released.
+This snippet is available at https://github.com/sinch/sinch-sdk-python/blob/v2.0/docs/snippets/
+"""
+
+import os
+from dotenv import load_dotenv
+from sinch import SinchClient
+
+load_dotenv()
+
+sinch_client = SinchClient(
+    project_id=os.environ.get("SINCH_PROJECT_ID") or "MY_PROJECT_ID",
+    key_id=os.environ.get("SINCH_KEY_ID") or "MY_KEY_ID",
+    key_secret=os.environ.get("SINCH_KEY_SECRET") or "MY_KEY_SECRET",
+    conversation_region=os.environ.get("SINCH_CONVERSATION_REGION") or "MY_CONVERSATION_REGION"
+)
+
+# The ID of the Conversation App to send the message from
+app_id = "CONVERSATION_APP_ID"
+# The phone number of the recipient in E.164 format (e.g. +46701234567)
+recipient_identities = [
+    {
+        "channel": "RCS",
+        "identity": "RECIPIENT_PHONE_NUMBER"
+    }
+]
+
+response = sinch_client.conversation.messages.send(
+    app_id=app_id,
+    message={
+        "text_message": {
+            "text": "[Python SDK: Conversation Message] Sample text message"
+        }
+    },
+    recipient_identities=recipient_identities
+)
+
+print(f"Successfully sent message.\n{response}")

examples/snippets/conversation/messages/send_card_message/snippet.py

@@ -0,0 +1,46 @@
+"""
+Sinch Python Snippet
+
+TODO: Update links when v2 is released.
+This snippet is available at https://github.com/sinch/sinch-sdk-python/blob/v2.0/docs/snippets/
+"""
+
+import os
+from dotenv import load_dotenv
+from sinch import SinchClient
+
+load_dotenv()
+
+sinch_client = SinchClient(
+    project_id=os.environ.get("SINCH_PROJECT_ID") or "MY_PROJECT_ID",
+    key_id=os.environ.get("SINCH_KEY_ID") or "MY_KEY_ID",
+    key_secret=os.environ.get("SINCH_KEY_SECRET") or "MY_KEY_SECRET",
+    conversation_region=os.environ.get("SINCH_CONVERSATION_REGION") or "MY_CONVERSATION_REGION"
+)
+
+# The ID of the Conversation App to send the message from
+app_id = "CONVERSATION_APP_ID"
+# The phone number of the recipient in E.164 format (e.g. +46701234567)
+recipient_identities = [
+    {
+        "channel": "RCS",
+        "identity": "RECIPIENT_PHONE_NUMBER"
+    }
+]
+
+card_message = {
+    "title": "Card title",
+    "description": "Optional card description",
+    "choices": [
+        {"text_message": {"text": "Yes"}, "postback_data": "yes"},
+        {"text_message": {"text": "No"}, "postback_data": "no"},
+    ]
+}
+
+response = sinch_client.conversation.messages.send_card_message(
+    app_id=app_id,
+    card_message=card_message,
+    recipient_identities=recipient_identities
+)
+
+print(f"Successfully sent card message.\n{response}")

examples/snippets/conversation/messages/send_carousel_message/snippet.py

@@ -0,0 +1,52 @@
+"""
+Sinch Python Snippet
+
+TODO: Update links when v2 is released.
+This snippet is available at https://github.com/sinch/sinch-sdk-python/blob/v2.0/docs/snippets/
+"""
+
+import os
+from dotenv import load_dotenv
+from sinch import SinchClient
+
+load_dotenv()
+
+sinch_client = SinchClient(
+    project_id=os.environ.get("SINCH_PROJECT_ID") or "MY_PROJECT_ID",
+    key_id=os.environ.get("SINCH_KEY_ID") or "MY_KEY_ID",
+    key_secret=os.environ.get("SINCH_KEY_SECRET") or "MY_KEY_SECRET",
+    conversation_region=os.environ.get("SINCH_CONVERSATION_REGION") or "MY_CONVERSATION_REGION"
+)
+
+# The ID of the Conversation App to send the message from
+app_id = "CONVERSATION_APP_ID"
+# The phone number of the recipient in E.164 format (e.g. +46701234567)
+recipient_identities = [
+    {
+        "channel": "RCS",
+        "identity": "RECIPIENT_PHONE_NUMBER"
+    }
+]
+
+carousel_message = {
+    "cards": [
+        {
+            "title": "Card 1",
+            "description": "First card description",
+            "choices": [{"text_message": {"text": "Option 1"}}],
+        },
+        {
+            "title": "Card 2",
+            "description": "Second card description",
+            "choices": [{"url_message": {"title": "Link", "url": "https://example.com"}}],
+        },
+    ],
+}
+
+response = sinch_client.conversation.messages.send_carousel_message(
+    app_id=app_id,
+    carousel_message=carousel_message,
+    recipient_identities=recipient_identities
+)
+
+print(f"Successfully sent carousel message.\n{response}")

examples/snippets/conversation/messages/send_choice_message/snippet.py

@@ -0,0 +1,45 @@
+"""
+Sinch Python Snippet
+
+TODO: Update links when v2 is released.
+This snippet is available at https://github.com/sinch/sinch-sdk-python/blob/v2.0/docs/snippets/
+"""
+
+import os
+from dotenv import load_dotenv
+from sinch import SinchClient
+
+load_dotenv()
+
+sinch_client = SinchClient(
+    project_id=os.environ.get("SINCH_PROJECT_ID") or "MY_PROJECT_ID",
+    key_id=os.environ.get("SINCH_KEY_ID") or "MY_KEY_ID",
+    key_secret=os.environ.get("SINCH_KEY_SECRET") or "MY_KEY_SECRET",
+    conversation_region=os.environ.get("SINCH_CONVERSATION_REGION") or "MY_CONVERSATION_REGION"
+)
+
+# The ID of the Conversation App to send the message from
+app_id = "CONVERSATION_APP_ID"
+# The phone number of the recipient in E.164 format (e.g. +46701234567)
+recipient_identities = [
+    {
+        "channel": "RCS",
+        "identity": "RECIPIENT_PHONE_NUMBER"
+    }
+]
+
+choice_message = {
+    "text_message": {"text": "Choose an option:"},
+    "choices": [
+        {"text_message": {"text": "Option A"}, "postback_data": "option_a"},
+        {"text_message": {"text": "Option B"}, "postback_data": "option_b"},
+    ],
+}
+
+response = sinch_client.conversation.messages.send_choice_message(
+    app_id=app_id,
+    choice_message=choice_message,
+    recipient_identities=recipient_identities
+)
+
+print(f"Successfully sent choice message.\n{response}")

examples/snippets/conversation/messages/send_contact_info_message/snippet.py

@@ -0,0 +1,42 @@
+"""
+Sinch Python Snippet
+
+TODO: Update links when v2 is released.
+This snippet is available at https://github.com/sinch/sinch-sdk-python/blob/v2.0/docs/snippets/
+"""
+
+import os
+from dotenv import load_dotenv
+from sinch import SinchClient
+
+load_dotenv()
+
+sinch_client = SinchClient(
+    project_id=os.environ.get("SINCH_PROJECT_ID") or "MY_PROJECT_ID",
+    key_id=os.environ.get("SINCH_KEY_ID") or "MY_KEY_ID",
+    key_secret=os.environ.get("SINCH_KEY_SECRET") or "MY_KEY_SECRET",
+    conversation_region=os.environ.get("SINCH_CONVERSATION_REGION") or "MY_CONVERSATION_REGION"
+)
+
+# The ID of the Conversation App to send the message from
+app_id = "CONVERSATION_APP_ID"
+# The phone number of the recipient in E.164 format (e.g. +46701234567)
+recipient_identities = [
+    {
+        "channel": "RCS",
+        "identity": "RECIPIENT_PHONE_NUMBER"
+    }
+]
+
+contact_info_message = {
+    "name": {"full_name": "John Doe"},
+    "phone_numbers": [{"phone_number": "+1234567890"}],
+}
+
+response = sinch_client.conversation.messages.send_contact_info_message(
+    app_id=app_id,
+    contact_info_message=contact_info_message,
+    recipient_identities=recipient_identities
+)
+
+print(f"Successfully sent contact info message.\n{response}")

examples/snippets/conversation/messages/send_list_message/snippet.py

@@ -0,0 +1,51 @@
+"""
+Sinch Python Snippet
+
+TODO: Update links when v2 is released.
+This snippet is available at https://github.com/sinch/sinch-sdk-python/blob/v2.0/docs/snippets/
+"""
+
+import os
+from dotenv import load_dotenv
+from sinch import SinchClient
+
+load_dotenv()
+
+sinch_client = SinchClient(
+    project_id=os.environ.get("SINCH_PROJECT_ID") or "MY_PROJECT_ID",
+    key_id=os.environ.get("SINCH_KEY_ID") or "MY_KEY_ID",
+    key_secret=os.environ.get("SINCH_KEY_SECRET") or "MY_KEY_SECRET",
+    conversation_region=os.environ.get("SINCH_CONVERSATION_REGION") or "MY_CONVERSATION_REGION"
+)
+
+# The ID of the Conversation App to send the message from
+app_id = "CONVERSATION_APP_ID"
+# The phone number of the recipient in E.164 format (e.g. +46701234567)
+recipient_identities = [
+    {
+        "channel": "RCS",
+        "identity": "RECIPIENT_PHONE_NUMBER"
+    }
+]
+
+list_message = {
+    "title": "Choose an option",
+    "description": "Select from the list below",
+    "sections": [
+        {
+            "title": "Section 1",
+            "items": [
+                {"choice": {"title": "Option A", "postback_data": "option_a"}},
+                {"choice": {"title": "Option B", "postback_data": "option_b"}},
+            ],
+        },
+    ],
+}
+
+response = sinch_client.conversation.messages.send_list_message(
+    app_id=app_id,
+    list_message=list_message,
+    recipient_identities=recipient_identities
+)
+
+print(f"Successfully sent list message.\n{response}")

examples/snippets/conversation/messages/send_location_message/snippet.py

@@ -0,0 +1,42 @@
+"""
+Sinch Python Snippet
+
+TODO: Update links when v2 is released.
+This snippet is available at https://github.com/sinch/sinch-sdk-python/blob/v2.0/docs/snippets/
+"""
+
+import os
+from dotenv import load_dotenv
+from sinch import SinchClient
+
+load_dotenv()
+
+sinch_client = SinchClient(
+    project_id=os.environ.get("SINCH_PROJECT_ID") or "MY_PROJECT_ID",
+    key_id=os.environ.get("SINCH_KEY_ID") or "MY_KEY_ID",
+    key_secret=os.environ.get("SINCH_KEY_SECRET") or "MY_KEY_SECRET",
+    conversation_region=os.environ.get("SINCH_CONVERSATION_REGION") or "MY_CONVERSATION_REGION"
+)
+
+# The ID of the Conversation App to send the message from
+app_id = "CONVERSATION_APP_ID"
+# The phone number of the recipient in E.164 format (e.g. +46701234567)
+recipient_identities = [
+    {
+        "channel": "RCS",
+        "identity": "RECIPIENT_PHONE_NUMBER"
+    }
+]
+
+location_message = {
+    "title": "Our office",
+    "coordinates": {"latitude": 59.3293, "longitude": 18.0686},
+}
+
+response = sinch_client.conversation.messages.send_location_message(
+    app_id=app_id,
+    location_message=location_message,
+    recipient_identities=recipient_identities
+)
+
+print(f"Successfully sent location message.\n{response}")