Skip to content

AWS.PinpointSMSVoiceV2 reference

CarrierLookup

Section titled “CarrierLookup”

Source: packages/aws/src/PinpointSMSVoiceV2/CarrierLookup.ts

Runtime binding for sms-voice:CarrierLookup.

Looks up carrier metadata for a destination phone number — its E.164 normalization, country, carrier name, and number type (MOBILE, LANDLINE, VOIP, …). Use it to validate destinations before sending. Account-level: lookups act on raw phone numbers, so the deploy-time grant is sms-voice:CarrierLookup on *. Each lookup incurs a small per-request fee. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.CarrierLookupHttp).

CarrierLookup: Validating Destinations

Section titled “CarrierLookup: Validating Destinations”
// init — bind the account-level operation
const carrierLookup = yield* AWS.PinpointSMSVoiceV2.CarrierLookup();


// runtime
const info = yield* carrierLookup({ PhoneNumber: "+12065550100" });
const isMobile = info.PhoneNumberType === "MOBILE";

ConfigurationSet

Section titled “ConfigurationSet”

Source: packages/aws/src/PinpointSMSVoiceV2/ConfigurationSet.ts

An AWS End User Messaging SMS (Pinpoint SMS Voice v2) configuration set — a named set of rules applied to SMS and voice messages sent through it.

Attach EventDestinations to a configuration set to route message events (sends, deliveries, failures) to CloudWatch Logs, Kinesis Data Firehose, or SNS.

ConfigurationSet: Creating Configuration Sets

Section titled “ConfigurationSet: Creating Configuration Sets”

Basic Configuration Set

import * as PinpointSMSVoiceV2 from "@alchemy.run/aws/PinpointSMSVoiceV2";


const configSet = yield* PinpointSMSVoiceV2.ConfigurationSet("Messaging");

Configuration Set with a Default Message Type

const configSet = yield* PinpointSMSVoiceV2.ConfigurationSet("Otp", {
  defaultMessageType: "TRANSACTIONAL",
  tags: { team: "auth" },
});

ConfigurationSet: Event Destinations

Section titled “ConfigurationSet: Event Destinations”
const events = yield* SNS.Topic("SmsEvents");
const destination = yield* PinpointSMSVoiceV2.EventDestination("Events", {
  configurationSetName: configSet.configurationSetName,
  matchingEventTypes: ["ALL"],
  snsDestination: { topicArn: events.topicArn },
});

ConfigurationSet: Looking up an existing configuration set

Section titled “ConfigurationSet: Looking up an existing configuration set”

ConfigurationSet.lookup references a configuration set Alchemy doesn’t manage (created in the console or by another stack), found by configurationSetName. It is read during plan/deploy and never created, updated or deleted.

const existing = AWS.PinpointSMSVoiceV2.ConfigurationSet.lookup({ configurationSetName: "my-configuration-set" });

DeleteKeyword

Section titled “DeleteKeyword”

Source: packages/aws/src/PinpointSMSVoiceV2/DeleteKeyword.ts

Runtime binding for sms-voice:DeleteKeyword.

Deletes a keyword from the bound origination phone number. Keywords HELP and STOP cannot be deleted (they are carrier-mandated). The deploy-time half grants sms-voice:DeleteKeyword on the number. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.DeleteKeywordHttp).

DeleteKeyword: Managing Keywords

Section titled “DeleteKeyword: Managing Keywords”
// init
const deleteKeyword = yield* AWS.PinpointSMSVoiceV2.DeleteKeyword(number);


// runtime
yield* deleteKeyword({ Keyword: "INFO" });

DeleteOptedOutNumber

Section titled “DeleteOptedOutNumber”

Source: packages/aws/src/PinpointSMSVoiceV2/DeleteOptedOutNumber.ts

Runtime binding for sms-voice:DeleteOptedOutNumber.

Removes a destination phone number from the bound opt-out list, opting the end user back in to receiving messages. Numbers that opted themselves out by replying with a keyword can only be removed once every 30 days. The deploy-time half grants sms-voice:DeleteOptedOutNumber on the list. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.DeleteOptedOutNumberHttp).

DeleteOptedOutNumber: Managing Opt-Outs

Section titled “DeleteOptedOutNumber: Managing Opt-Outs”
// init
const deleteOptedOut =
  yield* AWS.PinpointSMSVoiceV2.DeleteOptedOutNumber(optOuts);


