OTP Message - Amazon Pinpoint
URIHTTP methodsSchemasPropertiesSee also

OTP Message

Use this resource to generate a One-Time Password (OTP) and send it to a user of your application. When the user enters the OTP code in your application, use the the Verify OTP resource to confirm the validity of the OTP.

URI

/v1/apps/application-id/otp

HTTP methods

POST

Operation ID: SendOTPMessage

Use this operation to send an OTP code to a user of your application. When you use this API, Amazon Pinpoint generates a random code and sends it to your user.

Path parameters
NameTypeRequiredDescription
application-idStringTrue

The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.

Header parameters
NameTypeRequiredDescription
acceptStringFalse

Indicates which content types, expressed as MIME types, the client understands.

Responses
Status codeResponse modelDescription
200MessageResponse

200 response

400MessageBody

The request contains a syntax error (BadRequestException).

403MessageBody

The request was denied because access to the specified resource is forbidden (ForbiddenException).

404MessageBody

The request failed because the specified resource was not found (NotFoundException).

405MessageBody

The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).

413MessageBody

The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).

429MessageBody

The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).

500MessageBody

The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

OPTIONS

Path parameters
NameTypeRequiredDescription
application-idStringTrue

The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.

Responses
Status codeResponse modelDescription
200None

The request succeeded.

Schemas

Request bodies

{
  "Channel": "string",
  "OriginationIdentity": "string",
  "DestinationIdentity": "string",
  "BrandName": "string",
  "Language": "string",
  "CodeLength": integer,
  "ValidityPeriod": integer,
  "ReferenceId": "string",
  "AllowedAttempts": integer,
  "EntityId": "string",
  "TemplateId": "string"
}

Response bodies

{
  "ApplicationId": "string",
  "RequestId": "string",
  "Result": {
  },
  "EndpointResult": {
  }
}
{
  "RequestID": "string",
  "Message": "string"
}

Properties

EndpointMessageResult

Provides information about the delivery status and results of sending a message directly to an endpoint.

PropertyTypeRequiredDescription
Address

string

False

The endpoint address that the message was delivered to.

DeliveryStatus

string

Values: SUCCESSFUL | THROTTLED | TEMPORARY_FAILURE | PERMANENT_FAILURE | UNKNOWN_FAILURE | OPT_OUT | DUPLICATE

True

The delivery status of the message. Possible values are:

  • DUPLICATE – The endpoint address is a duplicate of another endpoint address. Amazon Pinpoint won't attempt to send the message again.

  • OPT_OUT – The SendMessages API does not honor the endpoint OPT_OUT status.

  • PERMANENT_FAILURE – An error occurred when delivering the message to the endpoint. Amazon Pinpoint won't attempt to send the message again.

  • SUCCESSFUL – The message was successfully delivered to the endpoint.

  • TEMPORARY_FAILURE – A temporary error occurred. Amazon Pinpoint won't attempt to send the message again.

  • THROTTLED – Amazon Pinpoint throttled the operation to send the message to the endpoint.

  • UNKNOWN_FAILURE – An unknown error occurred.

MessageId

string

False

The unique identifier for the message that was sent.

StatusCode

integer

True

The downstream service status code for delivering the message.

StatusMessage

string

False

The status message for delivering the message.

UpdatedToken

string

False

For push notifications that are sent through the GCM channel, specifies whether the endpoint's device registration token was updated as part of delivering the message.

MessageBody

Provides information about an API request or response.

PropertyTypeRequiredDescription
Message

string

False

The message that's returned from the API.

RequestID

string

False

The unique identifier for the request or response.

MessageResponse

Provides information about the results of a request to send a message to an endpoint address.

PropertyTypeRequiredDescription
ApplicationId

string

True

The unique identifier for the application that was used to send the message.

EndpointResult

object

False

A map that contains a multipart response for each address that the message was sent to. In the map, the endpoint ID is the key and the result is the value.

RequestId

string

False

The identifier for the original request that the message was delivered for.

Result

object

False

A map that contains a multipart response for each address (email address, phone number, or push notification token) that the message was sent to. In the map, the address is the key and the result is the value.

