AWS.SocialMessaging reference

CreateWhatsAppFlow

Source: src/AWS/SocialMessaging/CreateWhatsAppFlow.ts

Runtime binding for social-messaging:CreateWhatsAppFlow.

Creates a WhatsApp Flow (a rich interactive form users complete inside WhatsApp) on the bound account, in DRAFT status unless publish is set with a valid flowJson.

The deploy-time half grants social-messaging:CreateWhatsAppFlow on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.CreateWhatsAppFlowHttp).

CreateWhatsAppFlow: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const createFlow = yield* AWS.SocialMessaging.CreateWhatsAppFlow(account);

// runtime
const { flowId, validationErrors } = yield* createFlow({
  flowName: "appointment-booking",
  categories: ["APPOINTMENT_BOOKING"],
});

CreateWhatsAppMessageTemplate

Source: src/AWS/SocialMessaging/CreateWhatsAppMessageTemplate.ts

Runtime binding for social-messaging:CreateWhatsAppMessageTemplate.

Creates a WhatsApp message template on the bound account from a raw Meta template-definition JSON blob. Templates must be approved by Meta before they can be sent.

The deploy-time half grants social-messaging:CreateWhatsAppMessageTemplate on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.CreateWhatsAppMessageTemplateHttp).

CreateWhatsAppMessageTemplate: Managing Message Templates

// init — bind the operation to the linked WABA
const createTemplate = yield* AWS.SocialMessaging.CreateWhatsAppMessageTemplate(account);

// runtime
const { metaTemplateId, templateStatus } = yield* createTemplate({
  templateDefinition: new TextEncoder().encode(
    JSON.stringify({
      name: "order_update",
      language: "en_US",
      category: "UTILITY",
      components: [{ type: "BODY", text: "Your order {{1}} shipped." }],
    }),
  ),
});

CreateWhatsAppMessageTemplateFromLibrary

Source: src/AWS/SocialMessaging/CreateWhatsAppMessageTemplateFromLibrary.ts

Runtime binding for social-messaging:CreateWhatsAppMessageTemplateFromLibrary.

Creates a WhatsApp message template on the bound account from one of the pre-approved templates in Meta’s template library.

The deploy-time half grants social-messaging:CreateWhatsAppMessageTemplateFromLibrary on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.CreateWhatsAppMessageTemplateFromLibraryHttp).

CreateWhatsAppMessageTemplateFromLibrary: Managing Message Templates

// init — bind the operation to the linked WABA
const createFromLibrary = yield* AWS.SocialMessaging.CreateWhatsAppMessageTemplateFromLibrary(account);

// runtime
const { metaTemplateId } = yield* createFromLibrary({
  metaLibraryTemplate: {
    templateName: "order_shipped",
    libraryTemplateName: "shipment_confirmation",
    templateCategory: "UTILITY",
    templateLanguage: "en_US",
  },
});

CreateWhatsAppMessageTemplateMedia

Source: src/AWS/SocialMessaging/CreateWhatsAppMessageTemplateMedia.ts

Runtime binding for social-messaging:CreateWhatsAppMessageTemplateMedia.

Uploads media (from S3) for use in a WhatsApp message template header and returns the Meta header handle to reference from the template definition.

The deploy-time half grants social-messaging:CreateWhatsAppMessageTemplateMedia on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.CreateWhatsAppMessageTemplateMediaHttp).

CreateWhatsAppMessageTemplateMedia: Managing Message Templates

// init — bind the operation to the linked WABA
const uploadTemplateMedia = yield* AWS.SocialMessaging.CreateWhatsAppMessageTemplateMedia(account);

// runtime
const { metaHeaderHandle } = yield* uploadTemplateMedia({
  sourceS3File: { bucketName: "my-assets", key: "header.png" },
});

DeleteWhatsAppFlow

Source: src/AWS/SocialMessaging/DeleteWhatsAppFlow.ts

Runtime binding for social-messaging:DeleteWhatsAppFlow.

Deletes a DRAFT WhatsApp Flow from the bound account. Published flows must be deprecated instead.

The deploy-time half grants social-messaging:DeleteWhatsAppFlow on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.DeleteWhatsAppFlowHttp).

DeleteWhatsAppFlow: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const deleteFlow = yield* AWS.SocialMessaging.DeleteWhatsAppFlow(account);

