Search…
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
Kotlin
1
let localNumber: PhoneNumber
2
try! telephonyClient.sendSMSMessage(localNumber: localNumber,
3
remoteNumber: "+442071838750" , body: "Hi there") { result in
4
switch result {
5
case .success(let message):
6
// message: PhoneMessage (see details below)
7
case .failure(let error):
8
// error: SudoTelephonyClientError
9
}
10
}
Copied!
1
// val phoneNumber: PhoneNumber
2
// val destinationPhoneNumber = "+442071838750"
3
// val message = "Hi there"
4
telephonyClient.sendSMSMessage(phoneNumber,
5
destinationPhoneNumber,
6
message) { result ->
7
when (result) {
8
is Result.Success -> {
9
// result.value: PhoneMessage
10
}
11
is Result.Error -> {
12
// result.throwable: com.anonyome.telephonysdk.Result.Error
13
}
14
}
15
}
Copied!
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
Kotlin
1
let localNumber: PhoneNumber
2
let media = URL(string: "path to media")!
3
try! telephonyClient.sendMMSMessage(localNumber: localNumber,
4
remoteNumber: "+442071838750",
5
body: "Check out my new car!",
6
localUrl: media) { result in
7
switch result {
8
case .success(let message):
9
// message: PhoneMessage (see details below)
10
case .failure(let error):
11
// error: SudoTelephonyClientError
12
}
13
}
Copied!
1
// val phoneNumber: PhoneNumber
2
// val destinationPhoneNumber = "+442071838750"
3
// val message = "Hi there"
4
// val localUrl: URL
5
telephonyClient.sendMMSMessage(phoneNumber,
6
destinationPhoneNumber,
7
message,
8
localUrl) { result ->
9
when (result) {
10
is Result.Success -> {
11
// result.value: PhoneMessage (see details below)
12
}
13
is Result.Error -> {
14
// result.throwable: com.anonyome.telephonysdk.Result.Error
15
}
16
}
17
}
Copied!
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
Kotlin
1
struct PhoneMessage {
2
3
/// The direction of the message
4
enum Direction {
5
case inbound
6
case outbound
7
case unknown
8
}
9
10
/// The state of the message
11
enum State {
12
case queued
13
case sent
14
case delivered
15
case undelivered
16
case failed
17
case received
18
case unknown
19
}
20
21
let id: String // Unique ID of message
22
let owner: String // Unique ID of message owner
23
let conversation: String // Unique ID of the conversation this message is part of
24
let updated: Date // Date/time message was last updated
25
let created: Date // Date/time message was created
26
let localPhoneNumber: String // E.164 formatted local phone number
27
let remotePhoneNumber: String // E.164 formatted remote phone number
28
let body: String // body of message
29
let direction: Direction // Direction of message (see enum above)
30
let state: State // State of message (see enum above)
31
let media: [MediaObject] // Media attachements for MMS messages
32
}
Copied!
1
enum MessageDirection {
2
INBOUND
3
OUTBOUND
4
}
5
6
enum MessageState {
7
QUEUED
8
SENT
9
DELIVERED
10
UNDELIVERED
11
FAILED
12
RECEIVED
13
}
14
15
data class PhoneMessage(
16
val id: String,
17
val owner: String,
18
val conversation: String,
19
val updated: Instant,
20
val created: Instant,
21
val local: String,
22
val remote: String,
23
val body: String,
24
val direction: MessageDirection,
25
val state: MessageState,
26
val media: List<MediaObject> = emptyList()
27
)
Copied!

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
Kotlin
1
try! telephonyClient.getMessage(id: "abc123") { (result) in
2
switch result {
3
case .success(let message):
4
// message: PhoneMessage
5
case .failure(let error):
6
// error: SudoTelephonyClientError
7
}
8
}
Copied!
1
// val message: PhoneMessage
2
telephonyClient.getMessage(message.id) { result ->
3
when (result) {
4
is Result.Success -> {
5
// result.value: PhoneMessage (see details below)
6
}
7
is Result.Error -> {
8
// result.throwable: com.anonyome.telephonysdk.Result.Error
9
}
10
}
11
}
Copied!

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
Kotlin
1
let localNumber: PhoneNumber
2
try! telephonyClient.getMessages(localNumber: localNumber,
3
remoteNumber: "+442071838750", limit: 20, nextToken: nil) { (result) in
4
switch result {
5
case .success(let listToken):
6
// listToken: TelephonyListToken<PhoneMessage> (see details below)
7
case .failure(let error):
8
// error: SudoTelephonyClientError
9
}
10
}
Copied!
1
// val phoneNumber: PhoneNumber
2
// val destinationPhoneNumber = "+442071838750"
3
// val limit: Int = 20
4
// val nextToken: String? = null
5
telephonyClient.getMessages(phoneNumber,
6
destinationPhoneNumber,
7
limit,
8
nextToken) { result ->
9
when (result) {
10
is Result.Success -> {
11
// result.value: TelephonyListToken<PhoneMessage>
12
}
13
is Result.Error -> {
14
// result.throwable: com.anonyome.telephonysdk.Result.Error
15
}
16
}
17
}
Copied!
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
Kotlin
1
struct TelephonyListToken<PhoneMessage> {
2
let items: [PhoneMessage] // Phone messages
3
let nextToken: String? // Reference for next page
4
}
Copied!
1
data class TelephonyListToken<PhoneMessage>(
2
val items: List<PhoneMessage>,
3
val nextToken: String?
4
)
Copied!

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
Kotlin
1
try! telephonyClient.getConversation(conversationId: "1") { (result) in
2
switch result {
3
case .success(let conversation):
4
// conversation: PhoneMessageConverastion
5
case .failure(let error):
6
// error: SudoTelephonyClientError
7
}
8
}
Copied!
1
// val id = "abc"
2
telephonyClient.getConversation(id) { result ->
3
when (result) {
4
is Result.Success -> {
5
// result.value: PhoneMessageConversation
6
}
7
is Result.Error -> {
8
// result.throwable: com.anonyome.telephonysdk.Result.Error
9
}
10
}
11
}
Copied!
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
Kotlin
1
let localNumber: PhoneNumber
2
try! self.getConversation(localNumber: localNumber, remoteNumber: "+1") { (result) in
3
switch result {
4
case .success(let conversation):
5
// conversation: PhoneMessageConverastion
6
case .failure(let error):
7
// error: SudoTelephonyClientError
8
}
9
}
Copied!
1
// val localNumber: PhoneNumber
2
// val remoteNumber = "+442071838750"
3
telephonyClient.getConversation(localNumber, remoteNumber) { result ->
4
when (result) {
5
is Result.Success -> {
6
// result.value: PhoneMessageConversation
7
}
8
is Result.Error -> {
9
// result.throwable: com.anonyome.telephonysdk.Result.Error
10
}
11
}
12
}
Copied!

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
Kotlin
1
let localNumber: PhoneNumber
2
try! telephonyClient.getConversations(localNumber: localNumber,
3
limit: 20,
4
nextToken: nil) { (result) in
5
switch result {
6
case .success(let listToken):
7
// listToken: TelephonyListToken<PhoneMessageConversation>
8
case .failure(let error):
9
// error: SudoTelephonyClientError
10
}
11
}
Copied!
1
// val localNumber: PhoneNumber
2
// val limit = 20
3
// val nextToken = null
4
telephonyClient.getConversations(localNumber, limit, nextToken) { result ->
5
when (result) {
6
is Result.Success -> {
7
// result.value: TelephonyListToken<PhoneMessageConversation>
8
}
9
is Result.Error -> {
10
// result.throwable: com.anonyome.telephonysdk.Result.Error
11
}
12
}
13
}
Copied!
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
Kotlin
1
struct PhoneMessageConversation {
2
let id: String // Unique id of conversation
3
let latestPhoneMessage: PhoneMessage? // Latest sent/received message in conversation
4
public let type: MessageConversationType // `MessageConversationType` of the conversation
5
public let latestMessageId: String // ID of the latest message in the conversation
6
public var latestPhoneMessage: PhoneMessage? // Latest phone message
7
public let created: Date // Creation date of the conversation
8
public let updated: Date // Date of the last modification to the conversation
9
}
10
11
struct TelephonyListToken<PhoneMessageConversation> {
12
let items: [PhoneMessageConversation] // Conversations
13
let nextToken: String? // Reference for next page
14
}
Copied!
1
data class PhoneMessageConversation (
2
val id: String, // Unique ID of the conversation
3
val owner: String, // ID of the owner of the message
4
val type: MessageConversationType, // `MessageConversationType` of the conversation
5
val latestMessageId: String, // ID of the latest message in the conversation
6
var latestPhoneMessage: PhoneMessage?, // Latest phone message
7
val created: Date, // Creation date of the conversation
8
val updated: Date // Date of the last modification to the conversation
9
)
10
11
data class TelephonyListToken<PhoneMessageConversation>(
12
val items: List<PhoneMessageConversation>, // Conversations
13
val nextToken: String? // Reference for next page
14
)
Copied!

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
Kotlin
1
let message: PhoneMessage
2
let mediaItem = message.media[0]
3
try! telephonyClient.downloadData(for: mediaItem) { (result) in
4
switch result {
5
case .success(let data):
6
// Convert data to image for display
7
let image = UIImage(data: data)
8
case .failure(let error):
9
// error: SudoTelephonyClientError
10
}
11
}
Copied!
1
// val mediaItem: MediaObject
2
telephonyClient.downloadData(mediaItem) { result ->
3
when (result) {
4
is Result.Success -> {
5
// result.value: ByteArray
6
}
7
is Result.Error -> {
8
// result.throwable: com.anonyome.telephonysdk.Result.Error
9
}
10
}
11
}
Copied!

