feat: add diagnostic fields to message failure webhook events

src/linq/types/attachment_create_response.py

@@ -37,5 +37,7 @@ class AttachmentCreateResponse(BaseModel):
     """Presigned URL for uploading the file.
 
     PUT the raw binary file content to this URL with the `required_headers`. Do not
-    JSON-encode or multipart-wrap the body. Expires after 15 minutes.
+    JSON-encode or multipart-wrap the body. Expires after 15 minutes. Treat the URL
+    as opaque — the hostname depends on partner configuration and is the same across
+    sandbox and production.
     """

src/linq/types/chat.py

@@ -35,9 +35,10 @@ class HealthStatus(BaseModel):
     part of a longer one: `STOP` counts, `please stop` does not. Most keywords must
     match exactly, including case. `OPT OUT` is the exception — it matches in any
     casing, with or without the space or a hyphen, so `opt out`, `Opt-Out` and
-    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP`,
-    or if they keep replying on the chat — sustained two-way conversation is treated
-    as a sign the stop keyword was a false positive.
+    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP` —
+    these match in any casing — or if they keep replying — replies in any
+    conversation with you count, the same way the block does — since sustained
+    two-way conversation is treated as a sign the stop keyword was a false positive.
 
     Linq enforces this: while a recipient is opted out, every send to them is
     rejected with `403` (error code `2024`) before the message is queued, across

src/linq/types/chat_create_response.py

@@ -36,9 +36,10 @@ class ChatHealthStatus(BaseModel):
     part of a longer one: `STOP` counts, `please stop` does not. Most keywords must
     match exactly, including case. `OPT OUT` is the exception — it matches in any
     casing, with or without the space or a hyphen, so `opt out`, `Opt-Out` and
-    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP`,
-    or if they keep replying on the chat — sustained two-way conversation is treated
-    as a sign the stop keyword was a false positive.
+    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP` —
+    these match in any casing — or if they keep replying — replies in any
+    conversation with you count, the same way the block does — since sustained
+    two-way conversation is treated as a sign the stop keyword was a false positive.
 
     Linq enforces this: while a recipient is opted out, every send to them is
     rejected with `403` (error code `2024`) before the message is queued, across

src/linq/types/chat_created_webhook_event.py

@@ -36,9 +36,10 @@ class DataHealthStatus(BaseModel):
     part of a longer one: `STOP` counts, `please stop` does not. Most keywords must
     match exactly, including case. `OPT OUT` is the exception — it matches in any
     casing, with or without the space or a hyphen, so `opt out`, `Opt-Out` and
-    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP`,
-    or if they keep replying on the chat — sustained two-way conversation is treated
-    as a sign the stop keyword was a false positive.
+    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP` —
+    these match in any casing — or if they keep replying — replies in any
+    conversation with you count, the same way the block does — since sustained
+    two-way conversation is treated as a sign the stop keyword was a false positive.
 
     Linq enforces this: while a recipient is opted out, every send to them is
     rejected with `403` (error code `2024`) before the message is queued, across

src/linq/types/chat_group_icon_update_failed_webhook_event.py

@@ -18,7 +18,13 @@ class Data(BaseModel):
     """Chat identifier (UUID) of the group chat"""
 
     error_code: int
-    """Error codes in webhook failure events (3007, 4001, 4005)."""
+    """Error codes in webhook failure events.
+
+    The possible set varies by event: message.failed can carry 3007, 4001, 4002,
+    4005, 4006, 4007, or 4008; the group update failure events
+    (chat.group_name_update_failed, chat.group_icon_update_failed) carry 3007
+    or 4001.
+    """
 
     failed_at: datetime
     """When the failure was detected"""

src/linq/types/chat_group_name_update_failed_webhook_event.py

@@ -18,7 +18,13 @@ class Data(BaseModel):
     """Chat identifier (UUID) of the group chat"""
 
     error_code: int
