Text Messaging

Sending Messages

The Telephony SDK can handle sending of SMS and MMS messages. Sending messages requires a provisioned phone number, discussed in the phone numbers section of the documentation.

Refer to the Telephony Simulator page for details on sending messages from simulated phone numbers.

SMS Messages

SMS messages can be sent using the sendSMSMessage() method. This method takes a local number, which must be a PhoneNumber, an E.164 formatted remote number and a message body.

Swift

let localNumber: PhoneNumber
try! telephonyClient.sendSMSMessage(localNumber: localNumber, 
    remoteNumber: "[phone]" , body: "Hi there") { result in
    switch result {
    case .success(let message):
        // message: PhoneMessage (see details below)
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val phoneNumber: PhoneNumber
// val destinationPhoneNumber = "[phone]"
// val message = "Hi there"
telephonyClient.sendSMSMessage(phoneNumber, 
                               destinationPhoneNumber, 
                               message) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneMessage
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

The result of successfully sending a message is a PhoneMessage as described below.

MMS Messages

MMS messages can be sent using the sendMMSMessage() method. This is very similar to the method used for SMS but with an additional parameter localUrl: URL for the path to the MMS media file to be sent with the message.

Swift

let localNumber: PhoneNumber
let media = URL(string: "path to media")!
try! telephonyClient.sendMMSMessage(localNumber: localNumber, 
                                    remoteNumber: "[phone]", 
                                    body: "Check out my new car!", 
                                    localUrl: media) { result in
    switch result {
    case .success(let message):
        // message: PhoneMessage (see details below)
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val phoneNumber: PhoneNumber
// val destinationPhoneNumber = "[phone]"
// val message = "Hi there"
// val localUrl: URL
telephonyClient.sendMMSMessage(phoneNumber, 
                               destinationPhoneNumber, 
                               message, 
                               localUrl) { result -> 
    when (result) {
        is Result.Success -> {
            // result.value: PhoneMessage (see details below)
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

The result of successfully sending a message is a PhoneMessage, described below.

Phone Message

SMS and MMS messages are represented in the Telephony SDK by a PhoneMessage as described below:

Swift

struct PhoneMessage {

    /// The direction of the message
    enum Direction {
        case inbound
        case outbound
        case unknown
    }

    /// The state of the message
    enum State {
        case queued
        case sent
        case delivered
        case undelivered
        case failed
        case received
        case unknown
    }

    let id: String // Unique ID of message
    let owner: String // Unique ID of message owner
    let conversation: String // Unique ID of the conversation this message is part of
    let updated: Date // Date/time message was last updated
    let created: Date // Date/time message was created
    let localPhoneNumber: String // E.164 formatted local phone number
    let remotePhoneNumber: String // E.164 formatted remote phone number
    let body: String // body of message
    let direction: Direction // Direction of message (see enum above)
    let state: State // State of message (see enum above)
    let media: [MediaObject] // Media attachements for MMS messages
}

Kotlin

enum MessageDirection {
  INBOUND
  OUTBOUND
}

enum MessageState {
  QUEUED
  SENT
  DELIVERED
  UNDELIVERED
  FAILED
  RECEIVED
}

data class PhoneMessage(
    val id: String,
    val owner: String,
    val conversation: String,
    val updated: Instant,
    val created: Instant,
    val local: String,
    val remote: String,
    val body: String,
    val direction: MessageDirection,
    val state: MessageState,
    val media: List<MediaObject> = emptyList()
)

Getting Messages

To retrieve SMS and MMS messages, including both sent and received messages, use the getMessage() and getMessages() methods. Messages can be retrieved using either a message ID or the local and remote phone numbers.

Single Message using ID

To retrieve a single message, use the getMessage() method with the message ID. This returns a PhoneMessage object as described above.

Swift

try! telephonyClient.getMessage(id: "abc123") { (result) in
    switch result {
    case .success(let message):
        // message: PhoneMessage
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val message: PhoneMessage
telephonyClient.getMessage(message.id) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneMessage (see details below)
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

Multiple Messages using a Local and Remote Number

To retrieve multiple messages for a specific local and remote number, use the getMessages() method. A limit can be specified for paging, as well as a paging token.

Swift

let localNumber: PhoneNumber
try! telephonyClient.getMessages(localNumber: localNumber, 
    remoteNumber: "[phone]", limit: 20, nextToken: nil) { (result) in
    switch result {
    case .success(let listToken):
        // listToken: TelephonyListToken<PhoneMessage> (see details below)
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val phoneNumber: PhoneNumber
// val destinationPhoneNumber = "[phone]"
// val limit: Int = 20
// val nextToken: String? = null
telephonyClient.getMessages(phoneNumber,
                           destinationPhoneNumber,
                           limit,
                           nextToken) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: TelephonyListToken<PhoneMessage>
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

The result of the getMessages() call is a TelephonyListToken as described below.

Get Messages Result

When multiple messages are retrieved, for example through the getMessages() method, a list token object is returned which includes a list of results and a paging token that can be used to retrieve the next set of results.

Swift

struct TelephonyListToken<PhoneMessage> {
    let items: [PhoneMessage] // Phone messages
    let nextToken: String? // Reference for next page
}

Kotlin

data class TelephonyListToken<PhoneMessage>(
    val items: List<PhoneMessage>,
    val nextToken: String?
)

Conversations

A conversation is a convenient way to retrieve all messages between a specific local number and a specific remote number, sometimes referred to in outside contexts as a message thread or chat history. There are three methods for fetching conversations using different parameters.

Conversation by ID

To retrieve a conversation by ID, use the getConversation(conversationId: String) method.

Swift

try! telephonyClient.getConversation(conversationId: "1") { (result) in
    switch result {
    case .success(let conversation):
        // conversation: PhoneMessageConverastion
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val id = "abc"
telephonyClient.getConversation(id) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneMessageConversation
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

Conversation by local and remote number

To retrieve a conversation using the local and remote number, use the getConversation(localNumber: PhoneNumber, remoteNumber: String) method.

Swift

let localNumber: PhoneNumber
try! self.getConversation(localNumber: localNumber, remoteNumber: "+1") { (result) in
    switch result {
    case .success(let conversation):
        // conversation: PhoneMessageConverastion
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val localNumber: PhoneNumber
// val remoteNumber = "[phone]"
telephonyClient.getConversation(localNumber, remoteNumber) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneMessageConversation
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

Conversations by local number

To retrieve the list of conversations for a given local number, use the getConversations method. A limit can be specified for paging, as well as a paging token.

Swift

let localNumber: PhoneNumber
try! telephonyClient.getConversations(localNumber: localNumber, 
                                      limit: 20, 
                                      nextToken: nil) { (result) in
    switch result {
    case .success(let listToken):
        // listToken: TelephonyListToken<PhoneMessageConversation>
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val localNumber: PhoneNumber
// val limit = 20
// val nextToken = null
telephonyClient.getConversations(localNumber, limit, nextToken) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: TelephonyListToken<PhoneMessageConversation>
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

The PhoneMessageConversation type contains a latestPhoneMessage property which can be used to retrieve the local and remote phone numbers involved in the conversation, as well as to display a preview of the conversation contents.

Swift

struct PhoneMessageConversation {
    let id: String // Unique id of conversation
    let latestPhoneMessage: PhoneMessage? // Latest sent/received message in conversation
    public let type: MessageConversationType // `MessageConversationType` of the conversation
    public let latestMessageId: String // ID of the latest message in the conversation
    public var latestPhoneMessage: PhoneMessage? // Latest phone message
    public let created: Date // Creation date of the conversation
    public let updated: Date // Date of the last modification to the conversation
}

struct TelephonyListToken<PhoneMessageConversation> {
    let items: [PhoneMessageConversation] // Conversations
    let nextToken: String? // Reference for next page
}

Kotlin

data class PhoneMessageConversation (
    val id: String, // Unique ID of the conversation
    val owner: String, // ID of the owner of the message
    val type: MessageConversationType, // `MessageConversationType` of the conversation
    val latestMessageId: String, // ID of the latest message in the conversation
    var latestPhoneMessage: PhoneMessage?, // Latest phone message
    val created: Date, // Creation date of the conversation
    val updated: Date // Date of the last modification to the conversation
)

data class TelephonyListToken<PhoneMessageConversation>(
    val items: List<PhoneMessageConversation>, // Conversations
    val nextToken: String? // Reference for next page
)

Downloading MMS Message Media

When MMS messages are retrieved, the media data is not automatically downloaded. This gives you control over performance when retrieving MMS messages, particularly those with large media attachments.

To download MMS message media, use the downloadData() method, passing it a MediaObject which can be found in the media property of an MMS message. This method returns the raw media data. Images (jpeg, png, gif) are currently the only supported message media type.

Swift

let message: PhoneMessage
let mediaItem = message.media[0]
try! telephonyClient.downloadData(for: mediaItem) { (result) in
    switch result {
    case .success(let data):
        // Convert data to image for display
        let image = UIImage(data: data)
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val mediaItem: MediaObject
telephonyClient.downloadData(mediaItem) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: ByteArray
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

Deleting Messages

To delete a message, the deleteMessage() method is used and requires the message ID.

Swift

try! telephonyClient.deleteMessage(id: "1234") { result in
    switch result {
    case .success(let id):
        // id: Message ID string
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// val message: PhoneMessage
telephonyClient.deleteMessage(message.id) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: Message ID string
        }
        is Result.Error -> {
            // result.throwable: com.anonyome.telephonysdk.Result.Error
        }
    }
}

Subscribing to Message Events

To subscribe to new messages and message status change events, use the subscribeToMessages method. When new messages or message updates occur, the result handler or subscriber you provide will be called with the latest version of the message. On iOS this method returns a SubscriptionToken that cancels the subscription when it's released. On Android a unique ID is passed in to identify the subscriber and can be passed in to the unsubscribeFromPhoneMessages(id: String?) method on Android.

Swift

let token = try! telephonyClient.subscribeToMessages { (result) in
    switch result {
    case .success(let message):
        // message: PhoneMessage
    case .failure(let error):
        // error: SudoTelephonyClientError, if an error occurred processing subscription data
    }
}

Kotlin

// val subscriber: PhoneMessageSubscriber
// val subscriberId: String
telephonyClient.subscribeToMessages(subscriber, subscriberId)

// PhoneMessageSubscriber definition
interface PhoneMessageSubscriber : TelephonySubscriber {
    /**
     * Notifies the subscriber of a new 'PhoneMessage'.
     * @param phoneMessage new `PhoneMessage`.
     */
    fun phoneMessageReceived(phoneMessage: PhoneMessage)
}