A class that provides an interface for performing RCS operations.
Use the ``TelephonyMessagingSession`` property ``TelephonyMessagingSession/rcsService`` to get an instance of this class.
An `RCSService` sends and receives different kinds of messages, distinguished by the ``RCSMessage/content`` property of ``RCSMessage``:
- term ``RCSMessage/Text``: Plain text.
- term ``RCSMessage/FileTransfer``: Incoming or outgoing file transfer. To send a file to a receipient, call the ``upload(_:)``: method, then send a message of this type. To receive a file, handle the incoming message from the ``incomingMessageNotifications`` asynchronous sequence, and use its metadata to call ``download(_:)``.
- term ``RCSMessage/GeolocationPush``: The sender's location, as indicated by a latitude and longitude pair.
- term ``RCSMessage/ComposingIndicator``: An indicator that the sender is currently composing a message. Use this content type to provide "is typing" indicators to recipients.
- term ``RCSMessage/DispositionNotification``: An update regarding the processing of a message by the recipient app. This includes things like whether delivery suceeded or failed, and whether the app displayed the message to the recipient.
Use the various overloads of `sendMessage(_:to:using:messageID)` to send messages of these types to recipients.
The following example shows how to send a plain text message with ``RCSService/sendMessage(_:to:using:messageID:)-(RCSMessage.Text,_,_,_)``:
```swift
let service = TelephonyMessagingSession.shared.rcsService
let cellularServices = try TelephonyMessagingSession.shared.cellularServices
let cellularServiceID = cellularServices[0].id
guard service.isViable(for: cellularServiceID) else { return }
let message = RCSMessage.Text("Hello there.")
guard let handle = RCSHandle.phoneNumber(SAMPLE_PHONE_NUMBER) else { return }
try await service.sendMessage(message,
to: handle,
using:cellularServiceID,
messageID: RCSMessageID(rawValue: SAMPLE_RCS_MESSAGE_ID))
```
To receive messages, iterate over the ``incomingMessageNotifications`` asynchronous sequence with a `for`-`await`-`in` loop, then handle each notification based on its message content type, like this:
```swift
let service = TelephonyMessagingSession.shared.rcsService
let incomingMessageNotifications = try service.incomingMessageNotifications
Task {
for await notification in incomingMessageNotifications {
let receivedMessage = notification.message
switch receivedMessage.content {
case .text(let text): // ...
case .fileTransfer(let fileTransfer): // ...
case .geolocationPush(let geolocationPush): // ...
case .dispositionNotification(let dispositionNotification): // ...
case .composingIndicator(let composingIndicator): // ...
}
}
}
```
final func reportSpam(_ request: RCSService.ReportSpamRequest) async throws
Reports an RCS message as spam to the carrier and to partners.
- Parameters:
- request: A request that provides details about the spam message.
- Throws:
If the session is no longer valid, this method throws ``TelephonyMessagingSession/Error/invalidSession``. If the carrier doesn't support spam reporting, the method throws ``RCSService/Error/notSupported``.
final func sendMessage(_ content: RCSMessage.DispositionNotification, to destination: RCSHandle.URI, using cellularServiceID: CellularServiceID, messageID: RCSMessageID, group: RCSHandle.Group? = nil) async throws
Sends the disposition for an incoming message.
Your app can send this message so recipients can see if your app received and displayed a given message.
- Parameters:
- content: The content of the message to send.
- destination: Destination handle to send the message disposition to.
- cellularServiceID: Service identifier to use for this request.
- messageID: Message ID to use for this message.
- group: Optional group handle to use when the incoming message is part of a group conversation.
final func sendMessage(_ content: RCSMessage.FileTransfer, to destination: RCSHandle, using cellularServiceID: CellularServiceID, messageID: RCSMessageID) async throws
Sends a file transfer message to a specified destination.
Use this version of the `sendMessage` method in combination with the ``upload(_:)`` and ``download(_:)`` methods of `RCSService`.
To send a file to a recipient, call the upload method and use the returned metadata to create a new ``RCSMessage`` with content that's an instance of ``RCSMessage/FileTransfer``.
To receive a file, start by iterating over items in the ``incomingMessageNotifications`` asynchronous sequence.
When you get a message with a content value that's ``RCSMessage/Content/fileTransfer(_:)``, use the file URL and other metadata in the associated ``RCSMessage/FileTransfer`` value to call the download method.
- Parameters:
- content: The content of the message to send, as an instance of ``RCSMessage/FileTransfer``.
- destination: The destination handle to send the message to.
- cellularServiceID: The service identifier to use for the message.
- messageID: The message identifier to use for the message.
final func sendMessage(_ content: RCSMessage.CustomReaction, to destination: RCSHandle, using cellularServiceID: CellularServiceID, messageID: RCSMessageID) async throws
Sends a custom reaction message to a specified destination.
- Parameters:
- content: The content of the message to send, as an instance of ``RCSMessage/CustomReaction``.
- destination: The destination handle to send the message to.
- cellularServiceID: The service identifier to use for the message.
- messageID: The message identifier to use for the message.
final func sendMessage(_ content: RCSMessage.GeolocationPush, to destination: RCSHandle, using cellularServiceID: CellularServiceID, messageID: RCSMessageID) async throws
Sends a geolocation push message to a specified destination.
- Parameters:
- content: The content of the message to send, as an instance of ``RCSMessage/GeolocationPush``.
- destination: The destination handle to send the message to.
- cellularServiceID: The service identifier to use for the message.
- messageID: The message identifier to use for the message.
final func sendMessage(_ content: RCSMessage.ComposingIndicator, to destination: RCSHandle, using cellularServiceID: CellularServiceID, messageID: RCSMessageID) async throws
Sends a composing indicator message to a specified destination.
Your app can send this message to allow recipients to see an “is typing” indicator.
- Parameters:
- content: The content of the message to send, as an instance of ``RCSMessage/ComposingIndicator``.
- destination: The destination handle to send the message to.
- cellularServiceID: The service identifier to use for the message.
- messageID: The message identifier to use for the message.
final func sendMessage(_ content: RCSMessage.Text, to destination: RCSHandle, using cellularServiceID: CellularServiceID, messageID: RCSMessageID) async throws
Sends a text message to a specified destination.
- Parameters:
- content: The content of the message to send, as an instance of ``RCSMessage/Text``.
- destination: The destination handle to send the message to.
- cellularServiceID: The service identifier to use for the message.
- messageID: The message identifier to use for the message.
- Throws:
If RCS messaging isn't supported, this method throws ``RCSService/Error/notSupported``. If the message exceeds the maximum size, it throws ``RCSService/Error/maximumSizeExceeded``.
final func sendMessage(_ content: RCSMessage.Reply, to destination: RCSHandle, using cellularServiceID: CellularServiceID, messageID: RCSMessageID) async throws
Sends a reply message to a specified destination.
- Parameters:
- content: The content of the message to send, as an instance of ``RCSMessage/Reply``.
- destination: The destination handle to send the message to.
- cellularServiceID: The service identifier to use for the message.
- messageID: The message identifier to use for the message.
final func sendMessage(_ content: RCSMessage.Reaction, to destination: RCSHandle, using cellularServiceID: CellularServiceID, messageID: RCSMessageID) async throws
Sends a reaction message to a specified destination.
- Parameters:
- content: The content of the message to send, as an instance of ``RCSMessage/Reaction``.
- destination: The destination handle to send the message to.
- cellularServiceID: The service identifier to use for the message.
- messageID: The message identifier to use for the message.
- Throws:
If the reaction content is not a valid emoji sequence, this method throws ``RCSService/Error/invalidArgument``.
final func configuration(for cellularServiceID: CellularServiceID) throws -> RCSService.Configuration
Retrieves the RCS configuration for the specified cellular service.
You can observe changes in configuration through the ``viabilityNotifications`` asynchronous sequence.
When the service becomes viable, invoke this method to retrieve updates to the RCS configuration.
final func revokeMessage(_ request: RCSService.RevokeMessageRequest) async throws -> Bool
Requests revocation of an RCS message.
The RCS specification requires that you revoke a message when delivery fails or times out, and fall back to sending the message with SMS or MMS.
- Parameters:
- request: The request that contains the message to be revoked.
- Returns: A Boolean value that indicates whether sending the request to the carrier network succeeded.
- Throws:
If the session is no longer valid, this method throws ``TelephonyMessagingSession/Error/invalidSession``. If the method can't resolve the handle in the request, it throws ``RCSService/Error/invalidArgument``. If the method can't process the revoke request for other reasons it throws ``RCSService/Error/internalError``.
final func leaveGroupChat(_ request: RCSService.LeaveGroupChatRequest) async throws
Leave a group chat.
- Parameters:
- request: Request specifying the group to leave.
- Throws: ``RCSService/Error`` if there was an error while performing the operation.
final func createGroupChat(_ request: RCSService.CreateGroupChatRequest) async throws -> RCSService.CreateGroupChatRequest.Result
Creates a group with a list of participants and a specified subject.
- Parameters:
- request: Request specifying the group to create.
- Returns: A ``CreateGroupChatRequest/Result`` that contains the group handle for the group.
- Throws: If the messaging service doesn't support group chat, this method throws ``RCSService/Error/notSupported``. If the group chat size exceeds the maximum allowed size, this method throws ``RCSService/Error/maximumSizeExceeded``.
get · iOS 26.0+
groupChatEvents
TypeScript
get groupChatEvents(): SDKHandle
Swift declaration
final var groupChatEvents: some AsyncSequence<RCSService.GroupChatEvent, Never> { get throws }
Returns an asynchronous sequence of incoming group chat notifications produced by this service.
final func remoteCapabilities(for request: RCSService.RemoteCapabilitiesRequest) async throws -> RCSService.RemoteCapabilities?
Requests remote capability discovery for a given handle
- Parameters:
- request: `RemoteCapabilitiesRequest` containing the request parameters.
- Returns: Remote capabilities for requested handle, if available.
final func businessInformation(for request: RCSService.BusinessInformationRequest) async throws -> RCSService.Business?
Requests business information for a specified handle.
- Parameters:
- request: `BusinessInformationRequest` containing the request parameters.
- Returns: The actual render information structure or error.
get · iOS 26.0+
remoteHandleUpdates
TypeScript
get remoteHandleUpdates(): SDKHandle
Swift declaration
final var remoteHandleUpdates: some AsyncSequence<RCSService.RemoteHandleUpdate, Never> { get throws }
An asynchronous sequence of remote handle updates produced by this service.
Use a `for`-`await`-`in` loop to receive ``RemoteHandleUpdate`` instances from this property.
final func sendDeviceSpecifics(to destination: RCSHandle.URI, using cellularServiceID: CellularServiceID, messageID: RCSMessageID) async throws
Sends device specifics in response to a suggested action to send device specifics.
Call this method after the person using the app selects a ``RCSService/Business/Suggestion`` of type ``RCSService/Business/Suggestion/action(_:)``,
whose action type is ``RCSService/Business/SuggestedAction/Action/sendDeviceSpecifics`` .
- Parameters:
- destination: The destination handle to send device specifics to.
- cellularServiceID: The service identifier to use for the message.
- messageID: The message identifier to use for the message.
- Throws:
If the session is no longer valid, this method throws ``TelephonyMessagingSession/Error/invalidSession``. If the method can't process the request for other reasons it throws ``RCSService/Error/internalError``.
final func changeGroupChatSubject(_ request: RCSService.ChangeGroupChatSubjectRequest) async throws
Changes subject of a group.
- Parameters:
- request: Request specifying the group and subject to update.
- Throws: ``RCSService/Error`` if there was an error while performing the operation.
final func sendSuggestionResponse(_ response: RCSService.SuggestionResponse) async throws
Sends a response for a business suggestion.
- Parameters:
- response: `SuggestionResponse` containing the response parameters.
get · iOS 26.0+
viabilityNotifications
TypeScript
get viabilityNotifications(): SDKHandle
Swift declaration
final var viabilityNotifications: some AsyncSequence<RCSService.ViabilityNotification, Never> { get throws }
An asynchronous sequence of service viability notifications produced by the service.
Use a `for`-`await`-`in` loop to receive ``ViabilityNotification`` instances from this property.
final func addGroupChatParticipants(_ request: RCSService.AddGroupChatParticipantsRequest) async throws -> RCSService.AddGroupChatParticipantsRequest.Result
Adds participants to a group chat.
- Parameters:
- request: Request specifying the group and participants to add.
- Throws: ``RCSService/Error`` if there was an error while performing the operation.
final func removeGroupChatParticipants(_ request: RCSService.RemoveGroupChatParticipantsRequest) async throws -> RCSService.RemoveGroupChatParticipantsRequest.Result
Removes participants from a group chat.
- Parameters:
- request: Request specifying the group and participants to remove.
- Throws: `RCSService.Error` if there was an error while performing the operation.
final func sendEncryptedMessageRequest(_ request: RCSService.SendEncryptedMessageRequest) async throws -> RCSService.SendEncryptedMessageRequest.Result
Sends an encrypted message to a specified destination.
Your app may persist the returned ``RCSMessage/SecureSendReceipt`` instance to retry sending the message in the event that the recipient device fails to decrypt the original message.
To retry a request, set the ``RCSService/SendEncryptedMessageRequest/secureSendReceipt`` property of the request, after receiving an ``RCSMessage/DispositionNotification`` message
whose disposition is ``RCSMessage/Disposition/deliveryFailedDueToDecryptionFailure``.
get · iOS 26.0+
incomingMessageNotifications
TypeScript
get incomingMessageNotifications(): SDKHandle
Swift declaration
final var incomingMessageNotifications: some AsyncSequence<RCSService.IncomingMessageNotification, Never> { get throws }
An asynchronous sequence of incoming message notifications produced by this service.
Iterate over this sequence with a `for`-`await`-`in` loop to receive ``IncomingMessageNotification`` instances that indicate the arrival of incoming messages, like this:
```swift
let service = TelephonyMessagingSession.shared.rcsService
let incomingMessageNotifications = try service.incomingMessageNotifications
Task {
for await notification in incomingMessageNotifications {
let receivedMessage = notification.message
switch receivedMessage.content {
case .text(let text): // ...
case .fileTransfer(let fileTransfer): // ...
case .geolocationPush(let geolocationPush): // ...
case .dispositionNotification(let dispositionNotification): // ...
case .composingIndicator(let composingIndicator): // ...
}
}
```
For each message type, the matched `case` contains an instance of the relevant ``RCSMessage/Content`` type as its associated value.
In this example, `text` would contain string content in its ``RCSMessage/Text/body`` property, and `geolocationPush` would have geolocation values in its ``RCSMessage/GeolocationPush/latitude`` and ``RCSMessage/GeolocationPush/longitude`` properties.
final func upload(_ uploadRequest: RCSService.FileUploadRequest) async throws -> RCSService.FileUploadRequest.Metadata
Uploads a file to the RCS content server.
Sending a file to a recipient over RCS is a two-step process:
1. Call `upload(_:)` to upload the file to the carrier.
2. Send a message of type ``RCSMessage/FileTransfer`` to the recipient, using metadata returned from the upload step.
The following example shows this process:
```swift
let service = TelephonyMessagingSession.shared.rcsService
let cellularServices = try TelephonyMessagingSession.shared.cellularServices
let cellularServiceID = cellularServices[0].id
guard service.isViable(for: cellularServiceID) else { return }
guard let uploadURL = URL(string: SAMPLE_UPLOAD_FILE_PATH) else { return }
// Upload file.
let request = RCSService.FileUploadRequest(cellularServiceID: cellularServiceID,
fileURL: uploadURL,
contentType: UTType.plainText)
let uploadMetadata = try await service.upload(request)
// Send file transfer message to recipient handle, using upload metadata.
try await service.sendMessage(RCSMessage.FileTransfer(fileMetadata: uploadMetadata.fileMetadata),
to: RCSHandle.phoneNumber(SAMPLE_PHONE_NUMBER)!,
using: cellularServiceID,
messageID: RCSMessageID(rawValue: SAMPLE_RCS_MESSAGE_ID))
```
- Parameter uploadRequest: A ``FileUploadRequest`` instance that describes the file to upload and an optional thumbnail.
- Returns: A ``FileUploadRequest/Metadata`` instance that contains information about the uploaded file.
- Throws:
If RCS file transfer isn't supported, this method throws ``RCSService/Error/notSupported``. If the file exceeds the maximum size, it throws ``RCSService/Error/maximumSizeExceeded``.
final func download(_ downloadRequest: RCSService.FileDownloadRequest) async throws -> RCSService.FileDownloadRequest.Metadata
Downloads a file from the RCS content server.
Call this method after receiving an ``RCSMessage`` whose content type is ``RCSMessage/Content/fileTransfer(_:)`` from the RCS service's ``RCSService/incomingMessageNotifications`` asynchronous sequence.
Use the message's ``RCSMessage/FileTransfer/fileMetadata`` and optional ``RCSMessage/FileTransfer/thumbnailMetadata``, both of type ``RCSFileTransferMetadata``, to get the URLs to download.
The metadata structure also contains other properties which may be useful for downloading, such as the file size and type.
The following example assumes you received a ``RCSMessage/FileTransfer`` instance called `fileTransferMessage` from the incoming message notifications sequence.
It uses the message's metadata to get a URL with which to call `download(_:)`, and then uses metadata from the download to get a ``RCSService/FileDownloadRequest/Metadata/suggestedFileName`` to help place the file in a permanent location.
```swift
let service = TelephonyMessagingSession.shared.rcsService
let cellularServices = try TelephonyMessagingSession.shared.cellularServices
let cellularServiceID = cellularServices[0].id
guard service.isViable(for: cellularServiceID) else { return }
let downloadURL = fileTransferMessage.fileMetadata.url
let temporaryURL = URL.temporaryDirectory
.appendingPathComponent(downloadURL.lastPathComponent)
// Download file.
let request = RCSService.FileDownloadRequest(cellularServiceID: cellularServiceID,
fileURL: downloadURL,
destinationFileURL: temporaryURL)
let downloadMetadata = try await service.download(request)
// Move file to permanent location, using suggested file name.
let receivedURL = URL.documentsDirectory
.appendingPathComponent(downloadMetadata.suggestedFileName ?? "Unknown")
try FileManager.default.moveItem(at: temporaryURL,
to: receivedURL)
```
- Parameter downloadRequest: A ``FileDownloadRequest`` that indicates the URL to download and its destination path on the local filesystem.
- Returns: A ``FileDownloadRequest/Metadata`` instance that contains information about the downloaded file.
final func isViable(for cellularServiceID: CellularServiceID) -> Bool
Queries whether the device can perform RCS operations at this time.
- Parameters:
- cellularServiceID: The cellular service identifier for which to check RCS viability.
- Returns: `true` if RCS is currently viable for the cellular service; `false`, otherwise.