Deleting Messages

To delete a message, the deleteMessage() method is used and requires the message ID.
Swift
Kotlin
1
try! telephonyClient.deleteMessage(id: "1234") { result in
2
switch result {
3
case .success(let id):
4
// id: Message ID string
5
case .failure(let error):
6
// error: SudoTelephonyClientError
7
}
8
}
Copied!
1
// val message: PhoneMessage
2
telephonyClient.deleteMessage(message.id) { result ->
3
when (result) {
4
is Result.Success -> {
5
// result.value: Message ID string
6
}
7
is Result.Error -> {
8
// result.throwable: com.anonyome.telephonysdk.Result.Error
9
}
10
}
11
}
Copied!

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
Kotlin
1
let token = try! telephonyClient.subscribeToMessages { (result) in
2
switch result {
3
case .success(let message):
4
// message: PhoneMessage
5
case .failure(let error):
6
// error: SudoTelephonyClientError, if an error occurred processing subscription data
7
}
8
}
Copied!
1
// val subscriber: PhoneMessageSubscriber
2
// val subscriberId: String
3
telephonyClient.subscribeToMessages(subscriber, subscriberId)
4
5
// PhoneMessageSubscriber definition
6
interface PhoneMessageSubscriber : TelephonySubscriber {
7
/**
8
* Notifies the subscriber of a new 'PhoneMessage'.
9
* @param phoneMessage new `PhoneMessage`.
10
*/
11
fun phoneMessageReceived(phoneMessage: PhoneMessage)
12
}
Copied!
Last modified 1yr ago