@sentdm/sentdm 0.39.0 → 0.41.0

package/src/resources/messages.ts

@@ -13,11 +13,15 @@ import { path } from '../internal/utils/path';
  * One endpoint sends on any channel: pass `channel: "sent"` and we pick between SMS, WhatsApp and RCS per recipient using your routing rules, or name a channel to pin it. A send is accepted asynchronously — `POST /v3/messages` returns an id, and delivery is reported through `GET /v3/messages/{id}`, its activities, or a webhook.
  *
  * **A message needs a sender.** What you can send, where, and at what cost is decided by the markets under **Channels** — so a recipient in a country you hold no sender for is refused here rather than queued.
+ *
+ * **A message can be resent on its id.** `POST /v3/messages/{id}/resend` puts a finished message — typically one BLOCKED for insufficient balance — back through the send pipeline. It is a new attempt, not a free retry: every policy runs again, the message is billed again, and its status webhooks fire again. A FILTERED message is never resendable.
  */
 export class Messages extends APIResource {
   /**
    * Retrieves the activity log for a specific message. Activities track the message
-   * lifecycle including acceptance, processing, sending, delivery, and any errors.
+   * lifecycle including acceptance, processing, sending, delivery, and any errors. A
+   * SCHEDULED entry carries scheduled_at, the release instant in UTC as it stood at
+   * that moment. Other entries have no scheduled_at key.
    *
    * @example
    * ```ts
@@ -43,7 +47,11 @@ export class Messages extends APIResource {
 
   /**
    * Retrieves the current status and details of a message by ID. Includes delivery
-   * status, timestamps, and error information if applicable.
+   * status, timestamps, and error information if applicable. A message that is or
+   * was held for a later time (a send you scheduled with scheduled_at, or a
+   * quiet-hours hold) is returned as a ScheduledMessageResponse: the same fields
+   * plus scheduled_at, the release instant in UTC. A message sent immediately has no
+   * scheduled_at key.
    *
    * @example
    * ```ts
@@ -77,7 +85,17 @@ export class Messages extends APIResource {
    * insufficient balance, a template not approved for sending, or free-form content
    * with no open conversation with the contact. The send is accepted with 202 and
    * the affected messages are reported as BLOCKED on GET /messages/{id} and the
-   * message.blocked webhook.
+   * message.blocked webhook. To send later, set scheduled_at (ISO-8601 with an
+   * explicit UTC offset; a value without one is rejected) between 1 minute and 30
+   * days ahead: the response is a ScheduledSendMessageResponse (the same fields plus
+   * scheduled_at; status is still QUEUED), each message then moves to SCHEDULED, is
+   * held and released at that time (within a few minutes), and a message.scheduled
+   * webhook fires once it is held. Balance and template approval are evaluated at
+   * release, not at acceptance. Quiet hours are not checked when the request is
+   * accepted: if the time falls inside a legally protected quiet-hours window for a
+   * recipient, that message is moved to the next allowed time at release and a
+   * second message.scheduled webhook reports the new scheduled_at. An account may
+   * hold at most 1,000,000 scheduled messages at once (429 LIMIT_001).
    *
    * @example
    * ```ts
@@ -148,7 +166,11 @@ export namespace MessageRetrieveActivitiesResponse {
 
   export namespace Data {
     /**
-     * A single message activity event for v3 API
+     * A single message activity event for v3 API.
+     *
+     * The activity list mixes statuses, so unlike a message it is one shape rather
+     * than two: a SCHEDULED entry carries scheduled_at, and every other entry has no
+     * such key.
      */
     export interface Activity {
       /**
@@ -176,8 +198,31 @@ export namespace MessageRetrieveActivitiesResponse {
       price?: string | null;
 
       /**
-       * Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SENT, DELIVERED, READ,
-       * FAILED. Inbound (from contact): RECEIVED (terminal).
+       * A human-readable sentence for reason_code, for example "The recipient is not
+       * registered on this channel" Omitted whenever reason_code is.
+       */
+      reason?: string | null;
+
+      /**
+       * Why the message reached this status, as a stable platform code such as
+       * DELIVERY_007 or BUSINESS_003. Present on FAILED, FILTERED and BLOCKED
+       * activities; omitted on every status that needs no explanation. Switch on this
+       * rather than on reason: the code is stable, the wording may be improved. Same
+       * wire name and vocabulary as on the message and the webhook.
+       */
+      reason_code?: string | null;
+
+      /**
+       * SCHEDULED activities only: when the held message will be released for delivery,
+       * in UTC. Same wire name as on the send response, the message and the webhook.
+       * Omitted on every other activity. A message that quiet hours moved at release has
+       * two SCHEDULED entries, each carrying the instant as it stood at that moment.
+       */
+      scheduled_at?: string | null;
+
+      /**
+       * Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SCHEDULED, SENT,
+       * DELIVERED, READ, FAILED. Inbound (from contact): RECEIVED (terminal).
        */
       status?: string;
 
@@ -194,7 +239,12 @@ export namespace MessageRetrieveActivitiesResponse {
  */
 export interface MessageRetrieveStatusResponse {
   /**
-   * Message response for v3 API — same shape as v2 with snake_case JSON conventions
+   * Message response for v3 API — same shape as v2 with snake_case JSON conventions.
+   *
+   * The shape of a message that was sent immediately: it never has a scheduled_at
+   * key. A message that is or was held for a later instant is a
+   * ScheduledMessageResponse, and the endpoint decides which of the two to answer
+   * with. From always returns this type.
    */
   data?: MessageRetrieveStatusResponse.Data | null;
 
@@ -216,7 +266,12 @@ export interface MessageRetrieveStatusResponse {
 
 export namespace MessageRetrieveStatusResponse {
   /**
-   * Message response for v3 API — same shape as v2 with snake_case JSON conventions
+   * Message response for v3 API — same shape as v2 with snake_case JSON conventions.
+   *
+   * The shape of a message that was sent immediately: it never has a scheduled_at
+   * key. A message that is or was held for a later instant is a
+   * ScheduledMessageResponse, and the endpoint decides which of the two to answer
+   * with. From always returns this type.
    */
   export interface Data {
     id?: string;
@@ -237,7 +292,14 @@ export namespace MessageRetrieveStatusResponse {
 
     /**
      * Structured message body format for database storage. Preserves channel-specific
-     * components (header, body, footer, buttons).
+     * components (header, header media, body, footer, buttons, MMS subject and media).
+     *
+     * Persisted as the messageBody jsonb column on Messages. Every write path goes
+     * through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope
+     * shape is stable regardless of channel or status. Anything that rebuilds this
+     * object field by field — the four IMessageBodyStrategy implementations and
+     * MessageUtils.BuildSegmentBody — has to carry every member, or that member is
+     * silently dropped on whichever path forgot it.
      */
     message_body?: Data.MessageBody | null;
 
@@ -247,6 +309,22 @@ export namespace MessageRetrieveStatusResponse {
 
     price?: number | null;
 
+    /**
+     * A human-readable sentence for reason_code, for example "Insufficient balance".
+     * Omitted whenever reason_code is.
+     */
+    reason?: string | null;
+
+    /**
+     * Why the message is at its current status, as a stable platform code such as
+     * DELIVERY_007, BUSINESS_003 or DELIVERY_003. Present when the current status is
+     * FAILED, FILTERED or BLOCKED and the lifecycle was loaded; omitted otherwise.
+     * Switch on this rather than on reason: the code is stable, the wording may be
+     * improved. It is the platform's classification of the outcome, never a carrier or
+     * vendor code.
+     */
+    reason_code?: string | null;
+
     region_code?: string;
 
     status?: string;
@@ -268,11 +346,31 @@ export namespace MessageRetrieveStatusResponse {
       timestamp: string;
 
       description?: string | null;
+
+      /**
+       * A human-readable sentence for reason_code. Omitted whenever reason_code is.
+       */
+      reason?: string | null;
+
+      /**
+       * Why the message reached this status, as a stable platform code such as
+       * DELIVERY_007. Present on FAILED, FILTERED and BLOCKED events; omitted on every
+       * status that needs no explanation. Same wire name and vocabulary as on the
+       * activities list and the webhook.
+       */
+      reason_code?: string | null;
     }
 
     /**
      * Structured message body format for database storage. Preserves channel-specific
-     * components (header, body, footer, buttons).
+     * components (header, header media, body, footer, buttons, MMS subject and media).
+     *
+     * Persisted as the messageBody jsonb column on Messages. Every write path goes
+     * through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope
+     * shape is stable regardless of channel or status. Anything that rebuilds this
+     * object field by field — the four IMessageBodyStrategy implementations and
+     * MessageUtils.BuildSegmentBody — has to carry every member, or that member is
+     * silently dropped on whichever path forgot it.
      */
     export interface MessageBody {
       buttons?: Array<MessageBody.Button> | null;
@@ -282,6 +380,27 @@ export namespace MessageRetrieveStatusResponse {
       footer?: string | null;
 
       header?: string | null;
+
+      /**
+       * The media asset that rode a message's header, recorded as sent.
+       */
+      headerMedia?: MessageBody.HeaderMedia | null;
+
+      /**
+       * MMS attachments, as the publicly fetchable URLs handed to the carrier. Null on
+       * every other channel.
+       *
+       * Persisted rather than derived because a resend and a curfew release rebuild the
+       * send from the stored row — MessageReplayCommandBuilder reads templateId and
+       * templateVariables and nothing else — so media that lives only on the original
+       * request would silently turn a replayed MMS into a text message.
+       */
+      media?: Array<MessageBody.Media> | null;
+
+      /**
+       * MMS subject line. Null on every other channel.
+       */
+      subject?: string | null;
     }
 
     export namespace MessageBody {
@@ -294,6 +413,74 @@ export namespace MessageRetrieveStatusResponse {
 
         value?: string;
       }
+
+      /**
+       * The media asset that rode a message's header, recorded as sent.
+       */
+      export interface HeaderMedia {
+        /**
+         * "image", "video" or "document" — taken from the header's media variable.
+         */
+        type?: string;
+
+        /**
+         * The https URL the caller supplied for this send. Never the template's stored
+         * props.sample, which is Meta's expiring header_handle rather than what was
+         * delivered.
+         */
+        url?: string;
+      }
+
+      /**
+       * One attachment on a message, in either direction — and in both, a URL somebody
+       * else hosts.
+       *
+       * Outbound: the customer supplied a public URL and we handed it to the carrier.
+       * Inbound: the carrier hosts the file and we record where. sent.dm never holds the
+       * bytes, so there is no key, no expiry bookkeeping and nothing minted per read —
+       * what is stored is what is served.
+       *
+       * An inbound link expires on the carrier's own schedule and is unauthenticated.
+       * That is the customer's to manage, and it is documented where they will see it
+       * rather than only here — a recipient who needs an attachment to outlive that
+       * window copies it on receipt.
+       *
+       * Storing a presigned URL is the specific mistake this shape still avoids:
+       * M260826130000 and M260826140000 exist because RCS assets were stored as signed
+       * URLs and went stale. Nothing here is signed.
+       */
+      export interface Media {
+        /**
+         * One of MmsMediaTypes when the content type is known. Advisory — a reader should
+         * trust the fetched object's own Content-Type.
+         */
+        mediaType?: string | null;
+
+        /**
+         * Content type as the provider declared it. Null when it declared none.
+         */
+        mimeType?: string | null;
+
+        /**
+         * Size as the provider declared it. Never measured here — nothing downloads the
+         * file.
+         */
+        sizeBytes?: number | null;
+
+        /**
+         * Inbound only: the SHA-256 the provider declared alongside the attachment, when
+         * it declared one. Relayed to the customer so they can verify what they fetch
+         * matches what the carrier said it sent. It is the only integrity signal available
+         * on an attachment nobody here has read.
+         */
+        sourceHashSha256?: string | null;
+
+        /**
+         * Where the file lives. Outbound: the URL the customer gave us and the carrier
+         * fetched. Inbound: the URL the carrier hosts it at, relayed unchanged.
+         */
+        url?: string | null;
+      }
     }
   }
 }
@@ -312,7 +499,9 @@ export interface MessageSendResponse {
    * its result; this is what a caller sees, and the mapping between them is a
    * decision the endpoint makes.
    *
-   * The wire is unchanged by the move: same names, same values.
+   * The shape of an immediate send: it never has a scheduled_at key. A send that
+   * carried scheduled_at is a ScheduledSendMessageResponse, and the endpoint decides
+   * which of the two to answer with. From always returns this type.
    */
   data?: MessageSendResponse.Data | null;
 
@@ -343,13 +532,17 @@ export namespace MessageSendResponse {
    * its result; this is what a caller sees, and the mapping between them is a
    * decision the endpoint makes.
    *
-   * The wire is unchanged by the move: same names, same values.
+   * The shape of an immediate send: it never has a scheduled_at key. A send that
+   * carried scheduled_at is a ScheduledSendMessageResponse, and the endpoint decides
+   * which of the two to answer with. From always returns this type.
    */
   export interface Data {
     recipients?: Array<Data.Recipient>;
 
     /**
-     * Overall status — QUEUED once the batch is accepted for delivery.
+     * QUEUED: the batch is accepted. A request that carried scheduled_at is QUEUED
+     * here too; each message moves to SCHEDULED once it is held, as GET
+     * /v3/messages/{id} and the message.scheduled webhook report.
      */
     status?: string;
 
@@ -411,12 +604,51 @@ export interface MessageSendParams {
    */
   channel?: Array<string> | null;
 
+  /**
+   * Body param: Attachments for this send, as publicly fetchable https URLs. Used by
+   * the MMS channel and ignored by every other one.
+   *
+   * Supplying these replaces the media on the template's mms body rather than adding
+   * to it, so a template can hold a default creative while a caller still sends
+   * something recipient-specific.
+   *
+   * Their presence is also what makes a message eligible for MMS on an auto-detect
+   * send: a message with nothing attached is delivered as SMS, because an MMS with
+   * no media is a more expensive text message.
+   *
+   * The recipient's carrier fetches each URL after the send is accepted, so it must
+   * stay publicly reachable — a link that expires, or one behind auth, arrives as a
+   * failed message.
+   */
+  media_urls?: Array<string> | null;
+
   /**
    * Body param: Sandbox flag - when true, the operation is simulated without side
    * effects Useful for testing integrations without actual execution
    */
   sandbox?: boolean;
 
+  /**
+   * Body param: Optional future send time as an ISO-8601 timestamp with an explicit
+   * UTC offset, e.g. 2026-10-01T09:00:00+02:00 or 2026-10-01T07:00:00Z. A value
+   * without an offset is rejected (400) rather than read in the server's zone. The
+   * offset only fixes the instant: it is stored and echoed in UTC as scheduled_at.
+   * Omit to send now. Must be at least one minute ahead and at most 30 days ahead.
+   * Accepted messages report SCHEDULED and are released for delivery at this time.
+   * Quiet hours, balance and template approval are evaluated at release, not at
+   * acceptance: a message whose time falls inside a recipient's protected
+   * quiet-hours window is moved to the next allowed time and a second
+   * message.scheduled webhook reports the new scheduled_at.
+   */
+  scheduled_at?: string | null;
+
+  /**
+   * Body param: Subject line for this send, overriding the template's. MMS only;
+   * ignored on every other channel. Most handsets render it above the body, some
+   * ignore it entirely.
+   */
+  subject?: string | null;
+
   /**
    * Body param: SDK-style template reference: resolve by ID or by name, with
    * optional parameters.
@@ -467,7 +699,20 @@ export namespace MessageSendParams {
     name?: string | null;
 
     /**
-     * Template variable parameters for personalization
+     * Template variable parameters for personalization, keyed by variable name.
+     *
+     * Every variable the template declares is required; GET /v3/templates/{id} lists
+     * them. Supplying a key the template does not declare is ignored.
+     *
+     * Media headers. A template whose header is an image (designed in WhatsApp Manager
+     * and imported into Sent) declares a reserved header_image key. Its value is a
+     * publicly reachable https URL that Meta fetches at send time — Sent does not host
+     * the asset, and the sample approved with the template is not reused. The key is
+     * derived from the header's media type, so header_video and header_document follow
+     * the same shape when those formats ship.
+     *
+     * "parameters": { "header_image": "https://cdn.example.com/banner.jpg", "name":
+     * "John Doe" }
      */
     parameters?: { [key: string]: string } | null;
   }

package/src/resources/templates.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
+import * as TemplatesAPI from './templates';
 import * as WebhooksAPI from './webhooks';
 import { APIPromise } from '../core/api-promise';
 import { PagePromise, TemplatesPage, type TemplatesPageParams } from '../core/pagination';
@@ -318,6 +319,17 @@ export interface Template {
  * the copy, but cannot stand alone.
  */
 export interface TemplateBody {
+  /**
+   * MMS-specific content — subject, text and attachments.
+   *
+   * Like Rcs, an override that cannot stand on its own: a template still needs a
+   * MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
+   * Rcs, it has no fallback at send time — MMS with no media is a more expensive
+   * SMS, so a template without this slot is deliberately not MMS-capable and never
+   * produces an MMS route candidate.
+   */
+  mms?: TemplateBody.Mms | null;
+
   /**
    * The shared body, used for every channel. One half of the choice described above.
    */
@@ -341,6 +353,58 @@ export interface TemplateBody {
   whatsapp?: TemplateBodyContent | null;
 }
 
+export namespace TemplateBody {
+  /**
+   * MMS-specific content — subject, text and attachments.
+   *
+   * Like Rcs, an override that cannot stand on its own: a template still needs a
+   * MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
+   * Rcs, it has no fallback at send time — MMS with no media is a more expensive
+   * SMS, so a template without this slot is deliberately not MMS-capable and never
+   * produces an MMS route candidate.
+   */
+  export interface Mms extends TemplatesAPI.TemplateBodyContent {
+    /**
+     * Attachments carried by every send on this template, in order. A per-send
+     * media_urls on the request replaces this list rather than adding to it, so a
+     * template can hold a default creative and a caller can still send something
+     * recipient-specific.
+     */
+    media?: Array<Mms.Media> | null;
+
+    /**
+     * MMS subject line. Optional — most handsets render it above the body, some ignore
+     * it entirely. Deliberately its own field rather than riding TemplateHeader: the
+     * header is authored once and shared across every channel, and carries Meta's
+     * 60-character cap plus its no-newline, no-emoji text rules, none of which
+     * describe an MMS subject.
+     */
+    subject?: string | null;
+  }
+
+  export namespace Mms {
+    /**
+     * One attachment on an MMS template body.
+     */
+    export interface Media {
+      /**
+       * One of MmsMediaTypes. Advisory: the carrier reads the Content-Type off the
+       * fetched object, not this field. It exists so an authoring UI can render the
+       * right preview and so a reviewer can see what was intended.
+       */
+      mediaType?: string | null;
+
+      /**
+       * Publicly fetchable https URL. The carrier's MMSC fetches this at send time, so
+       * it has to stay reachable and unauthenticated for the life of the send —
+       * including retries and a DLQ replay — which is why a presigned URL is not a valid
+       * value here.
+       */
+      url?: string;
+    }
+  }
+}
+
 export interface TemplateBodyContent {
   /**
    * The body copy, with variables written as {{index:variable}}.
@@ -530,7 +594,52 @@ export interface TemplateHeader {
   template: string;
 
   /**
-   * The type of header (e.g., "text", "image", "video", "document")
+   * Request-only. The s.dm URL of the asset Meta's reviewers see —
+   * https://s.dm/s/{ID}, eight uppercase characters, uploaded to s.dm out of band.
+   * NormalizeRichHeader folds it into the synthesized media variable's Props.Sample
+   * and clears it, so it never persists and a stored definition is indistinguishable
+   * from an imported one.
+   *
+   * Stricter than the send path on purpose:
+   * TemplateUtils.ValidateMediaVariableValues accepts any absolute https URL for the
+   * per-send asset, because that one is the customer's and may live behind a signed
+   * CDN link. This one is the review sample, has to outlive every resubmission, and
+   * so must be ours. Do not "fix" one to match the other.
+   */
+  example_url?: string | null;
+
+  /**
+   * The map pin a location header drops. Meta wants none of this at creation — the
+   * component is just {"type":"header","format":"location"} — so these values exist
+   * for Sent: a preview, and the default a StaticResource header falls back to at
+   * send.
+   */
+  location?: TemplateHeader.Location | null;
+
+  /**
+   * Whether the asset registered at creation is reused when a caller omits the
+   * header's variable at send time. Default false — the caller must supply it per
+   * message, which is the behaviour every existing template has. Written only when
+   * true, so a default-valued header serializes byte-identically to one imported
+   * from Meta.
+   *
+   * Stored and validated but not yet honoured at send: that lands with the Resumable
+   * Upload work, alongside the code that lets such a template be approved in the
+   * first place.
+   */
+  static_resource?: boolean;
+
+  /**
+   * The kind of header. One of:
+   *
+   * text — up to 60 characters, at most one variable. image — png, jpg or jpeg.
+   * Needs ExampleUrl. video — mp4. Needs ExampleUrl. gif — mp4, max 3.5MB. WhatsApp
+   * renders larger files as an ordinary video. Needs ExampleUrl. document — pdf or
+   * docx; only the first page is shown as a thumbnail, so pdf is the practical
+   * choice. Needs ExampleUrl. location — a map pin, supplied through Location.
+   *
+   * Kept lowercase because MetaToTemplateConverter writes Meta's format through
+   * ToLowerInvariant() into this field on import, and the two are compared directly.
    */
   type?: string | null;
 
@@ -540,6 +649,24 @@ export interface TemplateHeader {
   variables?: Array<TemplateVariable> | null;
 }
 
+export namespace TemplateHeader {
+  /**
+   * The map pin a location header drops. Meta wants none of this at creation — the
+   * component is just {"type":"header","format":"location"} — so these values exist
+   * for Sent: a preview, and the default a StaticResource header falls back to at
+   * send.
+   */
+  export interface Location {
+    address: string;
+
+    latitude: string;
+
+    longitude: string;
+
+    name: string;
+  }
+}
+
 export interface TemplateVariable {
   /**
    * The variable's name, and the key callers use for it in a send request's
@@ -571,6 +698,13 @@ export namespace TemplateVariable {
   export interface Props {
     mediaType: string;
 
+    /**
+     * Example value substituted into the template when previewing it and when
+     * submitting it to Meta for review. Free text by nature, so the converter accepts
+     * a JSON number or boolean here and normalizes it — see
+     * JsonScalarToStringConverter for why — and guarantees it is always serialized
+     * back out as a JSON string.
+     */
     sample: string;
 
     url: string;
@@ -586,6 +720,14 @@ export namespace TemplateVariable {
 }
 
 export interface TemplateCreateParams {
+  /**
+   * Body param: Create this template automatically on every sender profile of the
+   * organization, now and in future (default: false). Accepted only from an
+   * organization that has been enabled for it, and only at creation — it cannot be
+   * changed afterwards.
+   */
+  auto_create_for_sp?: boolean;
+
   /**
    * Body param: Template category: MARKETING, UTILITY, AUTHENTICATION (optional,
    * auto-detected if not provided)