// runtime
yield* deleteFlow({ flowId: "1234567890" });

DeleteWhatsAppMessageMedia

Source: src/AWS/SocialMessaging/DeleteWhatsAppMessageMedia.ts

Runtime binding for social-messaging:DeleteWhatsAppMessageMedia.

Deletes a media file previously uploaded to WhatsApp from the given phone number.

The caller addresses one of the bound account’s phone numbers per request; phone-number ARNs are provisioned by Meta under the WABA, so the deploy-time half grants social-messaging:DeleteWhatsAppMessageMedia on *. Provide the implementation with Effect.provide(AWS.SocialMessaging.DeleteWhatsAppMessageMediaHttp).

DeleteWhatsAppMessageMedia: Managing Message Media

// init — bind the operation to the linked WABA
const deleteMedia = yield* AWS.SocialMessaging.DeleteWhatsAppMessageMedia(account);

// runtime
const { success } = yield* deleteMedia({
  mediaId: "media-id-to-delete",
  originationPhoneNumberId: "phone-number-id-0123456789abcdef",
});

DeleteWhatsAppMessageTemplate

Source: src/AWS/SocialMessaging/DeleteWhatsAppMessageTemplate.ts

Runtime binding for social-messaging:DeleteWhatsAppMessageTemplate.

Deletes a WhatsApp message template from the bound account, optionally across all of its languages.

The deploy-time half grants social-messaging:DeleteWhatsAppMessageTemplate on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.DeleteWhatsAppMessageTemplateHttp).

DeleteWhatsAppMessageTemplate: Managing Message Templates

// init — bind the operation to the linked WABA
const deleteTemplate = yield* AWS.SocialMessaging.DeleteWhatsAppMessageTemplate(account);

// runtime
yield* deleteTemplate({
  templateName: "order_update",
  deleteAllLanguages: true,
});

DeprecateWhatsAppFlow

Source: src/AWS/SocialMessaging/DeprecateWhatsAppFlow.ts

Runtime binding for social-messaging:DeprecateWhatsAppFlow.

Deprecates a published WhatsApp Flow on the bound account so it can no longer be sent to users.

The deploy-time half grants social-messaging:DeprecateWhatsAppFlow on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.DeprecateWhatsAppFlowHttp).

DeprecateWhatsAppFlow: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const deprecateFlow = yield* AWS.SocialMessaging.DeprecateWhatsAppFlow(account);

// runtime
yield* deprecateFlow({ flowId: "1234567890" });

GetLinkedWhatsAppBusinessAccountPhoneNumber

Source: src/AWS/SocialMessaging/GetLinkedWhatsAppBusinessAccountPhoneNumber.ts

Runtime binding for social-messaging:GetLinkedWhatsAppBusinessAccountPhoneNumber.

Retrieves the details (display name, quality rating, Meta ids) of one of the linked account’s WhatsApp phone numbers, plus the owning WABA id.

The caller addresses one of the bound account’s phone numbers per request; phone-number ARNs are provisioned by Meta under the WABA, so the deploy-time half grants social-messaging:GetLinkedWhatsAppBusinessAccountPhoneNumber on *. Provide the implementation with Effect.provide(AWS.SocialMessaging.GetLinkedWhatsAppBusinessAccountPhoneNumberHttp).

GetLinkedWhatsAppBusinessAccountPhoneNumber: Reading Phone Numbers

// init — bind the operation to the linked WABA
const getPhoneNumber = yield* AWS.SocialMessaging.GetLinkedWhatsAppBusinessAccountPhoneNumber(account);

// runtime
const details = yield* getPhoneNumber({
  id: "phone-number-id-0123456789abcdef",
});
const rating = details.phoneNumber?.qualityRating;

GetWhatsAppFlow

Source: src/AWS/SocialMessaging/GetWhatsAppFlow.ts

Runtime binding for social-messaging:GetWhatsAppFlow.

Retrieves a WhatsApp Flow’s details — status, categories, validation errors, health status — from the bound account.

The deploy-time half grants social-messaging:GetWhatsAppFlow on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.GetWhatsAppFlowHttp).

GetWhatsAppFlow: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const getFlow = yield* AWS.SocialMessaging.GetWhatsAppFlow(account);

