- Navigation GuideYou are on a Command (operation) page with structural examples. Use the navigation breadcrumb if you would like to return to the Client landing page.
PublishCommand
Sends a message to an Amazon SNS topic, a text message (SMS message) directly to a phone number, or a message to a mobile platform endpoint (when you specify the TargetArn
).
If you send a message to a topic, Amazon SNS delivers the message to each endpoint that is subscribed to the topic. The format of the message depends on the notification protocol for each subscribed endpoint.
When a messageId
is returned, the message is saved and Amazon SNS immediately delivers it to subscribers.
To use the Publish
action for publishing a message to a mobile endpoint, such as an app on a Kindle device or mobile phone, you must specify the EndpointArn for the TargetArn parameter. The EndpointArn is returned when making a call with the CreatePlatformEndpoint
action.
For more information about formatting messages, see Send Custom Platform-Specific Payloads in Messages to Mobile Devices .
You can publish messages only to topics and endpoints in the same Amazon Web Services Region.
Example Syntax
Use a bare-bones client and the command you need to make an API call.
import { SNSClient, PublishCommand } from "@aws-sdk/client-sns"; // ES Modules import
// const { SNSClient, PublishCommand } = require("@aws-sdk/client-sns"); // CommonJS import
const client = new SNSClient(config);
const input = { // PublishInput
TopicArn: "STRING_VALUE",
TargetArn: "STRING_VALUE",
PhoneNumber: "STRING_VALUE",
Message: "STRING_VALUE", // required
Subject: "STRING_VALUE",
MessageStructure: "STRING_VALUE",
MessageAttributes: { // MessageAttributeMap
"<keys>": { // MessageAttributeValue
DataType: "STRING_VALUE", // required
StringValue: "STRING_VALUE",
BinaryValue: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
},
},
MessageDeduplicationId: "STRING_VALUE",
MessageGroupId: "STRING_VALUE",
};
const command = new PublishCommand(input);
const response = await client.send(command);
// { // PublishResponse
// MessageId: "STRING_VALUE",
// SequenceNumber: "STRING_VALUE",
// };
PublishCommand Input
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
Message Required | string | undefined | The message you want to send. If you are publishing to a topic and you want to send the same message to all transport protocols, include the text of the message as a String value. If you want to send different messages for each transport protocol, set the value of the Constraints:
JSON-specific constraints:
|
MessageAttributes | Record<string, MessageAttributeValue> | undefined | Message attributes for Publish action. |
MessageDeduplicationId | string | undefined |
|
MessageGroupId | string | undefined | This parameter applies only to FIFO (first-in-first-out) topics. The The |
MessageStructure | string | undefined | Set
You can define other top-level keys that define the message you want to send to a specific transport protocol (e.g., "http"). Valid value: |
PhoneNumber | string | undefined | The phone number to which you want to deliver an SMS message. Use E.164 format. If you don't specify a value for the |
Subject | string | undefined | Optional parameter to be used as the "Subject" line when the message is delivered to email endpoints. This field will also be included, if present, in the standard JSON messages delivered to other endpoints. Constraints: Subjects must be UTF-8 text with no line breaks or control characters, and less than 100 characters long. |
TargetArn | string | undefined | If you don't specify a value for the |
TopicArn | string | undefined | The topic you want to publish to. If you don't specify a value for the |
PublishCommand Output
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
$metadata Required | ResponseMetadata | Metadata pertaining to this request. |
MessageId | string | undefined | Unique identifier assigned to the published message. Length Constraint: Maximum 100 characters |
SequenceNumber | string | undefined | This response element applies only to FIFO (first-in-first-out) topics. The sequence number is a large, non-consecutive number that Amazon SNS assigns to each message. The length of |
Throws
Name | Fault | Details |
---|
Name | Fault | Details |
---|---|---|
AuthorizationErrorException | client | Indicates that the user has been denied access to the requested resource. |
EndpointDisabledException | client | Exception error indicating endpoint disabled. |
InternalErrorException | server | Indicates an internal service error. |
InvalidParameterException | client | Indicates that a request parameter does not comply with the associated constraints. |
InvalidParameterValueException | client | Indicates that a request parameter does not comply with the associated constraints. |
InvalidSecurityException | client | The credential signature isn't valid. You must use an HTTPS endpoint and sign your request using Signature Version 4. |
KMSAccessDeniedException | client | The ciphertext references a key that doesn't exist or that you don't have access to. |
KMSDisabledException | client | The request was rejected because the specified Amazon Web Services KMS key isn't enabled. |
KMSInvalidStateException | client | The request was rejected because the state of the specified resource isn't valid for this request. For more information, see Key states of Amazon Web Services KMS keys in the Key Management Service Developer Guide. |
KMSNotFoundException | client | The request was rejected because the specified entity or resource can't be found. |
KMSOptInRequired | client | The Amazon Web Services access key ID needs a subscription for the service. |
KMSThrottlingException | client | The request was denied due to request throttling. For more information about throttling, see Limits in the Key Management Service Developer Guide. |
NotFoundException | client | Indicates that the requested resource does not exist. |
PlatformApplicationDisabledException | client | Exception error indicating platform application disabled. |
ValidationException | client | Indicates that a parameter in the request is invalid. |
SNSServiceException | Base exception class for all service exceptions from SNS service. |