@messagebird/sdk 0.46.0 → 0.48.0

package/dist/index.d.mts

@@ -18,6 +18,12 @@ interface RequestLifecycleOptions {
   timeout?: number;
   /** Max retry attempts. Overrides the client default. */
   maxRetries?: number;
+  /**
+   * A 3xx this operation answers on success. Set only where the contract is a
+   * redirect the caller must take itself, because the target is pre-authorized
+   * and must not receive this client's credentials.
+   */
+  successStatus?: number;
 }
 /** The shape a generated hey-api SDK call resolves to. */
 interface FetchOutcome<T> {
@@ -3500,6 +3506,9 @@ type VerificationChannelEntry = {
  * moved to the next channel.
  * - `channel_disabled`: Sending on the channel is temporarily disabled, so the
  * verification moved to the next channel.
+ * - `channel_restricted`: The channel does not carry passcodes to this
+ * destination country. The verification moves to the next channel enabled
+ * there, or fails when the country has no other.
  * - `delivery_timeout`: No delivery confirmation arrived before the channel's
  * timeout, so the verification moved to the next channel.
  * - `not_billable`: The send could not be charged, so it was never handed to the
@@ -3509,7 +3518,7 @@ type VerificationChannelEntry = {
  * New reasons may be added over time. Treat unrecognized values as reasons added
  * later rather than errors.
  */
-type VerificationAttemptFailureReason$1 = "carrier_rejected" | "hard_bounce" | "soft_bounce" | "undelivered" | "channel_unavailable" | "channel_disabled" | "delivery_timeout" | "not_billable" | (string & {});
+type VerificationAttemptFailureReason$1 = "carrier_rejected" | "hard_bounce" | "soft_bounce" | "undelivered" | "channel_unavailable" | "channel_disabled" | "channel_restricted" | "delivery_timeout" | "not_billable" | (string & {});
 /**
  * Meta's content classification for a template.
  *
@@ -3932,7 +3941,7 @@ type WhatsAppContactPhone = {
    */
   phone_number?: string;
   /**
-   * The label the contact's device attached, for example `CELL`, `Home` or `iPhone`. Free text passed through verbatim: WhatsApp declares no vocabulary here and does not normalize the casing, so neither do we.
+   * The label attached to this value, for example `CELL`, `Home` or `iPhone`. Free text: WhatsApp defines no vocabulary. A label on a received card is lowercased; one this workspace sent reads back exactly as sent.
    *
    */
   type?: string;
@@ -3943,7 +3952,7 @@ type WhatsAppContactPhone = {
 type WhatsAppContactEmail = {
   email?: string;
   /**
-   * The label the contact's device attached, for example `Personal` or `Work`. Free text passed through verbatim.
+   * The label attached to this value, for example `CELL`, `Home` or `iPhone`. Free text: WhatsApp defines no vocabulary. A label on a received card is lowercased; one this workspace sent reads back exactly as sent.
    *
    */
   type?: string;
@@ -3958,7 +3967,7 @@ type WhatsAppContactUrl = {
    */
   url?: string;
   /**
-   * The label the contact's device attached, for example `Company`. Free text passed through verbatim.
+   * The label attached to this value, for example `CELL`, `Home` or `iPhone`. Free text: WhatsApp defines no vocabulary. A label on a received card is lowercased; one this workspace sent reads back exactly as sent.
    *
    */
   type?: string;
@@ -3978,24 +3987,24 @@ type WhatsAppContactAddress = {
    */
   country_code?: string;
   /**
-   * The label the contact's device attached, for example `Home`. Free text passed through verbatim.
+   * The label attached to this value, for example `CELL`, `Home` or `iPhone`. Free text: WhatsApp defines no vocabulary. A label on a received card is lowercased; one this workspace sent reads back exactly as sent.
    *
    */
   type?: string;
 };
 /**
- * A contact card the contact shared, either by tapping a button that asked for their number or by sending a card from their address book. Inbound only.
+ * A contact card on this message: one the contact shared, or one this workspace sent.
  * Nothing here is required. WhatsApp sends the parts the card holds and omits the rest, and a card that arrives with only an `origin` is still meaningful, so an empty card reads back empty rather than being dropped.
  *
  */
 type WhatsAppContactCard = {
   /**
-   * Why the card arrived. `contact_request` means the contact tapped a button this workspace sent asking for their number, which is the only signal that the message answers that ask; `other` means they shared a card in the chat. Open enum: treat an unrecognized value as a way of sharing added since.
+   * Why the card arrived. `contact_request` means the contact tapped a button this workspace sent asking for their number, which is the only signal that the message answers that ask; `other` means they shared a card in the chat. Open enum: treat an unrecognized value as a way of sharing added since. Set on a card the contact shared; absent on one this workspace sent.
    *
    */
   origin?: string;
   /**
-   * The contact's card in vCard format. WhatsApp sends it on a card shared in the chat and omits it on a button tap, which carries the number alone.
+   * The contact's card in vCard format. WhatsApp sends it on a card shared in the chat and omits it on a button tap, which carries the number alone. Set on a card the contact shared; absent on one this workspace sent.
    *
    */
   vcard?: string;
@@ -4357,7 +4366,7 @@ type WhatsAppMessage = {
    */
   readonly location?: WhatsAppLocation;
   /**
-   * Contact cards the contact shared, either by tapping a button that asked for their number or by sending a card from their address book. Inbound only: sending a contact card is not supported.
+   * Contact cards on this message: cards the contact shared, either by tapping a button that asked for their number or by sending one from their address book, or the cards this workspace sent.
    *
    */
   readonly contact_cards?: Array<WhatsAppContactCard>;
@@ -4817,6 +4826,114 @@ type WhatsAppInteractiveSend = ({
    */
   cards?: Array<WhatsAppInteractiveCardSend>;
 };
+/**
+ * The contact's name. `formatted_name` is what the card shows, and WhatsApp additionally requires at least one of the parts below it, so a card carrying only a formatted name is rejected.
+ *
+ */
+type WhatsAppContactNameSend = {
+  /**
+   * The whole name, as the card should render it.
+   */
+  formatted_name: string;
+  first_name?: string;
+  middle_name?: string;
+  last_name?: string;
+  prefix?: string;
+  suffix?: string;
+};
+/**
+ * Where the contact works, as the card should record it.
+ */
+type WhatsAppContactOrgSend = {
+  company?: string;
+  department?: string;
+  title?: string;
+};
+/**
+ * One phone number to put on a contact card.
+ */
+type WhatsAppContactPhoneSend = {
+  /**
+   * The number to show. Send it in E.164 to get a card the recipient can message from; any other form still renders, with an invite button.
+   *
+   */
+  phone_number: string;
+  /**
+   * A label for the number, shown beside it. Free text: WhatsApp defines no vocabulary, and the label is sent exactly as written.
+   *
+   */
+  type?: string;
+};
+/**
+ * One email address to put on a contact card.
+ */
+type WhatsAppContactEmailSend = {
+  email: string;
+  /**
+   * A label for the address, shown beside it. Free text, sent exactly as written.
+   *
+   */
+  type?: string;
+};
+/**
+ * One website to put on a contact card.
+ */
+type WhatsAppContactUrlSend = {
+  /**
+   * The address to show. Not validated as a URL, because a card commonly carries a bare domain.
+   *
+   */
+  url: string;
+  /**
+   * A label for the website, shown beside it. Free text, sent exactly as written.
+   *
+   */
+  type?: string;
+};
+/**
+ * One postal address to put on a contact card.
+ */
+type WhatsAppContactAddressSend = {
+  street?: string;
+  city?: string;
+  state?: string;
+  zip?: string;
+  country?: string;
+  /**
+   * The country as it should appear on the address, commonly the ISO two-letter code.
+   */
+  country_code?: string;
+  /**
+   * A label for the address, shown beside it. Free text, sent exactly as written.
+   *
+   */
+  type?: string;
+};
+/**
+ * A contact card to send. WhatsApp shows the name on the card and the rest in a profile view the recipient opens from it.
+ * A card carrying a phone number renders buttons that message or save the contact; a card without one can only be added to an address book.
+ *
+ */
+type WhatsAppContactCardSend = {
+  name: WhatsAppContactNameSend;
+  /**
+   * Where the contact works.
+   */
+  org?: WhatsAppContactOrgSend;
+  /**
+   * The contact's birthday, as `YYYY-MM-DD`. WhatsApp rejects any other shape, and a date no calendar holds is rejected too.
+   *
+   */
+  birthday?: string;
+  /**
+   * The numbers on the card. A number in E.164 renders a button that opens a WhatsApp chat with it; one that is not renders an invite instead.
+   *
+   */
+  phone_numbers?: Array<WhatsAppContactPhoneSend>;
+  emails?: Array<WhatsAppContactEmailSend>;
+  urls?: Array<WhatsAppContactUrlSend>;
+  addresses?: Array<WhatsAppContactAddressSend>;
+};
 /**
  * A WhatsApp message to send. Carry exactly one kind of content: a request with none returns a `422` `WhatsAppContentRequired`, and one carrying more than one returns a `422` `WhatsAppContentAmbiguous`. The schema does not express that constraint, because which combinations are available depends on the content types your workspace can send.
  *
@@ -4877,6 +4994,11 @@ type WhatsAppMessageSendRequest = {
    *
    */
   interactive?: WhatsAppInteractiveSend;
+  /**
+   * Contact cards to send instead of a template. Up to five: WhatsApp accepts far more, and a message that opens as one name plus a count of the rest is not a card the recipient will read.
+   *
+   */
+  contact_cards?: Array<WhatsAppContactCardSend>;
   /**
    * Quote a message the contact will see above this one, the way replying in the WhatsApp client does. Name a message from the same conversation: one this workspace sent to this recipient, or received from them. Any content quotes, template or free-form. A message this workspace does not hold, or one older than the 15-day window we keep provider ids for, returns a `422` `WhatsAppInReplyToNotFound`. A message that never reached WhatsApp, or one from a different conversation than this send's `to` and `from`, returns a `422` `WhatsAppInReplyToNotQuotable`.
    *
@@ -8850,6 +8972,11 @@ type EventWhatsAppBase = {
   metadata: {
     [key: string]: unknown;
   } | null;
+  /**
+   * The message this one answers. On an outbound message it is the `in_reply_to_message_id` the send request quoted. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
+   *
+   */
+  in_reply_to_message_id?: WhatsAppMessageId;
 };
 /**
  * Payload of the whatsapp.accepted event.
@@ -8970,6 +9097,11 @@ type EventWhatsAppReceivedData = EventWhatsAppBase & {
    *
    */
   contact_cards?: Array<WhatsAppContactCard>;
+  /**
+   * What the contact tapped, when the message answers an interactive message or a template's quick-reply button.
+   *
+   */
+  interactive_reply?: WhatsAppInteractiveReply;
   /**
    * Set when the contact sent content the API does not model, naming the WhatsApp content type.
    *
@@ -9340,6 +9472,10 @@ type VoiceInboundForwardAs = "dialed_number" | "calling_number";
  * - `caller_id_not_verified`: The number in the `From` header is not a verified
  * caller ID for this workspace. Verify it, or present a number you have
  * already verified.
+ * - `number_ownership_not_verified`: You bought this number, but the country that
+ * issued it has not yet accepted the documents proving your workspace owns it.
+ * Open the number under Numbers and complete its ownership requirements, then
+ * place the call again.
  * - `destination_not_enabled`: You have not turned on calling to this
  * destination country. Enable it in your voice destination settings.
  * - `insufficient_balance`: Your wallet did not cover the call. Top up, or turn
@@ -9362,7 +9498,7 @@ type VoiceInboundForwardAs = "dialed_number" | "calling_number";
  * - `call_not_permitted`: The call could not be priced for your account.
  *
  */
-type VoiceCallRejectionReason = "source_not_allowed" | "caller_id_not_verified" | "routing_not_configured" | "no_route_found" | "destination_blocked" | "destination_not_enabled" | "insufficient_balance" | "daily_spend_exceeded" | "concurrent_calls_exceeded" | "calls_per_second_exceeded" | "call_not_permitted";
+type VoiceCallRejectionReason = "source_not_allowed" | "caller_id_not_verified" | "routing_not_configured" | "no_route_found" | "destination_blocked" | "destination_not_enabled" | "insufficient_balance" | "daily_spend_exceeded" | "concurrent_calls_exceeded" | "calls_per_second_exceeded" | "call_not_permitted" | "number_ownership_not_verified";
 type VoiceCallInboundRouteReject = {
   /**
    * The number turned the call away. This is where every number starts, so it covers a number nobody has configured as well as one set to reject.
@@ -12877,7 +13013,7 @@ declare abstract class Resource {
   protected readonly client: Client;
   constructor(core: BirdHTTPClient, client: Client);
   /** Run a single typed call through the lifecycle. */
-  protected call<T>(method: string, options: RequestOptions | undefined, invoke: (ctx: CallContext) => Promise<FetchOutcome<T>>, schemes?: string[]): APIPromise<T>;
+  protected call<T>(method: string, options: RequestOptions | undefined, invoke: (ctx: CallContext) => Promise<FetchOutcome<T>>, schemes?: string[], successStatus?: number): APIPromise<T>;
   /** Run a cursor-paginated list through the lifecycle (each page retried independently). */
   protected paginated<T>(method: string, options: RequestOptions | undefined, invoke: (ctx: CallContext, cursor: string | undefined) => Promise<FetchOutcome<CursorPage<T>>>, schemes?: string[]): PaginatedPromise<T>;
 }
@@ -14271,16 +14407,52 @@ declare class WhatsappResourceBase extends Resource {
   listEvents(messageId: string, query?: WhatsappListEventsQuery, options?: RequestOptions): APIPromise<WhatsAppEventList>;
 }
 //#endregion
+//#region src/resources/whatsappMessages.d.ts
+/**
+ * Media downloaded from a received WhatsApp message. `contentType` is what
+ * storage declared, which is the message's own `mime_type`.
+ */
+interface WhatsappMedia {
+  data: Uint8Array;
+  contentType: string;
+  contentLength: number;
+}
+declare class WhatsappMessagesResource extends Resource {
+  /**
+   * Download the media on a received WhatsApp message — an image, video, audio
+   * clip, sticker or document. `mediaId` is the `id` on the message's content
+   * object, which `bird.whatsapp.get` returns.
+   *
+   * Media is kept for 30 days after the message arrives; after that the message
+   * still lists the media's `mime_type` and `caption`, and this throws. Outbound
+   * messages carry no stored media.
+   *
+   * @example
+   * const media = await bird.whatsapp.messages.media(
+   *   "wam_01kya19eknftrs2s6p82asmvnh",
+   *   "waf_01kyb2m4xq7whs0d8n3prv6tez",
+   * );
+   * console.log(media.contentType, media.contentLength);
+   */
+  media(messageId: string, mediaId: string, options?: RequestOptions): APIPromise<WhatsappMedia>;
+}
+//#endregion
 //#region src/resources/whatsapp.d.ts
 /** Body for `bird.whatsapp.send` — a template send, or one free-form content arm. */
 type WhatsappSendParams = WhatsAppMessageSendRequest;
 declare class WhatsappResource extends WhatsappResourceBase {
+  /** Subresources of one message — `bird.whatsapp.messages.media(...)`. */
+  readonly messages: WhatsappMessagesResource;
+  constructor(core: ConstructorParameters<typeof Resource>[0], client: ConstructorParameters<typeof Resource>[1]);
   /**
    * Send one message, carrying exactly one kind of content: a template, or
    * free-form `text`, `image`, `video`, `audio`, `sticker`, `document`,
-   * `location` or `interactive` — the last being the arm that gives the
-   * recipient something to tap: reply buttons, a list menu, a link button,
-   * media cards, or a request for their location or contact details. Set
+   * `location`, `contact_cards` or `interactive` — the last being the arm that
+   * gives the recipient something to tap: reply buttons, a list menu, a link
+   * button, media cards, or a request for their location or contact details.
+   * `contact_cards` sends up to five contact cards: a card's `name` needs
+   * `formatted_name` plus at least one other part, and a `phone_number` in
+   * E.164 earns the card a button that opens a chat. Set
    * `in_reply_to_message_id` to quote an earlier message from the same
    * conversation. Every send but a Bird-managed
    * template needs `from`, a number this workspace owns. The result is
@@ -15291,6 +15463,7 @@ type TemplateStatusValue = (typeof TemplateStatus)[keyof typeof TemplateStatus];
 declare const VerificationAttemptFailureReason: {
   readonly CarrierRejected: "carrier_rejected";
   readonly ChannelDisabled: "channel_disabled";
+  readonly ChannelRestricted: "channel_restricted";
   readonly ChannelUnavailable: "channel_unavailable";
   readonly DeliveryTimeout: "delivery_timeout";
   readonly HardBounce: "hard_bounce";
@@ -15436,5 +15609,5 @@ declare const WhatsAppTemplateParameterType: {
 /** A known WhatsAppTemplateParameterType value. */
 type WhatsAppTemplateParameterTypeValue = (typeof WhatsAppTemplateParameterType)[keyof typeof WhatsAppTemplateParameterType];
 //#endregion
-export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceCreateParams, type AudienceListContactsQuery, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, type BirdClientOptions, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdMissingApiKeyError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, type BirdRequest, type BirdResponse, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, type BirdWebhookEvent, BirdWebhookVerificationError, type ChannelAuthorization, type Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type ContactsPreferencesListQuery, type CursorPage, type DnsRecord, type Domain, type DomainCapabilities, type DomainCreateParams, type DomainDkim, type DomainListQuery, type DomainUpdateParams, type EmailChannelDefaults, EmailEventType, type EmailEventTypeValue, type EmailListQuery, type EmailLookup, EmailLookupFlag, type EmailLookupFlagValue, EmailLookupReason, type EmailLookupReasonValue, EmailLookupResult, type EmailLookupResultValue, type EmailMailboxLabelList, type EmailMailboxesCreateParams, type EmailMailboxesListQuery, type EmailMailboxesMessagesCreateParams, type EmailMailboxesReceiveRulesCreateParams, type EmailMailboxesReceiveRulesListQuery, type EmailMailboxesStatsQuery, type EmailMailboxesUpdateParams, type EmailMailboxesUpdateQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type EmailStatsByBounceCodeQuery, type EmailStatsByBounceCodeResponse, type EmailStatsByBroadcastQuery, type EmailStatsByBroadcastResponse, type EmailStatsByCategoryQuery, type EmailStatsByCategoryResponse, type EmailStatsByClientQuery, type EmailStatsByClientResponse, type EmailStatsByComplaintTypeQuery, type EmailStatsByComplaintTypeResponse, type EmailStatsByLocationQuery, type EmailStatsByLocationResponse, type EmailStatsByMailboxProviderQuery, type EmailStatsByMailboxProviderRegionQuery, type EmailStatsByMailboxProviderRegionResponse, type EmailStatsByMailboxProviderResponse, type EmailStatsByRecipientDomainQuery, type EmailStatsByRecipientDomainResponse, type EmailStatsBySendingDomainQuery, type EmailStatsBySendingDomainResponse, type EmailStatsBySendingIpQuery, type EmailStatsBySendingIpResponse, type EmailStatsByTagQuery, type EmailStatsByTemplateQuery, type EmailStatsByTemplateResponse, type EmailStatsDailyQuery, type EmailStatsHourlyQuery, type EmailStatsResponse, type EmailStatsSummary, type EmailStatsSummaryQuery, type EmailStatsTagsResponse, type EmailThread, type EmailThreadMessage, type EmailThreadMessageAttachmentList, type EmailThreadMessageBody, type EmailThreadsDeleteQuery, type EmailThreadsListQuery, type EmailThreadsMessagesListQuery, type EmailThreadsMessagesReplyParams, type EmailThreadsUpdateParams, type ErrorDetail, type LookupEmailParams, LookupFlag, type LookupFlagValue, type LookupPhoneNumberParams, LookupPropertyStatus, type LookupPropertyStatusValue, type Mailbox, type MailboxStatsResponse, type NextAction, NumberCapability, type NumberCapabilityValue, NumberType, type NumberTypeValue, NumbersOrderStatus, type NumbersOrderStatusValue, type PaginatedPromise, type PhoneNumberLookup, type Preference, PreferenceChannel, type PreferenceChannelValue, type PreferenceCoverage, type PreferenceCreateParams, PreferenceOrigin, type PreferenceOriginValue, type PreferenceStatus, type PreferenceWriteResult, type PreferencesListQuery, type RealtimeBatchPublishResult, type RealtimeChannelGetQuery, type RealtimeChannelInclude, type RealtimeChannelInfo, type RealtimeChannelListItem, type RealtimeChannelListQuery, type RealtimeChannelMember, type RealtimeChannelMembers, type RealtimeChannelsList, type RealtimeOptions, type RealtimePublishBatchParams, type RealtimePublishParams, type RealtimePublishResult, type ReceiveRule, type RequestOptions, SMSErrorCode, type SMSErrorCodeValue, SMSKeywordOperation, type SMSKeywordOperationValue, SMSSuppressionCoverage, type SMSSuppressionCoverageValue, SMSSuppressionEndReason, type SMSSuppressionEndReasonValue, SMSSuppressionOrigin, type SMSSuppressionOriginValue, SMSSuppressionReason, type SMSSuppressionReasonValue, type SafeResult, type SmsEventList, type SmsInboundStatsByCountryResponse, type SmsInboundStatsByNumberResponse, type SmsInboundStatsByOperatorResponse, type SmsInboundStatsResponse, type SmsInboundStatsSummaryResponse, type SmsKeywordRule, type SmsKeywordRuleList, type SmsKeywordRulesCreateParams, type SmsKeywordRulesListQuery, type SmsKeywordRulesUpdateParams, type SmsListEventsQuery, type SmsListQuery, type SmsMessage, type SmsSendBatchParams, type SmsSendBatchResult, type SmsSendParams, type SmsStatsByCarrierQuery, type SmsStatsByCarrierResponse, type SmsStatsByCategoryQuery, type SmsStatsByCategoryResponse, type SmsStatsByCountryQuery, type SmsStatsByCountryResponse, type SmsStatsByErrorCodeQuery, type SmsStatsByErrorCodeResponse, type SmsStatsByOriginatorQuery, type SmsStatsByOriginatorResponse, type SmsStatsByStatusQuery, type SmsStatsByStatusResponse, type SmsStatsDailyQuery, type SmsStatsHourlyQuery, type SmsStatsInboundByCountryQuery, type SmsStatsInboundByNumberQuery, type SmsStatsInboundByOperatorQuery, type SmsStatsInboundDailyQuery, type SmsStatsInboundHourlyQuery, type SmsStatsInboundSummaryQuery, type SmsStatsResponse, type SmsStatsSummary, type SmsStatsSummaryQuery, type SmsSuppression, type SmsSuppressionsAddParams, type SmsSuppressionsListQuery, type SmsTemplate, type SmsTemplateList, type SmsTemplateListQuery, TemplateLanguageStatus, type TemplateLanguageStatusValue, TemplateStatus, type TemplateStatusValue, type Verification, VerificationAttemptFailureReason, type VerificationAttemptFailureReasonValue, VerificationChannel, type VerificationChannelValue, type VerificationCheckResult, VerificationTerminalReason, type VerificationTerminalReasonValue, type VerifyVerificationsCheckParams, type VerifyVerificationsCreateParams, type VerifyVerificationsNextChannelParams, type WebhookAttemptList, type WebhookEndpoint, type WebhookEndpointCreated, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, type WebhookRotateSecretResponse, type WebhookTestResponse, type WebhooksAttemptsQuery, type WebhooksCreateParams, type WebhooksListQuery, type WebhooksTestParams, type WebhooksUpdateParams, WhatsAppErrorCode, type WhatsAppErrorCodeValue, type WhatsAppEventList, WhatsAppEventType, type WhatsAppEventTypeValue, WhatsAppInteractiveButtonType, type WhatsAppInteractiveButtonTypeValue, WhatsAppInteractiveHeaderType, type WhatsAppInteractiveHeaderTypeValue, WhatsAppInteractiveReplyType, type WhatsAppInteractiveReplyTypeValue, WhatsAppInteractiveType, type WhatsAppInteractiveTypeValue, type WhatsAppMessage, WhatsAppTemplateCategory, type WhatsAppTemplateCategoryValue, WhatsAppTemplateParameterType, type WhatsAppTemplateParameterTypeValue, type WhatsappListEventsQuery, type WhatsappListQuery, type WhatsappSendParams, type Workspace, baseUrlForRegion, regionFromApiKey };
+export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceCreateParams, type AudienceListContactsQuery, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, type BirdClientOptions, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdMissingApiKeyError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, type BirdRequest, type BirdResponse, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, type BirdWebhookEvent, BirdWebhookVerificationError, type ChannelAuthorization, type Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type ContactsPreferencesListQuery, type CursorPage, type DnsRecord, type Domain, type DomainCapabilities, type DomainCreateParams, type DomainDkim, type DomainListQuery, type DomainUpdateParams, type EmailChannelDefaults, EmailEventType, type EmailEventTypeValue, type EmailListQuery, type EmailLookup, EmailLookupFlag, type EmailLookupFlagValue, EmailLookupReason, type EmailLookupReasonValue, EmailLookupResult, type EmailLookupResultValue, type EmailMailboxLabelList, type EmailMailboxesCreateParams, type EmailMailboxesListQuery, type EmailMailboxesMessagesCreateParams, type EmailMailboxesReceiveRulesCreateParams, type EmailMailboxesReceiveRulesListQuery, type EmailMailboxesStatsQuery, type EmailMailboxesUpdateParams, type EmailMailboxesUpdateQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type EmailStatsByBounceCodeQuery, type EmailStatsByBounceCodeResponse, type EmailStatsByBroadcastQuery, type EmailStatsByBroadcastResponse, type EmailStatsByCategoryQuery, type EmailStatsByCategoryResponse, type EmailStatsByClientQuery, type EmailStatsByClientResponse, type EmailStatsByComplaintTypeQuery, type EmailStatsByComplaintTypeResponse, type EmailStatsByLocationQuery, type EmailStatsByLocationResponse, type EmailStatsByMailboxProviderQuery, type EmailStatsByMailboxProviderRegionQuery, type EmailStatsByMailboxProviderRegionResponse, type EmailStatsByMailboxProviderResponse, type EmailStatsByRecipientDomainQuery, type EmailStatsByRecipientDomainResponse, type EmailStatsBySendingDomainQuery, type EmailStatsBySendingDomainResponse, type EmailStatsBySendingIpQuery, type EmailStatsBySendingIpResponse, type EmailStatsByTagQuery, type EmailStatsByTemplateQuery, type EmailStatsByTemplateResponse, type EmailStatsDailyQuery, type EmailStatsHourlyQuery, type EmailStatsResponse, type EmailStatsSummary, type EmailStatsSummaryQuery, type EmailStatsTagsResponse, type EmailThread, type EmailThreadMessage, type EmailThreadMessageAttachmentList, type EmailThreadMessageBody, type EmailThreadsDeleteQuery, type EmailThreadsListQuery, type EmailThreadsMessagesListQuery, type EmailThreadsMessagesReplyParams, type EmailThreadsUpdateParams, type ErrorDetail, type LookupEmailParams, LookupFlag, type LookupFlagValue, type LookupPhoneNumberParams, LookupPropertyStatus, type LookupPropertyStatusValue, type Mailbox, type MailboxStatsResponse, type NextAction, NumberCapability, type NumberCapabilityValue, NumberType, type NumberTypeValue, NumbersOrderStatus, type NumbersOrderStatusValue, type PaginatedPromise, type PhoneNumberLookup, type Preference, PreferenceChannel, type PreferenceChannelValue, type PreferenceCoverage, type PreferenceCreateParams, PreferenceOrigin, type PreferenceOriginValue, type PreferenceStatus, type PreferenceWriteResult, type PreferencesListQuery, type RealtimeBatchPublishResult, type RealtimeChannelGetQuery, type RealtimeChannelInclude, type RealtimeChannelInfo, type RealtimeChannelListItem, type RealtimeChannelListQuery, type RealtimeChannelMember, type RealtimeChannelMembers, type RealtimeChannelsList, type RealtimeOptions, type RealtimePublishBatchParams, type RealtimePublishParams, type RealtimePublishResult, type ReceiveRule, type RequestOptions, SMSErrorCode, type SMSErrorCodeValue, SMSKeywordOperation, type SMSKeywordOperationValue, SMSSuppressionCoverage, type SMSSuppressionCoverageValue, SMSSuppressionEndReason, type SMSSuppressionEndReasonValue, SMSSuppressionOrigin, type SMSSuppressionOriginValue, SMSSuppressionReason, type SMSSuppressionReasonValue, type SafeResult, type SmsEventList, type SmsInboundStatsByCountryResponse, type SmsInboundStatsByNumberResponse, type SmsInboundStatsByOperatorResponse, type SmsInboundStatsResponse, type SmsInboundStatsSummaryResponse, type SmsKeywordRule, type SmsKeywordRuleList, type SmsKeywordRulesCreateParams, type SmsKeywordRulesListQuery, type SmsKeywordRulesUpdateParams, type SmsListEventsQuery, type SmsListQuery, type SmsMessage, type SmsSendBatchParams, type SmsSendBatchResult, type SmsSendParams, type SmsStatsByCarrierQuery, type SmsStatsByCarrierResponse, type SmsStatsByCategoryQuery, type SmsStatsByCategoryResponse, type SmsStatsByCountryQuery, type SmsStatsByCountryResponse, type SmsStatsByErrorCodeQuery, type SmsStatsByErrorCodeResponse, type SmsStatsByOriginatorQuery, type SmsStatsByOriginatorResponse, type SmsStatsByStatusQuery, type SmsStatsByStatusResponse, type SmsStatsDailyQuery, type SmsStatsHourlyQuery, type SmsStatsInboundByCountryQuery, type SmsStatsInboundByNumberQuery, type SmsStatsInboundByOperatorQuery, type SmsStatsInboundDailyQuery, type SmsStatsInboundHourlyQuery, type SmsStatsInboundSummaryQuery, type SmsStatsResponse, type SmsStatsSummary, type SmsStatsSummaryQuery, type SmsSuppression, type SmsSuppressionsAddParams, type SmsSuppressionsListQuery, type SmsTemplate, type SmsTemplateList, type SmsTemplateListQuery, TemplateLanguageStatus, type TemplateLanguageStatusValue, TemplateStatus, type TemplateStatusValue, type Verification, VerificationAttemptFailureReason, type VerificationAttemptFailureReasonValue, VerificationChannel, type VerificationChannelValue, type VerificationCheckResult, VerificationTerminalReason, type VerificationTerminalReasonValue, type VerifyVerificationsCheckParams, type VerifyVerificationsCreateParams, type VerifyVerificationsNextChannelParams, type WebhookAttemptList, type WebhookEndpoint, type WebhookEndpointCreated, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, type WebhookRotateSecretResponse, type WebhookTestResponse, type WebhooksAttemptsQuery, type WebhooksCreateParams, type WebhooksListQuery, type WebhooksTestParams, type WebhooksUpdateParams, WhatsAppErrorCode, type WhatsAppErrorCodeValue, type WhatsAppEventList, WhatsAppEventType, type WhatsAppEventTypeValue, WhatsAppInteractiveButtonType, type WhatsAppInteractiveButtonTypeValue, WhatsAppInteractiveHeaderType, type WhatsAppInteractiveHeaderTypeValue, WhatsAppInteractiveReplyType, type WhatsAppInteractiveReplyTypeValue, WhatsAppInteractiveType, type WhatsAppInteractiveTypeValue, type WhatsAppMessage, WhatsAppTemplateCategory, type WhatsAppTemplateCategoryValue, WhatsAppTemplateParameterType, type WhatsAppTemplateParameterTypeValue, type WhatsappListEventsQuery, type WhatsappListQuery, type WhatsappMedia, type WhatsappSendParams, type Workspace, baseUrlForRegion, regionFromApiKey };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1089,7 +1089,7 @@ var BirdHTTPClient = class {
 				await retryOrThrow(() => new BirdConnectionError("No response received from the server"));
 				continue;
 			}
-			if (res.ok) return {
+			if (res.ok || res.status === options.successStatus) return {
 				data: outcome.data,
 				response: toBirdResponse(res)
 			};
@@ -2975,9 +2975,9 @@ const listWhatsAppMessages = (options) => (options?.client ?? client).get({
 *
 * Sends one WhatsApp message to one recipient. The request carries exactly one
 * kind of content: a message template, or free-form `text`, `image`, `video`,
-* `audio`, `sticker`, `document`, `location` or `interactive`. A request
-* carrying none is rejected with a `422`, and one carrying more than one is
-* too.
+* `audio`, `sticker`, `document`, `location`, `contact_cards` or
+* `interactive`. A request carrying none is rejected with a `422`, and one
+* carrying more than one is too.
 *
 * A **template** is the only content WhatsApp delivers outside an open
 * customer service window, so it is what starts a conversation. Name the
@@ -3010,6 +3010,11 @@ const listWhatsAppMessages = (options) => (options?.client ?? client).get({
 * Interactive content is free-form, so the customer service window and the
 * `from` requirement above both apply.
 *
+* **Contact cards** share up to five contacts in one message. Each card's
+* `name` needs `formatted_name` plus at least one other part, and a
+* `phone_number` in E.164 earns that card a button opening a chat with it.
+* Contact cards are free-form too, so the same window and `from` rules apply.
+*
 * Set `in_reply_to_message_id` to quote a message the contact sees above this
 * one, the way replying in the WhatsApp client does. Any content quotes, and
 * the quoted message must be one from this same conversation.
@@ -3086,6 +3091,42 @@ const listWhatsAppMessageEvents = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get a WhatsApp message's media
+*
+* Redirects to a short-lived URL for the media on a received WhatsApp message.
+* Inbound media is stored because WhatsApp's own URL is not fetchable
+* without our credentials; this endpoint is what the `url` on the message's
+* `image`, `video`, `audio`, `sticker` or `document` points at. The bytes
+* live in object storage and are served straight from there, so they never
+* transit the API.
+*
+* The response is a `302` whose `Location` is that pre-authorized storage URL,
+* valid for 15 minutes; your client must follow redirects. The `Authorization`
+* header must be absent from the request that fetches that URL: a client that
+* attaches credentials centrally, at its transport, interceptor or middleware
+* layer rather than per request, re-adds the header on every hop including the
+* redirect, so the storage URL must be fetched with a client that carries
+* none.
+*
+* Media is kept for 30 days after the message is received, and the message
+* itself is kept longer. A message older than that still lists its media's
+* `mime_type` and `caption`, and this operation returns `410` once the bytes
+* have expired. Outbound messages have no media to serve.
+*
+*/
+const getWhatsAppMessageMedia = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/whatsapp/messages/{message_id}/media/{media_id}",
+	...options
+});
+/**
 * Get daily sending statistics
 *
 * Returns one row of aggregate sending statistics per calendar day for the workspace: UTC days by default, or your local days when `timezone` is set. Days with no activity are included with zero counts, so the series charts without client-side gap handling. Suited to charts and trend lines; for per-message exact accounting use the message detail endpoints.
@@ -4424,9 +4465,12 @@ var Resource = class {
 		this.client = client;
 	}
 	/** Run a single typed call through the lifecycle. */
-	call(method, options, invoke, schemes) {
+	call(method, options, invoke, schemes, successStatus) {
 		const credentials = this.core.credentialHeaders(schemes, options?.credentials);
-		return apiPromise(this.core.request((ctx) => invoke(callContext(ctx, options, credentials)), lifecycle(method, options)));
+		return apiPromise(this.core.request((ctx) => invoke(callContext(ctx, options, credentials)), {
+			...lifecycle(method, options),
+			successStatus
+		}));
 	}
 	/** Run a cursor-paginated list through the lifecycle (each page retried independently). */
 	paginated(method, options, invoke, schemes) {
@@ -6649,14 +6693,107 @@ var WhatsappResourceBase = class extends Resource {
 	}
 };
 //#endregion
+//#region src/resources/whatsappMessages.ts
+var WhatsappMessagesResource = class extends Resource {
+	/**
+	* Download the media on a received WhatsApp message — an image, video, audio
+	* clip, sticker or document. `mediaId` is the `id` on the message's content
+	* object, which `bird.whatsapp.get` returns.
+	*
+	* Media is kept for 30 days after the message arrives; after that the message
+	* still lists the media's `mime_type` and `caption`, and this throws. Outbound
+	* messages carry no stored media.
+	*
+	* @example
+	* const media = await bird.whatsapp.messages.media(
+	*   "wam_01kya19eknftrs2s6p82asmvnh",
+	*   "waf_01kyb2m4xq7whs0d8n3prv6tez",
+	* );
+	* console.log(media.contentType, media.contentLength);
+	*/
+	media(messageId, mediaId, options) {
+		return this.call("GET", options, async ({ signal, headers }) => {
+			const outcome = await getWhatsAppMessageMedia({
+				client: this.client,
+				path: {
+					message_id: messageId,
+					media_id: mediaId
+				},
+				headers,
+				signal,
+				redirect: "manual",
+				parseAs: "arrayBuffer"
+			});
+			const res = outcome.response;
+			if (!res) return outcome;
+			if (res.status !== 302) {
+				if (!res.ok) return outcome;
+				return {
+					data: mediaFrom(res, outcome.data),
+					response: res
+				};
+			}
+			const location = res.headers.get("Location");
+			if (!location) throw new BirdConnectionError("media redirect carried no Location header");
+			const stored = await fetchStorage(this.client.getConfig().fetch ?? fetch, location, signal);
+			return {
+				data: mediaFrom(stored.response, stored.body),
+				response: res
+			};
+		}, void 0, 302);
+	}
+};
+/**
+* The second leg. Not a Bird API request — a different host, a credential of
+* its own, and an XML error body that is no Bird error envelope — so it runs
+* outside the request core and its failures surface as connection errors.
+* Running a storage 403 through the API error mapper would report the caller's
+* own key as lacking permission, which is not what happened.
+*
+* It reuses the client's configured `fetch` (a proxy or edge adapter still
+* applies) but sends no headers at all, which is what keeps the credential off
+* the wire.
+*/
+async function fetchStorage(fetchFn, location, signal) {
+	let response;
+	try {
+		response = await fetchFn(location, { signal });
+	} catch (err) {
+		if (signal.aborted) throw err;
+		throw new BirdConnectionError(`downloading media failed: ${err instanceof Error ? err.message : String(err)} — call media again for a fresh link`);
+	}
+	if (!response.ok) throw new BirdConnectionError(`storage refused the download link (status ${response.status}) — the link expired or was refused; call media again for a fresh link`);
+	return {
+		response,
+		body: await response.arrayBuffer()
+	};
+}
+function mediaFrom(response, body) {
+	const data = new Uint8Array(body);
+	return {
+		data,
+		contentType: response.headers.get("Content-Type") ?? "application/octet-stream",
+		contentLength: data.length
+	};
+}
+//#endregion
 //#region src/resources/whatsapp.ts
 var WhatsappResource = class extends WhatsappResourceBase {
+	/** Subresources of one message — `bird.whatsapp.messages.media(...)`. */
+	messages;
+	constructor(core, client) {
+		super(core, client);
+		this.messages = new WhatsappMessagesResource(core, client);
+	}
 	/**
 	* Send one message, carrying exactly one kind of content: a template, or
 	* free-form `text`, `image`, `video`, `audio`, `sticker`, `document`,
-	* `location` or `interactive` — the last being the arm that gives the
-	* recipient something to tap: reply buttons, a list menu, a link button,
-	* media cards, or a request for their location or contact details. Set
+	* `location`, `contact_cards` or `interactive` — the last being the arm that
+	* gives the recipient something to tap: reply buttons, a list menu, a link
+	* button, media cards, or a request for their location or contact details.
+	* `contact_cards` sends up to five contact cards: a card's `name` needs
+	* `formatted_name` plus at least one other part, and a `phone_number` in
+	* E.164 earns the card a button that opens a chat. Set
 	* `in_reply_to_message_id` to quote an earlier message from the same
 	* conversation. Every send but a Bird-managed
 	* template needs `from`, a number this workspace owns. The result is
@@ -7790,9 +7927,9 @@ var BirdClient = class {
 		this.#headers = {
 			...opts.defaultHeaders,
 			...opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {},
-			"User-Agent": `bird-sdk-js/0.46.0`,
+			"User-Agent": `bird-sdk-js/0.48.0`,
 			"Bird-Surface": "sdk-js",
-			"Bird-Version": "0.46.0"
+			"Bird-Version": "0.48.0"
 		};
 		const caller = detectCaller();
 		if (caller) this.#headers["Bird-Caller"] = caller;
@@ -8182,6 +8319,7 @@ const TemplateStatus = {
 const VerificationAttemptFailureReason = {
 	CarrierRejected: "carrier_rejected",
 	ChannelDisabled: "channel_disabled",
+	ChannelRestricted: "channel_restricted",
 	ChannelUnavailable: "channel_unavailable",
 	DeliveryTimeout: "delivery_timeout",
 	HardBounce: "hard_bounce",