// runtime
const flow = yield* getFlow({ flowId: "1234567890" });
const publishable = flow.validationErrors?.length === 0;

GetWhatsAppFlowPreview

Source: src/AWS/SocialMessaging/GetWhatsAppFlowPreview.ts

Runtime binding for social-messaging:GetWhatsAppFlowPreview.

Generates (or refreshes with invalidate) a shareable preview URL for a WhatsApp Flow on the bound account.

The deploy-time half grants social-messaging:GetWhatsAppFlowPreview on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.GetWhatsAppFlowPreviewHttp).

GetWhatsAppFlowPreview: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const getFlowPreview = yield* AWS.SocialMessaging.GetWhatsAppFlowPreview(account);

// runtime
const { preview } = yield* getFlowPreview({
  flowId: "1234567890",
  invalidate: true,
});

GetWhatsAppMessageMedia

Source: src/AWS/SocialMessaging/GetWhatsAppMessageMedia.ts

Runtime binding for social-messaging:GetWhatsAppMessageMedia.

Retrieves a media file received in a WhatsApp message — either just its metadata (metadataOnly: true) or a full download into an S3 object or presigned URL.

The caller addresses one of the bound account’s phone numbers per request; phone-number ARNs are provisioned by Meta under the WABA, so the deploy-time half grants social-messaging:GetWhatsAppMessageMedia on *. Provide the implementation with Effect.provide(AWS.SocialMessaging.GetWhatsAppMessageMediaHttp).

GetWhatsAppMessageMedia: Managing Message Media

// init — bind the operation to the linked WABA
const getMedia = yield* AWS.SocialMessaging.GetWhatsAppMessageMedia(account);

// runtime
const { mimeType, fileSize } = yield* getMedia({
  mediaId: "media-id-from-inbound-event",
  originationPhoneNumberId: "phone-number-id-0123456789abcdef",
  destinationS3File: { bucketName: "my-inbox", key: "media/inbound" },
});

GetWhatsAppMessageTemplate

Source: src/AWS/SocialMessaging/GetWhatsAppMessageTemplate.ts

Runtime binding for social-messaging:GetWhatsAppMessageTemplate.

Retrieves a WhatsApp message template’s JSON definition from the bound account by its Meta template id.

The deploy-time half grants social-messaging:GetWhatsAppMessageTemplate on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.GetWhatsAppMessageTemplateHttp).

GetWhatsAppMessageTemplate: Managing Message Templates

// init — bind the operation to the linked WABA
const getTemplate = yield* AWS.SocialMessaging.GetWhatsAppMessageTemplate(account);

// runtime
const { template } = yield* getTemplate({
  metaTemplateId: "1234567890",
});

LinkedWhatsAppBusinessAccount

Source: src/AWS/SocialMessaging/LinkedWhatsAppBusinessAccount.ts

A WhatsApp Business Account (WABA) linked to your AWS account through AWS End User Messaging Social.

Caution

Linking a WhatsApp Business Account requires the Meta embedded-signup OAuth flow in the AWS console and cannot be automated. This resource adopts an already-linked account by its waba-... identifier and manages its event destinations and tags. Destroying the resource disassociates the WhatsApp Business Account from your AWS account.

LinkedWhatsAppBusinessAccount: Managing a Linked Account

import * as AWS from "alchemy/AWS";

const events = yield* AWS.SNS.Topic("WhatsAppEvents", {});

const waba = yield* AWS.SocialMessaging.LinkedWhatsAppBusinessAccount(
  "Business",
  {
    // from the AWS End User Messaging Social console after onboarding
    accountId: "waba-0123456789abcdef0123456789abcdef",
    eventDestinations: [{ eventDestinationArn: events.topicArn }],
    tags: { team: "growth" },
  },
);

LinkedWhatsAppBusinessAccount: Consuming WhatsApp Events

WhatsApp events (inbound messages, message status updates) are delivered exclusively to the SNS topics listed in eventDestinations — there is no separate event source for this service. Compose the resource with AWS.SNS.consumeTopicNotifications on the destination topic:

const events = yield* AWS.SNS.Topic("WhatsAppEvents", {});

const waba = yield* AWS.SocialMessaging.LinkedWhatsAppBusinessAccount(
  "Business",
  {
    accountId: "waba-0123456789abcdef0123456789abcdef",
    eventDestinations: [{ eventDestinationArn: events.topicArn }],
  },
);

