aace::messaging::Messaging Class Reference

Public Types
using	ErrorCode = MessagingEngineInterface::ErrorCode
using	ConnectionState = MessagingEngineInterface::ConnectionState
using	PermissionState = MessagingEngineInterface::PermissionState

Public Member Functions
virtual void	sendMessage (const std::string &token, const std::string &message, const std::string &recipients)=0
virtual void	uploadConversations (const std::string &token)=0
virtual void	updateMessagesStatus (const std::string &token, const std::string &conversationId, const std::string &status)=0
void	sendMessageSucceeded (const std::string &token)
void	sendMessageFailed (const std::string &token, ErrorCode code, const std::string &message="")
void	conversationsReport (const std::string &token, const std::string &conversations)
void	updateMessagesStatusSucceeded (const std::string &token)
void	updateMessagesStatusFailed (const std::string &token, ErrorCode code, const std::string &message="")
void	updateMessagingEndpointState (ConnectionState connectionState, PermissionState sendPermission, PermissionState readPermission)

Detailed Description

Messaging should be extended to allow a user to use Alexa to interact with a device that provides Short Messaging Service (SMS) capabilities, such as a connected mobile phone.

Note

The device is referred to as the messaging endpoint.

The platform implementation is responsible for uploading unread messages to the cloud when the messaging endpoint is connected, and when new messages are received. Alexa reads messages in the order they are uploaded. Additionally, the platform implementation is responsible for sending messages, updating message status, and providing the messaging endpoint connection state and permissions.

Deprecated:

This platform interface is deprecated. Use the Alexa Auto Services Bridge (AASB) message broker to publish and subscribe to AASB messages instead.

See also

aace::core::MessageBroker

Member Typedef Documentation

ErrorCode

using aace::messaging::Messaging::ErrorCode = MessagingEngineInterface::ErrorCode

Describes the ErrorCode for failed responses.

ConnectionState

using aace::messaging::Messaging::ConnectionState = MessagingEngineInterface::ConnectionState

Describes the ConnectionState of the messaging endpoint.

PermissionState

using aace::messaging::Messaging::PermissionState = MessagingEngineInterface::PermissionState

Describes the PermissionState of the messaging endpoint.

Member Function Documentation

sendMessage()

virtual void aace::messaging::Messaging::sendMessage ( const std::string &  token, const std::string &  message, const std::string &  recipients  )

pure virtual

Notifies the platform implementation to send an SMS message via the messaging endpoint. The message text contains a short lived URL that contains the audio data from which the message was generated.

Parameters

[in]	token	The identifier for the request.
[in]	message	The body of the message, which includes the text and a URL pointing to the audio the audio data from which the message was generated. The text and the URL are separated by a ' ' character.
[in]	recipients	JSON data containing the recipients of the message. { "recipients" : [ { "address" : "{{STRING}}", "addressType" : "PhoneNumberAddress" } ] } recipients (required) : The list of phone numbers to which the user intends to send the message. address (required) : The phone number of the recipient. addressType (required) : Describes the type of value address contains. Currently, only "PhoneNumberAddress" is supported.

uploadConversations()

virtual void aace::messaging::Messaging::uploadConversations ( const std::string &  token )

pure virtual

Notifies the platform implementation to upload all unread messages to the cloud. This method is called if message playback is interrupted or when Alexa has finished reading all messages. This ensures that the cloud and the messaging endpoint stay in sync with the status of unread messages. Upload messages via the conversationsReport API using the token received.

Parameters

[in]

token

The identifier for the request.

updateMessagesStatus()

virtual void aace::messaging::Messaging::updateMessagesStatus ( const std::string &  token, const std::string &  conversationId, const std::string &  status  )

pure virtual

Notifies the platform implementation that a message has been read, and therefore the messaging device must update the message status to reflect that. The platform implementation is responsible for maintaining the list of unread messages. It must send a response to the cloud via updateMessagesStatusSucceeded or updateMessagesStatusFailed depending on the result of the status update.

Parameters

