Amazon Pinpoint SMS and Voice
REST API Reference

Voice Message

The Amazon Pinpoint SMS and Voice API lets you create voice messages from a text script, and then deliver those messages to your customers over the phone.

URI

/v1/sms-voice/voice/message

HTTP Methods

POST

Operation ID: SendVoiceMessage

Create a new voice message and send it to a recipient's phone number.

Responses

Status Code Response Model Description
200 SendVoiceMessageResponse

An object that that contains the Message ID of a Voice message that was sent successfully.

400 BadRequestException

The request contained syntax that the API couldn't interpret. Modify the request and try again.

429 TooManyRequestsException

You've issued too many requests to the resource. Wait a few minutes, and then try again.

500 InternalServiceErrorException

The API encountered an unexpected error and couldn't complete the request. You might be able to successfully issue the request again in the future.

OPTIONS

Responses

Status Code Response Model Description
200 None

200 response

Schemas

Request Bodies

Example POST

{ "Content": { "CallInstructionsMessage": { "Text": "string" }, "PlainTextMessage": { "LanguageCode": "string", "Text": "string", "VoiceId": "string" }, "SSMLMessage": { "LanguageCode": "string", "Text": "string", "VoiceId": "string" } }, "OriginationPhoneNumber": "string", "ConfigurationSetName": "string", "DestinationPhoneNumber": "string", "CallerId": "string" }

Response Bodies

Example SendVoiceMessageResponse

{ "MessageId": "string" }

Example BadRequestException

{ "Message": "string" }

Example TooManyRequestsException

{ "Message": "string" }

Example InternalServiceErrorException

{ "Message": "string" }

Properties

BadRequestException

The input that you provided to the API is invalid.

Property Type Required Description
Message

string

False

A description of the error that the API encountered.

CallInstructionsMessageType

An object that defines a message that contains text formatted using Amazon Pinpoint Voice Instructions markup.

Note

The ability to send messages using Amazon Pinpoint Call Instructions is currently a pre-production feature. It isn't currently available to all customers.

Property Type Required Description
Text

string

True

The language to use when delivering the message. For a complete list of supported languages, see the Amazon Polly Developer Guide.

InternalServiceErrorException

This error occurs when an there is an unexpected issue with the Amazon Pinpoint SMS and Voice API service.

Property Type Required Description
Message

string

False

A description of the error that the API encountered.

PlainTextMessageType

An object that defines a message that contains unformatted text.

Property Type Required Description
LanguageCode

string

False

The language to use when delivering the message. For a complete list of supported languages, see the Amazon Polly Developer Guide.

Text

string

True

The plain (not SSML-formatted) text to deliver to the recipient.

VoiceId

string

False

The name of the voice that you want to use to deliver the message. For a complete list of supported voices, see the Amazon Polly Developer Guide.

SSMLMessageType

An object that defines a message that contains SSML-formatted text.

Property Type Required Description
LanguageCode

string

False

The language to use when delivering the message. For a complete list of supported languages, see the Amazon Polly Developer Guide.

Text

string

True

The SSML-formatted text to deliver to the recipient.

VoiceId

string

False

The name of the voice that you want to use to deliver the message. For a complete list of supported voices, see the Amazon Polly Developer Guide.

SendVoiceMessageRequest

A request to create and send a new voice message.

Property Type Required Description
Content

VoiceMessageContent

False

An object that contains a voice message and information about the recipient that you want to send it to.

OriginationPhoneNumber

string

True

The phone number that Amazon Pinpoint should use to send the voice message. This isn't necessarily the phone number that appears on recipients' devices when they receive the message, because you can specify the CallerId property in the request.

Although it isn't required, we recommend that you specify the phone number in E.164 format to ensure prompt and accurate delivery.

ConfigurationSetName

string

False

The name of the configuration set that you want to use to send the message.

DestinationPhoneNumber

string

True

The phone number that you want to send the voice message to.

Although it isn't required, we recommend that you specify the phone number in E.164 format to ensure prompt and accurate delivery. You can use the Phone Number Validate resource in the Amazon Pinpoint API to convert phone numbers to E.164 format.

CallerId

string

False

The phone number that appears on recipients' devices when they receive the message.

Note

You can't specify a CallerId parameter if your account is in the sandbox.

SendVoiceMessageResponse

An object that that contains the Message ID of a Voice message that was sent successfully.

Property Type Required Description
MessageId

string

False

A unique identifier for the voice message.

TooManyRequestsException

This error occurs when an there is an unexpected issue with the Amazon Pinpoint SMS and Voice API service.

Property Type Required Description
Message

string

False

A description of the error that the API encountered.

VoiceMessageContent

An object that contains the voice message that you want to send.

Property Type Required Description
CallInstructionsMessage

CallInstructionsMessageType

False

An object that defines a message formatted using Amazon Pinpoint Call Instructions.

PlainTextMessage

PlainTextMessageType

False

An object that defines a message that contains unformatted text.

SSMLMessage

SSMLMessageType

False

An object that defines a message that contains SSML-formatted text.

See Also

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

SendVoiceMessage