// inside a Lambda Function's init effect
yield* AWS.SNS.consumeTopicNotifications(events, (stream) =>
  stream.pipe(
    Stream.runForEach((notification) =>
      Effect.log("whatsapp event", notification.Message),
    ),
  ),
);

ListWhatsAppFlowAssets

Source: src/AWS/SocialMessaging/ListWhatsAppFlowAssets.ts

Runtime binding for social-messaging:ListWhatsAppFlowAssets.

Lists the assets (Flow JSON) of a WhatsApp Flow on the bound account, with download URLs.

The deploy-time half grants social-messaging:ListWhatsAppFlowAssets on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.ListWhatsAppFlowAssetsHttp).

ListWhatsAppFlowAssets: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const listFlowAssets = yield* AWS.SocialMessaging.ListWhatsAppFlowAssets(account);

// runtime
const { flowAssets } = yield* listFlowAssets({
  flowId: "1234567890",
});

ListWhatsAppFlows

Source: src/AWS/SocialMessaging/ListWhatsAppFlows.ts

Runtime binding for social-messaging:ListWhatsAppFlows.

Lists the WhatsApp Flows of the bound account with their status and validation errors.

The deploy-time half grants social-messaging:ListWhatsAppFlows on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.ListWhatsAppFlowsHttp).

ListWhatsAppFlows: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const listFlows = yield* AWS.SocialMessaging.ListWhatsAppFlows(account);

// runtime
const { flows } = yield* listFlows({ maxResults: 25 });

ListWhatsAppMessageTemplates

Source: src/AWS/SocialMessaging/ListWhatsAppMessageTemplates.ts

Runtime binding for social-messaging:ListWhatsAppMessageTemplates.

Lists the WhatsApp message templates of the bound account, with their Meta review status and quality score.

The deploy-time half grants social-messaging:ListWhatsAppMessageTemplates on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.ListWhatsAppMessageTemplatesHttp).

ListWhatsAppMessageTemplates: Managing Message Templates

// init — bind the operation to the linked WABA
const listTemplates = yield* AWS.SocialMessaging.ListWhatsAppMessageTemplates(account);

// runtime
const { templates } = yield* listTemplates({ maxResults: 25 });

ListWhatsAppTemplateLibrary

Source: src/AWS/SocialMessaging/ListWhatsAppTemplateLibrary.ts

Runtime binding for social-messaging:ListWhatsAppTemplateLibrary.

Lists the pre-approved templates available in Meta’s template library, optionally filtered by category, topic, or industry.

The deploy-time half grants social-messaging:ListWhatsAppTemplateLibrary on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.ListWhatsAppTemplateLibraryHttp).

ListWhatsAppTemplateLibrary: Managing Message Templates

// init — bind the operation to the linked WABA
const browseLibrary = yield* AWS.SocialMessaging.ListWhatsAppTemplateLibrary(account);

// runtime
const { metaLibraryTemplates } = yield* browseLibrary({
  filters: { category: "UTILITY" },
});

PostWhatsAppMessageMedia

Source: src/AWS/SocialMessaging/PostWhatsAppMessageMedia.ts

Runtime binding for social-messaging:PostWhatsAppMessageMedia.

Uploads a media file to WhatsApp (from an S3 object or presigned URL) so it can be referenced by mediaId in outbound messages sent from the given phone number.

The caller addresses one of the bound account’s phone numbers per request; phone-number ARNs are provisioned by Meta under the WABA, so the deploy-time half grants social-messaging:PostWhatsAppMessageMedia on *. Provide the implementation with Effect.provide(AWS.SocialMessaging.PostWhatsAppMessageMediaHttp).

PostWhatsAppMessageMedia: Managing Message Media

// init — bind the operation to the linked WABA
const postMedia = yield* AWS.SocialMessaging.PostWhatsAppMessageMedia(account);

// runtime
const { mediaId } = yield* postMedia({
  originationPhoneNumberId: "phone-number-id-0123456789abcdef",
  sourceS3File: { bucketName: "my-assets", key: "welcome.png" },
});

PublishWhatsAppFlow

Source: src/AWS/SocialMessaging/PublishWhatsAppFlow.ts

Runtime binding for social-messaging:PublishWhatsAppFlow.

