feat(api): sync OpenAPI spec from production

Stainless-Generated-From: b3fade88d1c6d48ba3a7258b330ae352c62db4df

Author: stlc-bot

src/sent_dm/resources/templates.py

@@ -78,7 +78,9 @@ def create(
 
         The
         template can be submitted for review immediately or saved as draft for later
-        submission.
+        submission. There is no `name` field on create — the display name is derived
+        from the template's content and can be changed afterwards with
+        `PUT /v3/templates/{id}`.
 
         Args:
           category: Template category: MARKETING, UTILITY, AUTHENTICATION (optional, auto-detected
@@ -190,7 +192,31 @@ def update(
     ) -> APIResponseTemplate:
         """
         Updates an existing template's name, category, language, definition, or submits
-        it for review.
+        it for review. While the template is in review (status PENDING, or any channel
+        awaiting a verdict) its definition, category and language are frozen and a
+        resubmission is refused — those requests answer 409 CONFLICT_006. The display
+        name stays editable throughout.
+
+        `definition`, `category` and `language` are editable only from status DRAFT,
+        REJECTED or APPROVED. An edit to any of them on a template in another state
+        (PAUSED, DISABLED or REVOKED) is refused with 400 VALIDATION_001 and the detail
+        "Template (except display name) cannot be updated unless it is in draft or
+        rejected status"; `name` stays editable in every state. `submit_for_review` on a
+        PAUSED, DISABLED or REVOKED template is accepted and answers 200, but opens no
+        review and does not move the status — only the reviewer can reinstate it.
+
+        Editing an APPROVED template is a live edit: the new content is stored
+        immediately, and sending `submit_for_review: true` re-opens review, which
+        returns the affected channels to PENDING so they stop sending until they are
+        approved again. The previously approved content is never sent during re-review.
+        Watch the per-channel `templates` webhook events rather than assuming the
+        template-level status.
+
+        Templates provisioned by Sent (light-onboarding templates, whose names carry the
+        reserved `sent_` prefix) are read-only: every field is refused with 400
+        VALIDATION*001 and the detail "This template is read-only. Only 'submit for
+        review' is allowed.", and only `submit_for_review` is accepted. A `name`
+        starting with `sent*` is refused for the same reason — the prefix is reserved.
 
         Args:
           category: Template category: MARKETING, UTILITY, AUTHENTICATION
@@ -416,7 +442,9 @@ async def create(
 
         The
         template can be submitted for review immediately or saved as draft for later
-        submission.
+        submission. There is no `name` field on create — the display name is derived
+        from the template's content and can be changed afterwards with
+        `PUT /v3/templates/{id}`.
 
         Args:
           category: Template category: MARKETING, UTILITY, AUTHENTICATION (optional, auto-detected
@@ -528,7 +556,31 @@ async def update(
     ) -> APIResponseTemplate:
         """
         Updates an existing template's name, category, language, definition, or submits
-        it for review.
+        it for review. While the template is in review (status PENDING, or any channel
+        awaiting a verdict) its definition, category and language are frozen and a
+        resubmission is refused — those requests answer 409 CONFLICT_006. The display
+        name stays editable throughout.
+
+        `definition`, `category` and `language` are editable only from status DRAFT,
+        REJECTED or APPROVED. An edit to any of them on a template in another state
+        (PAUSED, DISABLED or REVOKED) is refused with 400 VALIDATION_001 and the detail
+        "Template (except display name) cannot be updated unless it is in draft or
+        rejected status"; `name` stays editable in every state. `submit_for_review` on a
+        PAUSED, DISABLED or REVOKED template is accepted and answers 200, but opens no
+        review and does not move the status — only the reviewer can reinstate it.
+
+        Editing an APPROVED template is a live edit: the new content is stored
+        immediately, and sending `submit_for_review: true` re-opens review, which
+        returns the affected channels to PENDING so they stop sending until they are
+        approved again. The previously approved content is never sent during re-review.
+        Watch the per-channel `templates` webhook events rather than assuming the
+        template-level status.
+
+        Templates provisioned by Sent (light-onboarding templates, whose names carry the
+        reserved `sent_` prefix) are read-only: every field is refused with 400
+        VALIDATION*001 and the detail "This template is read-only. Only 'submit for
+        review' is allowed.", and only `submit_for_review` is accepted. A `name`
+        starting with `sent*` is refused for the same reason — the prefix is reserved.
 
         Args:
           category: Template category: MARKETING, UTILITY, AUTHENTICATION

src/sent_dm/types/inbound_message_event.py

@@ -17,13 +17,13 @@ class InboundMessageEvent(BaseModel):
 
     event: Optional[str] = None
     """
-    The specific event within the family, for example message.delivered or
-    message.received. Absent on events that have no subtype, so treat it as
-    optional.
+    The specific event within the family, for example message.delivered,
+    message.received or contact.opt_out. Absent on events that have no subtype, so
+    treat it as optional.
     """
 
     field: Optional[str] = None
-    """The event family, for example message or templates.
+    """The event family, for example message, templates or contact.
 
     Route on this first, then on event for the specific change.
     """
@@ -34,6 +34,9 @@ class InboundMessageEvent(BaseModel):
     Delivered when a contact messages one of your numbers.
     """
 
+    request_id: Optional[str] = None
+    """The event-specific body."""
+
     timestamp: Optional[str] = None
     """When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ).
 

src/sent_dm/types/message_event.py

@@ -17,13 +17,13 @@ class MessageEvent(BaseModel):
 
     event: Optional[str] = None
     """
-    The specific event within the family, for example message.delivered or
-    message.received. Absent on events that have no subtype, so treat it as
-    optional.
+    The specific event within the family, for example message.delivered,
+    message.received or contact.opt_out. Absent on events that have no subtype, so
+    treat it as optional.
     """
 
     field: Optional[str] = None
-    """The event family, for example message or templates.
+    """The event family, for example message, templates or contact.
 
     Route on this first, then on event for the specific change.
     """
@@ -35,6 +35,9 @@ class MessageEvent(BaseModel):
     as it moves toward a terminal status.
     """
 
+    request_id: Optional[str] = None
+    """The event-specific body."""
+
     timestamp: Optional[str] = None
     """When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ).
 

src/sent_dm/types/message_event_payload.py

@@ -27,6 +27,14 @@ class MessageEventPayload(BaseModel):
     agent_id: Optional[str] = None
     """The agent attributed to the send, when the send was attributed to one."""
 
+    body: Optional[str] = None
+    """The rendered message body, as plain text.
+
+    Sent as null when we aren't asserting a body for this event. The field is always
+    present, so read it and check for null rather than checking whether the key
+    exists. Truncated to 3072 characters.
+    """
+
     channel: Optional[str] = None
     """The channel the message went out on, for example sms or whatsapp.
 

src/sent_dm/types/template.py

@@ -20,11 +20,40 @@ class Template(BaseModel):
     id: Optional[str] = None
     """Unique template identifier"""
 
+    auto_reply_action: Optional[str] = None
+    """
+    Which consent keyword this template answers, when it is one of Sent's
+    auto-replies: OPT_IN, OPT_OUT, HELP, or OTHER for a customer-defined keyword.
+    Null for an ordinary template, and omitted from the response, so its presence is
+    the answer to "is this an auto-reply".
+
+    Deliberately not required, unlike CustomerId, even though the same "no single
+    mapper" argument applies: NJsonSchema publishes a C# required member in the
+    schema's required array, so the contract would have advertised a field this
+    response omits for every ordinary template, and a generated client could refuse
+    the common case. A compile-time guard is not worth a wrong published contract.
+    Every mapping site sets it explicitly, and TemplateResponseSchemaTests pins the
+    field as optional so it cannot be reintroduced.
+    """
+
     category: Optional[str] = None
     """Template category: MARKETING, UTILITY, AUTHENTICATION"""
 
     channels: Optional[List[str]] = None
-    """Supported channels: sms, whatsapp"""
+    """
+    The channels this template's definition can render on, in canonical order: sms,
+    whatsapp, rcs.
+
+    Derived from the definition's body, mirroring each channel's send-time fallback
+    chain, so a channel is listed only when a real body would be produced for it:
+    SMS reads sms ?? multiChannel, WhatsApp reads whatsapp ?? multiChannel, and RCS
+    reads rcs ?? multiChannel ?? sms. A multiChannel body therefore reports all
+    three, and the extra SMS fallback on RCS is why an sms/whatsapp pair reports RCS
+    too.
+
+    This says what the content can render on, not what may be sent: sending also
+    needs the template approved for that channel.
+    """
 
     created_at: Optional[datetime] = None
     """When the template was created"""
@@ -39,7 +68,11 @@ class Template(BaseModel):
     """Template display name"""
 
     status: Optional[str] = None
-    """Template status: APPROVED, PENDING, REJECTED"""
+    """Template status: DRAFT, PENDING, APPROVED, REJECTED.
+
+    A template created with submit_for_review: false starts as DRAFT and stays there
+    until it is submitted.
+    """
 
     updated_at: Optional[datetime] = None
     """When the template was last updated"""

src/sent_dm/types/template_body_content_param.py

@@ -12,7 +12,40 @@
 
 class TemplateBodyContentParam(TypedDict, total=False):
     template: Required[str]
+    """The body copy, with variables written as {{index:variable}}.
+
+    Length cap depends on which channel this body belongs to:
+    TemplateContentLimits.MaxBodyLength (1024) for multiChannel, sms and whatsapp —
+    Meta's BODY limit, which a multiChannel body may be delivered under — and
+    TemplateContentLimits.MaxRcsBodyLength (3072) for an rcs body, which never
+    reaches Meta. The maxLength advertised on this schema is the 1024 one, because
+    all four channel bodies share this single schema — an rcs body between the two
+    is accepted.
+
+    Meta requires every variable to carry surrounding context, so a body is refused
+    unless it also satisfies all of the following (enforced by
+    TemplateDefinitionValidator): At least one letter before the first variable and
+    after the last — trailing punctuation such as "... {{1:variable}}." does not
+    count. At least (2 × variable count) + 1 words once the placeholders are
+    removed. No two variables adjacent with only whitespace between them. No leading
+    or trailing newline, no more than two consecutive line breaks, and no more than
+    four consecutive spaces.
+
+    Example: "Hello {{0:variable}}! Welcome to {{1:variable}}. We are glad to have
+    you on board." — two variables, so at least five words are required, and the
+    copy after the final variable contains letters.
+    """
 
     type: Optional[str]
+    """The type of body content — send "text".
+
+    It is dropped from the stored definition when null, so a body posted without it
+    is saved with no type key at all and the template editor has nothing to render
+    the block from.
+    """
 
     variables: Optional[Iterable[TemplateVariableParam]]
+    """
+    The variables referenced by the body copy, one entry per {{index:variable}}
+    placeholder.
+    """

src/sent_dm/types/template_body_param.py

@@ -12,22 +12,35 @@
 
 
 class TemplateBodyParam(TypedDict, total=False):
-    """Body section of a message template with channel-specific content"""
+    """
+    Body section of a message template.
 
-    multi_channel: Annotated[Optional[TemplateBodyContentParam], PropertyInfo(alias="multiChannel")]
+    A body picks one of two authoring strategies, and mixing them is refused
+    (TemplateDefinitionValidator.HaveValidChannelConfiguration):
+    a shared multiChannel body on its own, or
+    an explicit sms + whatsapp pair, both present.
+
+    multiChannel together with sms or whatsapp is rejected, and so is
+    sms or whatsapp on its own — every template is expected to be deliverable on every
+    channel. rcs is the one true override: it may accompany either strategy to vary the copy,
+    but cannot stand alone.
     """
-    Content that will be used for all channels (SMS and WhatsApp) unless
-    channel-specific content is provided
+
+    multi_channel: Annotated[Optional[TemplateBodyContentParam], PropertyInfo(alias="multiChannel")]
+    """The shared body, used for every channel.
+
+    One half of the choice described above.
     """
 
     rcs: Optional[TemplateBodyContentParam]
-    """RCS-specific content that overrides multi-channel content for RCS messages"""
+    """RCS-specific copy that overrides the chosen strategy for RCS only.
+
+    The one true override: optional on top of either strategy, but it cannot be the
+    only body present. Its length cap is the higher one described on Template.
+    """
 
     sms: Optional[TemplateBodyContentParam]
-    """SMS-specific content that overrides multi-channel content for SMS messages"""
+    """The SMS body. It does not override multiChannel, it replaces it."""
 
     whatsapp: Optional[TemplateBodyContentParam]
-    """
-    WhatsApp-specific content that overrides multi-channel content for WhatsApp
-    messages
-    """
+    """The WhatsApp body. It does not override multiChannel, it replaces it."""

src/sent_dm/types/template_button_param.py

@@ -21,4 +21,11 @@ class TemplateButtonParam(TypedDict, total=False):
     """
 
     id: int
-    """The unique identifier of the button (1-based index)"""
+    """The button's identifier (1-based index), unique within the template.
+
+    Omitting it is only safe for a template holding a single button. The field is a
+    non-nullable int, so every button that leaves it out defaults to 0, and two such
+    buttons are refused by the unique-id rule ("Button IDs must be unique"). Number
+    them from 1 in the order they should appear — order matters on RCS, where only
+    the first four buttons render.
+    """

src/sent_dm/types/template_button_props_param.py

@@ -23,6 +23,20 @@ class TemplateButtonPropsParam(TypedDict, total=False):
     quick_reply_type: Required[Annotated[str, PropertyInfo(alias="quickReplyType")]]
 
     text: Required[str]
+    """The button's label.
+
+    Required for every button type, and capped at
+    TemplateContentLimits.MaxButtonTextLength (25) characters.
+
+    Meta accepts only static text here, so a label is refused when it contains a
+    {{...}} variable placeholder, a newline, an emoji, or WhatsApp formatting markup
+    (\\**, \\__, ~) — enforced by ApplyButtonLabelContentRules in
+    TemplateButtonValidator. Meta reports all four as one error: "Buttons can't have
+    any variables, newlines, emojis, or formatting characters."
+
+    AUTHENTICATION OTP buttons are the exception: Meta auto-localizes their label
+    from the template language, and the converter drops whatever text was sent.
+    """
 
     url: Required[str]
 

src/sent_dm/types/template_definition_param.py

@@ -21,7 +21,17 @@ class TemplateDefinitionParam(TypedDict, total=False):
     """
 
     body: Required[TemplateBodyParam]
-    """Body section of a message template with channel-specific content"""
+    """Body section of a message template.
+
+    A body picks one of two authoring strategies, and mixing them is refused
+    (TemplateDefinitionValidator.HaveValidChannelConfiguration): a shared
+    multiChannel body on its own, or an explicit sms + whatsapp pair, both present.
+
+    multiChannel together with sms or whatsapp is rejected, and so is sms or
+    whatsapp on its own — every template is expected to be deliverable on every
+    channel. rcs is the one true override: it may accompany either strategy to vary
+    the copy, but cannot stand alone.
+    """
 
     authentication_config: Annotated[Optional[AuthenticationConfigParam], PropertyInfo(alias="authenticationConfig")]
     """Configuration for AUTHENTICATION category templates"""