-    """Error codes in webhook failure events (3007, 4001, 4005)."""
+    """Error codes in webhook failure events.
+
+    The possible set varies by event: message.failed can carry 3007, 4001, 4002,
+    4005, 4006, 4007, or 4008; the group update failure events
+    (chat.group_name_update_failed, chat.group_icon_update_failed) carry 3007
+    or 4001.
+    """
 
     failed_at: datetime
     """When the failure was detected"""

src/linq/types/message_edited_webhook_event.py

@@ -34,9 +34,10 @@ class DataChatHealthStatus(BaseModel):
     part of a longer one: `STOP` counts, `please stop` does not. Most keywords must
     match exactly, including case. `OPT OUT` is the exception — it matches in any
     casing, with or without the space or a hyphen, so `opt out`, `Opt-Out` and
-    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP`,
-    or if they keep replying on the chat — sustained two-way conversation is treated
-    as a sign the stop keyword was a false positive.
+    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP` —
+    these match in any casing — or if they keep replying — replies in any
+    conversation with you count, the same way the block does — since sustained
+    two-way conversation is treated as a sign the stop keyword was a false positive.
 
     Linq enforces this: while a recipient is opted out, every send to them is
     rejected with `403` (error code `2024`) before the message is queued, across

src/linq/types/message_event_v2.py

@@ -49,9 +49,10 @@ class ChatHealthStatus(BaseModel):
     part of a longer one: `STOP` counts, `please stop` does not. Most keywords must
     match exactly, including case. `OPT OUT` is the exception — it matches in any
     casing, with or without the space or a hyphen, so `opt out`, `Opt-Out` and
-    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP`,
-    or if they keep replying on the chat — sustained two-way conversation is treated
-    as a sign the stop keyword was a false positive.
+    `optout` all count. It clears if they later send `START`, `OPTIN`, or `UNSTOP` —
+    these match in any casing — or if they keep replying — replies in any
+    conversation with you count, the same way the block does — since sustained
+    two-way conversation is treated as a sign the stop keyword was a false positive.
 
     Linq enforces this: while a recipient is opted out, every send to them is
     rejected with `403` (error code `2024`) before the message is queued, across

src/linq/types/message_failed_webhook_event.py

@@ -2,9 +2,11 @@
 
 from typing import Optional
 from datetime import datetime
+from typing_extensions import Literal
 
 from .._models import BaseModel
 from .webhook_event_type import WebhookEventType
+from .shared.service_type import ServiceType
 
 __all__ = ["MessageFailedWebhookEvent", "Data"]
 
@@ -18,20 +20,42 @@ class Data(BaseModel):
     """
 
     code: int
-    """Error codes in webhook failure events (3007, 4001, 4005)."""
+    """Error codes in webhook failure events.
+
+    The possible set varies by event: message.failed can carry 3007, 4001, 4002,
+    4005, 4006, 4007, or 4008; the group update failure events
+    (chat.group_name_update_failed, chat.group_icon_update_failed) carry 3007
+    or 4001.
+    """
 
     failed_at: datetime
     """When the failure was detected"""
 
     chat_id: Optional[str] = None
     """Chat identifier (UUID)"""
 
+    detail_code: Optional[int] = None
+    """
+    Opaque diagnostic code identifying the specific failure class within `code`.
+    Values are not enumerated and may change without notice — log it and include it
+    in support requests, but do not branch on it.
+    """
+
     message_id: Optional[str] = None
     """Message identifier (UUID)"""
 
+    preferred_service: Optional[Literal["iMessage", "SMS", "RCS", "auto"]] = None
+    """Preferred messaging service type.
+
+    Includes "auto" for default fallback behavior.
+    """
+
     reason: Optional[str] = None
     """Human-readable description of the failure"""
 
+    service: Optional[ServiceType] = None
+    """Messaging service type"""
+
 
 class MessageFailedWebhookEvent(BaseModel):
     """Complete webhook payload for message.failed events"""