// runtime
yield* deleteOptedOut({ OptedOutNumber: "+12065550100" });

DescribeKeywords

Section titled “DescribeKeywords”

Source: packages/aws/src/PinpointSMSVoiceV2/DescribeKeywords.ts

Runtime binding for sms-voice:DescribeKeywords.

Lists the keywords configured on the bound origination phone number (one page per call — pass NextToken from the previous response to continue). The deploy-time half grants sms-voice:DescribeKeywords on the number. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.DescribeKeywordsHttp).

DescribeKeywords: Managing Keywords

Section titled “DescribeKeywords: Managing Keywords”
// init
const describeKeywords =
  yield* AWS.PinpointSMSVoiceV2.DescribeKeywords(number);


// runtime
const { Keywords } = yield* describeKeywords({});
const info = (Keywords ?? []).find((k) => k.Keyword === "INFO");

DescribeOptedOutNumbers

Section titled “DescribeOptedOutNumbers”

Source: packages/aws/src/PinpointSMSVoiceV2/DescribeOptedOutNumbers.ts

Runtime binding for sms-voice:DescribeOptedOutNumbers.

Lists the opted-out destination numbers in the bound opt-out list (one page per call — pass NextToken from the previous response to continue). Use it to check whether a number opted out before sending. The deploy-time half grants sms-voice:DescribeOptedOutNumbers on the list. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.DescribeOptedOutNumbersHttp).

DescribeOptedOutNumbers: Managing Opt-Outs

Section titled “DescribeOptedOutNumbers: Managing Opt-Outs”
// init
const describeOptedOut =
  yield* AWS.PinpointSMSVoiceV2.DescribeOptedOutNumbers(optOuts);


// runtime
const { OptedOutNumbers } = yield* describeOptedOut({
  OptedOutNumbers: ["+12065550100"],
});
const optedOut = (OptedOutNumbers ?? []).length > 0;

EventDestination

Section titled “EventDestination”

Source: packages/aws/src/PinpointSMSVoiceV2/EventDestination.ts

An AWS End User Messaging SMS (Pinpoint SMS Voice v2) event destination — routes message events (sends, deliveries, failures) from a ConfigurationSet to CloudWatch Logs, Kinesis Data Firehose, or SNS.

Each configuration set holds up to five event destinations; each event destination references exactly one delivery target.

EventDestination: Creating Event Destinations

Section titled “EventDestination: Creating Event Destinations”

Stream all events to SNS

import * as PinpointSMSVoiceV2 from "@alchemy.run/aws/PinpointSMSVoiceV2";
import * as SNS from "@alchemy.run/aws/SNS";


const configSet = yield* PinpointSMSVoiceV2.ConfigurationSet("Messaging");
const events = yield* SNS.Topic("SmsEvents");
const destination = yield* PinpointSMSVoiceV2.EventDestination("Events", {
  configurationSetName: configSet.configurationSetName,
  matchingEventTypes: ["ALL"],
  snsDestination: { topicArn: events.topicArn },
});

CloudWatch Logs destination

const destination = yield* PinpointSMSVoiceV2.EventDestination("Logs", {
  configurationSetName: configSet.configurationSetName,
  matchingEventTypes: ["TEXT_ALL"],
  cloudWatchLogsDestination: {
    iamRoleArn: role.roleArn,
    logGroupArn: logGroup.logGroupArn,
  },
});

Disable a destination without deleting it

const destination = yield* PinpointSMSVoiceV2.EventDestination("Events", {
  configurationSetName: configSet.configurationSetName,
  matchingEventTypes: ["ALL"],
  snsDestination: { topicArn: events.topicArn },
  enabled: false,
});

OptOutList

Section titled “OptOutList”

Source: packages/aws/src/PinpointSMSVoiceV2/OptOutList.ts

An AWS End User Messaging SMS (Pinpoint SMS Voice v2) opt-out list — a list of destination phone numbers that opted out of receiving your SMS or voice messages.

When an end user replies with a supported opt-out keyword (STOP, CANCEL, OPTOUT, …), their number is added to the list automatically and further messages to it are suppressed.

OptOutList: Creating Opt-Out Lists

Section titled “OptOutList: Creating Opt-Out Lists”

Basic Opt-Out List

