Skip to content

AWS.PinpointSMSVoiceV2 reference

CarrierLookup

Section titled “CarrierLookup”

Source: src/AWS/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: src/AWS/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/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 },
});

DeleteKeyword

Section titled “DeleteKeyword”

Source: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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/AWS/PinpointSMSVoiceV2";
import * as SNS from "alchemy/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: src/AWS/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/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" },
});

PhoneNumber

Section titled “PhoneNumber”

Source: src/AWS/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/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,
});

PutKeyword

Section titled “PutKeyword”

Source: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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: src/AWS/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",
});