MessageResult

Provides information about the results of sending a message directly to an endpoint address.

PropertyTypeRequiredDescription
DeliveryStatus

string

Values: SUCCESSFUL | THROTTLED | TEMPORARY_FAILURE | PERMANENT_FAILURE | UNKNOWN_FAILURE | OPT_OUT | DUPLICATE

True

The delivery status of the message. Possible values are:

  • DUPLICATE – The endpoint address is a duplicate of another endpoint address. Amazon Pinpoint won't attempt to send the message again.

  • OPT_OUT – The SendMessages API does not honor the OPT_OUT attribute when sending to endpoints and therefore will not use the OPT_OUT message status.

  • PERMANENT_FAILURE – An error occurred when delivering the message to the endpoint address. Amazon Pinpoint won't attempt to send the message again.

  • SUCCESSFUL – The message was successfully delivered to the endpoint address.

  • TEMPORARY_FAILURE – A temporary error occurred. Amazon Pinpoint won't attempt to send the message again.

  • THROTTLED – Amazon Pinpoint throttled the operation to send the message to the endpoint address.

  • UNKNOWN_FAILURE – An unknown error occurred.

MessageId

string

False

The unique identifier for the message that was sent.

StatusCode

integer

True

The downstream service status code for delivering the message.

StatusMessage

string

False

The status message for delivering the message.

UpdatedToken

string

False

For push notifications that are sent through the GCM channel, specifies whether the endpoint's device registration token was updated as part of delivering the message.

SendOTPMessageRequestParameters

Specifies the details of and parameters for the OTP that you are generating.

PropertyTypeRequiredDescription
AllowedAttempts

integer

False

The number of times the recipient can unsuccessfully attempt to validate the OTP. If the number of attempts exceeds this value, the OTP automatically becomes invalid. The maximum number of allowed attempts is 5. The default value is 3 attempts.

BrandName

string

False

The name of the brand, company, or product that is associated with the OTP code. This name can contain up to 20 characters. Amazon Pinpoint automatically adds the brand name to the OTP message that it sends.

Channel

string

True

The communication channel that the OTP code is sent through. Currently, only SMS messages are supported, so the only acceptable value is SMS.

CodeLength

integer

False

The number of digits that will be in the OTP code that's sent to the recipient. OTP codes can contain between 5 and 8 digits, inclusive. The default value is 6 digits.

DestinationIdentity

string

True

The phone number, in E.164 format, that the OTP code was sent to.

EntityId

string

False

An Entity ID that is registered with a regulatory agency. This is currently only used when sending messages to recipients in India. If you aren't sending to recipients in India, you can omit this parameter.

Language

string

False

The language, in IETF BCP-47 format, to use when sending the message. Acceptable values are:

  • de-DE – German

  • en-GB – English (UK)

  • en-US – English (US)

  • es-419 – Spanish (Latin America)

  • es-ES – Spanish

  • fr-CA – French (Canada)

  • fr-FR – French

  • ja-JP – Japanese

  • ko-KR – Korean

  • pt-BR – Portuguese (Brazil)

  • zh-CN – Chinese (Simplified)

  • zh-TW – Chinese (Traditional)

OriginationIdentity

string

True

The originating identity (such as a long code, short code, or sender ID) that is used to send the OTP code. If you use a long code or toll-free number to send the OTP, the phone number must be in E.164 format.

ReferenceId

string

True

A unique reference ID for the request. The reference ID exactly match the reference ID that you provide when you validate the OTP. The reference ID can contain between 1 and 48 characters, inclusive. For security purposes, you should use a reference ID that is unique to the application that is sending the OTP code.

TemplateId

string

False

A Template ID that is registered with a regulatory agency. This is currently only used when sending messages to recipients in India. If you aren't sending to recipients in India, you can omit this parameter.

ValidityPeriod

integer

False

The amount of time, in minutes, that the OTP code will be valid. The validity period can be between 5 and 60 minutes, inclusive. The default value is 15 minutes.

See also

For more information about using this API in one of the language-specific AWS SDKs and references, see the following:

SendOTPMessage