import * as PinpointSMSVoiceV2 from "@alchemy.run/aws/PinpointSMSVoiceV2";


const optOuts = yield* PinpointSMSVoiceV2.OptOutList("OptOuts");

Named Opt-Out List with Tags

const optOuts = yield* PinpointSMSVoiceV2.OptOutList("OptOuts", {
  optOutListName: "marketing-opt-outs",
  tags: { team: "growth" },
});

OptOutList: Looking up an existing opt out list

Section titled “OptOutList: Looking up an existing opt out list”

OptOutList.lookup references an opt out list Alchemy doesn’t manage (created in the console or by another stack), found by optOutListName. It is read during plan/deploy and never created, updated or deleted.

const existing = AWS.PinpointSMSVoiceV2.OptOutList.lookup({ optOutListName: "my-opt-out-list" });

PhoneNumber

Section titled “PhoneNumber”

Source: packages/aws/src/PinpointSMSVoiceV2/PhoneNumber.ts

An AWS End User Messaging SMS (Pinpoint SMS Voice v2) origination phone number leased into your account.

Requesting a number incurs a monthly leasing fee and most number types require account-level entitlement (spending limits, registration). SIMULATOR numbers are the cheap, entitlement-free option for testing.

PhoneNumber: Requesting Phone Numbers

Section titled “PhoneNumber: Requesting Phone Numbers”

Simulator Number

import * as PinpointSMSVoiceV2 from "@alchemy.run/aws/PinpointSMSVoiceV2";


const number = yield* PinpointSMSVoiceV2.PhoneNumber("TestNumber", {
  isoCountryCode: "US",
  messageType: "TRANSACTIONAL",
  numberCapabilities: ["SMS"],
  numberType: "SIMULATOR",
});

Toll-Free Number with a Custom Opt-Out List

const optOuts = yield* PinpointSMSVoiceV2.OptOutList("OptOuts");
const number = yield* PinpointSMSVoiceV2.PhoneNumber("Sender", {
  isoCountryCode: "US",
  messageType: "TRANSACTIONAL",
  numberCapabilities: ["SMS", "VOICE"],
  numberType: "TOLL_FREE",
  optOutListName: optOuts.optOutListName,
});

PhoneNumber: Looking up an existing phone number

Section titled “PhoneNumber: Looking up an existing phone number”

PhoneNumber.lookup references a phone number Alchemy doesn’t manage (created in the console or by another stack), found by phoneNumberId. It is read during plan/deploy and never created, updated or deleted.

const existing = AWS.PinpointSMSVoiceV2.PhoneNumber.lookup({ phoneNumberId: "..." });

PutKeyword

Section titled “PutKeyword”

Source: packages/aws/src/PinpointSMSVoiceV2/PutKeyword.ts

Runtime binding for sms-voice:PutKeyword.

Creates or updates a keyword on the bound origination phone number — when an end user texts the keyword to the number, End User Messaging SMS automatically replies with KeywordMessage (or opts them out / back in when KeywordAction is set). The deploy-time half grants sms-voice:PutKeyword on the number. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.PutKeywordHttp).

PutKeyword: Managing Keywords

Section titled “PutKeyword: Managing Keywords”
// init
const putKeyword = yield* AWS.PinpointSMSVoiceV2.PutKeyword(number);


// runtime
yield* putKeyword({
  Keyword: "INFO",
  KeywordMessage: "Visit https://example.com for details.",
});

PutMessageFeedback

Section titled “PutMessageFeedback”

Source: packages/aws/src/PinpointSMSVoiceV2/PutMessageFeedback.ts

Runtime binding for sms-voice:PutMessageFeedback.

Marks a sent message’s feedback record as RECEIVED or FAILED. When a message is sent with MessageFeedbackEnabled: true, End User Messaging SMS waits for this signal — set RECEIVED when your application observes the user acting on the message (e.g. entering the one-time passcode); records not updated within an hour are marked FAILED. Account-level: feedback acts on message IDs, so the deploy-time grant is sms-voice:PutMessageFeedback on *. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.PutMessageFeedbackHttp).

PutMessageFeedback: Message Feedback

Section titled “PutMessageFeedback: Message Feedback”
// init — bind the account-level operation
const putFeedback = yield* AWS.PinpointSMSVoiceV2.PutMessageFeedback();


// runtime — after the user enters the code sent in `MessageId`
yield* putFeedback({
  MessageId: messageId,
  MessageFeedbackStatus: "RECEIVED",
});