Publishes a DRAFT WhatsApp Flow on the bound account so it can be sent to users. Published flows can no longer be edited, only deprecated.

The deploy-time half grants social-messaging:PublishWhatsAppFlow on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.PublishWhatsAppFlowHttp).

PublishWhatsAppFlow: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const publishFlow = yield* AWS.SocialMessaging.PublishWhatsAppFlow(account);

// runtime
yield* publishFlow({ flowId: "1234567890" });

SendWhatsAppMessage

Source: src/AWS/SocialMessaging/SendWhatsAppMessage.ts

Runtime binding for social-messaging:SendWhatsAppMessage.

Sends a WhatsApp message (text, template, media, or interactive) from one of the linked account’s phone numbers. The message blob is the raw Meta Cloud API message payload and is sensitive — pass it as a Uint8Array or Redacted<Uint8Array>.

The caller addresses one of the bound account’s phone numbers per request; phone-number ARNs are provisioned by Meta under the WABA, so the deploy-time half grants social-messaging:SendWhatsAppMessage on *. Provide the implementation with Effect.provide(AWS.SocialMessaging.SendWhatsAppMessageHttp).

SendWhatsAppMessage: Sending Messages

// init — bind the operation to the linked WABA
const sendMessage = yield* AWS.SocialMessaging.SendWhatsAppMessage(account);

// runtime
const { messageId } = yield* sendMessage({
  originationPhoneNumberId: "phone-number-id-0123456789abcdef",
  metaApiVersion: "v20.0",
  message: new TextEncoder().encode(
    JSON.stringify({
      messaging_product: "whatsapp",
      to: "+12065550100",
      type: "text",
      text: { body: "Hello from Alchemy" },
    }),
  ),
});

UpdateWhatsAppFlow

Source: src/AWS/SocialMessaging/UpdateWhatsAppFlow.ts

Runtime binding for social-messaging:UpdateWhatsAppFlow.

Updates a WhatsApp Flow’s name and categories on the bound account.

The deploy-time half grants social-messaging:UpdateWhatsAppFlow on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.UpdateWhatsAppFlowHttp).

UpdateWhatsAppFlow: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const updateFlow = yield* AWS.SocialMessaging.UpdateWhatsAppFlow(account);

// runtime
yield* updateFlow({
  flowId: "1234567890",
  flowName: "appointment-booking-v2",
});

UpdateWhatsAppFlowAssets

Source: src/AWS/SocialMessaging/UpdateWhatsAppFlowAssets.ts

Runtime binding for social-messaging:UpdateWhatsAppFlowAssets.

Replaces a WhatsApp Flow’s Flow JSON asset on the bound account and returns any validation errors Meta reports.

The deploy-time half grants social-messaging:UpdateWhatsAppFlowAssets on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.UpdateWhatsAppFlowAssetsHttp).

UpdateWhatsAppFlowAssets: Managing WhatsApp Flows

// init — bind the operation to the linked WABA
const updateFlowAssets = yield* AWS.SocialMessaging.UpdateWhatsAppFlowAssets(account);

// runtime
const { validationErrors } = yield* updateFlowAssets({
  flowId: "1234567890",
  flowJson: new TextEncoder().encode(JSON.stringify(flowDefinition)),
});

UpdateWhatsAppMessageTemplate

Source: src/AWS/SocialMessaging/UpdateWhatsAppMessageTemplate.ts

Runtime binding for social-messaging:UpdateWhatsAppMessageTemplate.

Updates an existing WhatsApp message template on the bound account — its category or component JSON. Edits re-enter Meta review.

The deploy-time half grants social-messaging:UpdateWhatsAppMessageTemplate on the bound WABA’s ARN and the runtime half injects the linked account id into every request. Provide the implementation with Effect.provide(AWS.SocialMessaging.UpdateWhatsAppMessageTemplateHttp).

UpdateWhatsAppMessageTemplate: Managing Message Templates

// init — bind the operation to the linked WABA
const updateTemplate = yield* AWS.SocialMessaging.UpdateWhatsAppMessageTemplate(account);

// runtime
yield* updateTemplate({
  metaTemplateId: "1234567890",
  templateComponents: new TextEncoder().encode(
    JSON.stringify([{ type: "BODY", text: "Order {{1}} delivered." }]),
  ),
});