[in]	token	The identifier for the request.
[in]	conversationId	The identifier for the conversation whose status will be updated. This is the value provided by the platform via the conversationsReport API.
[in]	status	Contains the set of message identifiers that need to be updated to the associated status. { "statusMap" : { "read" : [{{STRING}}], } } read The list of message ids that were read in the associated conversationId.

sendMessageSucceeded()

void aace::messaging::Messaging::sendMessageSucceeded

(

const std::string &

token

)

Notifies the cloud that the sendMessage request succeeded.

Parameters

[in]

token

The token received from the sendMessage request.

sendMessageFailed()

void aace::messaging::Messaging::sendMessageFailed	(	const std::string &	token,
		ErrorCode	code,
		const std::string &	message = ""
	)

Notifies the cloud that the sendMessage request failed.

Parameters

[in]	token	The token received from the sendMessage request.
[in]	code	The error code describing the reason for the failure.
[in]	message	Optional error message describing the failure.

conversationsReport()

void aace::messaging::Messaging::conversationsReport	(	const std::string &	token,
		const std::string &	conversations
	)

Updates the cloud with the list of unread messages that Alexa will play back. Call this method when the messaging endpoint is connected and read permission has been granted. Additionally, use this method to reply to a uploadConversations request, passing back the token that was sent in that request.

Note

The conversation report is a JSON Array and therefore must be enclosed in brackets [].

The list of conversations is a JSON array. Each conversation must contain a unique identifier that will be used by the updateMessagesStatus request to identify the conversation whose messages must be updated.

The "otherParticipants" field of the conversation report contains the phone numbers of all participants in the conversation, except for the phone number of the messaging endpoint.

Parameters

[in]	The	token received from uploadConversations, otherwise an empty string.
[in]	conversations	A JSON array representing the unread messages of the messaging endpoint. [ { "id": "{{STRING}}", "otherParticipants": [ { "address":"{{STRING}}", "addressType":"PhoneNumberAddress" } ], "messages": [ { "id":"{{STRING}}", "payload": { "@type":"text", "text":"{{STRING}}" }, "status":"unread", "createdTime":"{{STRING}}", "sender": { "address":"{{STRING}}", "addressType":"PhoneNumberAddress" } } ], "unreadMessageCount": {{INTEGER}} } ] id A unique identifier generated by the application for the conversation. otherParticipants Additional recipients of the message used for group conversation or empty. otherParticipants.address The phone number of the recipient. otherParticipants.addressType Hard coded string "PhoneNumberAddress" indicating the value of the address field. messages.id A unique identifier generated by the application for the message. messages.payload. Hard coded string "text" indicating the value of the text field. messages.text The text for the message. messages.createdTime (optional) The ISO 8601 timestamp of when the message was created on the device. messages.sender.address The phone number of the sender. messages.sender.addressType Hard coded string "PhoneNumberAddress" indicating the value of the address field. unreadMessageCount The total number of unread messages in this conversation.

updateMessagesStatusSucceeded()

void aace::messaging::Messaging::updateMessagesStatusSucceeded

(

const std::string &

token

)

Notifies the cloud that the updateMessagesStatus request succeeded.

Parameters

[in]

token

The token received from the

See also

Messaging::updateMessagesStatus request.

updateMessagesStatusFailed()

void aace::messaging::Messaging::updateMessagesStatusFailed	(	const std::string &	token,
		ErrorCode	code,
		const std::string &	message = ""
	)

Notifies the cloud that the updateMessagesStatus request failed.

Parameters

[in]

token

The token received from the

See also

Messaging::updateMessagesStatus request.

Parameters

[in]	code	The error code describing the reason for the failure.
[in]	message	Optional error message describing the failure.

updateMessagingEndpointState()

void aace::messaging::Messaging::updateMessagingEndpointState	(	ConnectionState	connectionState,
		PermissionState	sendPermission,
		PermissionState	readPermission
	)

Allows the platform implementation to provide the connection state of the messaging endpoint, and whether send and read permissions are granted by the user.

Parameters

[in]	connectionState	CONNECTED If the messaging endpoint is connected, else DISCONNECTED
[in]	sendPermission	ON If the messaging endpoint can send messages, else OFF
[in]	readPermission	ON If the messaging endpoint messages be read, else OFF