Package com.tomtom.ivi.platform.messaging.api.service.messaging

The messaging service API package.

Messaging service

The messaging service is an IVI service, used for sending and receiving messages. It supports multiple message types. Each type can be seen as a separate messaging application; think of SMS or other third-party messaging services. Messages are further divided into conversations. A conversation contains a list of unread messages of a particular type, that have been received from a particular list of contacts.

Note: Currently a conversation only supports a single remote contact.

All conversations that contain unread messages can be accessed using the MessagingService.allConversations property. The Conversations in this list will contain meta data as well as a list of unread message IDs. To get the actual message content, call the MessagingService.getMessage function with the desired message ID.

To mark messages as read:

• Call MessagingService.updateMessageState with a MessageState.INCOMING_READ when a single message needs to be marked as read.

• Call MessagingService.markConversationReadUpToAndIncluding when multiple messages in a row need to be marked as read,

Conversations also have a set of capabilities that indicate if it is possible to reply to the conversation using text, or to call the remote contact using a voice connection. If it is possible to reply to a conversation using text, call the MessagingService.replyUsingText function. For some message types, like SMS, it is also possible to initiate a conversation. This can be done by calling MessagingService.getOrCreateConversationId with the message type and a contact.

Overview of the messaging service

The messaging frontend communicates with the MessagingApp service, which in turn communicates with the MessagingService. Through it, the app service and frontend can display notifications for all incoming conversations, and provide functionality to play back messages using Text-To-Speech (TTS). The MessagingService.allConversations property provides all current conversations with unread messages, while the MessagingService.getMessage function provides the content of those messages. The capabilities of the conversations indicate the possibility of calling the remote contact by voice, and if it is possible to send a default reply.

The actual messaging functionality is provided by one or more implementations of the discoverable MessagingProvider service. All messages provided by all those implementations are combined by the MessagingService to provide a single source for all messages.

Using the messaging service API

To use the messaging service, add a dependency to the MessagingService to your Gradle file:

dependencies {
    implementation("com.tomtom.ivi.platform:platform_messaging_api_service_messaging")
}

To get access to the MessagingService API, you need to first get a MessagingServiceApi instance, by calling the companion function MessagingService.createApi(...).

val messagingService = MessagingService.createApi(lifecycleOwner, iviServiceProvider)

Once you have the MessagingServiceApi instance, you can use it to call any API, and observe any properties provided by the service.

Note: The service may not be ready when a client calls the service API and could return a SERVICE_UNAVAILABLE result. It is possible to check the service availability by observing the serviceAvailable property:

messagingService.serviceAvailable.observe(lifecycleOwner) {
    if (it) {
        // Service is available.
    } else {
        // Service is not available.
    }
}

Get available message types

Available message types can be retrieved using the MessagingService.allMessageTypes property. This contains a map of message types associated with a boolean flag. When the message type is in the map, it means that there is a MessagingProvider service available for that message type. If the boolean flag is true it means that messaging is enabled for that message type, otherwise messaging is disabled for that message type.

For example, the platform contains an SMS messaging provider. This means that the SMS message type is always in the map. But if there is no phone connected through which to send messages, the boolean flag for SMS is false. This indicates that currently SMS messaging is not enabled. When a phone is paired that supports the messaging profile, the flag will change to true.

messagingService.allMessageTypes.observe(lifecycleOwner) {
    if (it[MessageType.SMS] == true) {
        // Sms messaging is available.
    } else {
        // Sms messaging is not available.
    }
}

Conversations list

Conversations are provided by the MessagingService.allConversations map. This contains unique conversation IDs associated with the Conversation object for that conversation. The conversation object contains all meta data, as well as a list of IDs of all unread messages for that conversation.

messagingService.allConversations.observe(lifecycleOwner) { conversations ->
    // [conversations] contains a map of all conversations with unread messages.
}

Getting message content

Once you get a message ID from a Conversation.unreadMessages list, you can retrieve its meta data and content text by calling the MessagingService.getMessage with that message ID.

fun getMessageContentTextFor(messageId: Uid<Message>): String? {
    return messagingService.getMessage(messageId)?.contentText
}

Marking message as read

When a message is marked as read, it will be removed from the unread messages list of its conversation. If this was the last unread message in that conversation, that conversation will be removed from the allConversations list.

There are two ways to mark a message as read.

It is possible to mark all messages in a conversation, up to and including a particular message, as read by calling:

  messagingService.markConversationReadUpToAndIncluding(conversationId, messageId)

To only mark a single message as read, do the following:

  messagingService.updateMessageState(messageId, MessageState.INCOMING_READ)

Replying to a conversation

To reply to the first conversation available with text, you can do the following:

  messagingService.allConversation.keys.firstOrNull()?.let { conversationId ->
    messagingService.replyUsingText(conversationId, "The message to send.")
  }

Creating a new conversation to send messages to

It is also possible to initiate a conversation. This is an example of sending an SMS to someone:

fun sendSmsTo(phoneNumber: String, contentText: String) : Boolean {
  return messagingService.getOrCreateConversationId(
    setOf(ConversationContact(null, phoneNumber, null)),
    MessageType.SMS
  )?.let { conversationId ->
    messagingService.replyUsingText(conversationId, contentText)
  } ?: false
}