PutOptedOutNumber

Section titled “PutOptedOutNumber”

Source: packages/aws/src/PinpointSMSVoiceV2/PutOptedOutNumber.ts

Runtime binding for sms-voice:PutOptedOutNumber.

Adds a destination phone number to the bound opt-out list — further messages to it through numbers using this list are suppressed. Use it to honor opt-out requests arriving through channels other than the carrier keywords (support tickets, web forms). The deploy-time half grants sms-voice:PutOptedOutNumber on the list. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.PutOptedOutNumberHttp).

PutOptedOutNumber: Managing Opt-Outs

Section titled “PutOptedOutNumber: Managing Opt-Outs”
// init
const optOuts = yield* AWS.PinpointSMSVoiceV2.OptOutList("OptOuts");
const putOptedOut = yield* AWS.PinpointSMSVoiceV2.PutOptedOutNumber(optOuts);


// runtime
yield* putOptedOut({ OptedOutNumber: "+12065550100" });

SendMediaMessage

Section titled “SendMediaMessage”

Source: packages/aws/src/PinpointSMSVoiceV2/SendMediaMessage.ts

Runtime binding for sms-voice:SendMediaMessage.

Sends a multimedia message (MMS) from the bound origination phone number. MediaUrls reference S3 objects (s3://bucket/key) holding the attachments. The deploy-time half grants sms-voice:SendMediaMessage on the number and the runtime half injects its ARN as the request’s OriginationIdentity. The bound number must carry the MMS capability. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.SendMediaMessageHttp).

SendMediaMessage: Sending Media Messages

Section titled “SendMediaMessage: Sending Media Messages”
// init
const sendMedia = yield* AWS.PinpointSMSVoiceV2.SendMediaMessage(number);


// runtime
const { MessageId } = yield* sendMedia({
  DestinationPhoneNumber: "+12065550100",
  MessageBody: "Here is your receipt",
  MediaUrls: ["s3://my-bucket/receipts/1234.png"],
});

SendTextMessage

Section titled “SendTextMessage”

Source: packages/aws/src/PinpointSMSVoiceV2/SendTextMessage.ts

Runtime binding for sms-voice:SendTextMessage.

Sends an SMS message from the bound origination phone number to one recipient — the effectful call made from a deployed Lambda or Task. The deploy-time half grants sms-voice:SendTextMessage on the number and the runtime half injects its ARN as the request’s OriginationIdentity. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.SendTextMessageHttp).

SendTextMessage: Sending Text Messages

Section titled “SendTextMessage: Sending Text Messages”
// init — lease a number and bind the send operation
const number = yield* AWS.PinpointSMSVoiceV2.PhoneNumber("Sender", {
  isoCountryCode: "US",
  messageType: "TRANSACTIONAL",
  numberCapabilities: ["SMS"],
  numberType: "TOLL_FREE",
});
const sendText = yield* AWS.PinpointSMSVoiceV2.SendTextMessage(number);


// runtime
const { MessageId } = yield* sendText({
  DestinationPhoneNumber: "+12065550100",
  MessageBody: "Your code is 123456",
  MessageType: "TRANSACTIONAL",
});

SendVoiceMessage

Section titled “SendVoiceMessage”

Source: packages/aws/src/PinpointSMSVoiceV2/SendVoiceMessage.ts

Runtime binding for sms-voice:SendVoiceMessage.

Sends a voice message from the bound origination phone number — Amazon Polly converts the text (or SSML) MessageBody into speech. The deploy-time half grants sms-voice:SendVoiceMessage on the number and the runtime half injects its ARN as the request’s OriginationIdentity. The bound number must carry the VOICE capability. Provide the implementation with Effect.provide(AWS.PinpointSMSVoiceV2.SendVoiceMessageHttp).

SendVoiceMessage: Sending Voice Messages

Section titled “SendVoiceMessage: Sending Voice Messages”
// init
const sendVoice = yield* AWS.PinpointSMSVoiceV2.SendVoiceMessage(number);


// runtime
const { MessageId } = yield* sendVoice({
  DestinationPhoneNumber: "+12065550100",
  MessageBody: "Your appointment is confirmed for tomorrow at nine A M.",
  MessageBodyTextType: "TEXT",
  VoiceId: "JOANNA",
});