Discussion

The Agora RTM SDK supports creating multiple AgoraRtmKit instances. All methods in the AgoraRtmKit class, except the destroyChannelWithId method, are executed asynchronously.

Discussion

NOTE

• If you log in with the same user ID from a different instance, you will be kicked out of your previous login and removed from previously joined channels.
• The call frequency limit for this method is two queries per second.

• Only after you successfully call this method and receives the AgoraRtmLoginErrorOk error code, can you call the key RTM methods except:

  • createChannelWithId
  • initWithText
  • getRtmCallKit
  • initWithCalleeId

After the app calls this method, the local user receives the connectionStateChanged callback and switches to the AgoraRtmConnectionStateConnecting state.

• Success: The local user receives the AgoraRtmLoginBlock and connectionStateChanged callbacks, and switches to the AgoraRtmConnectionStateConnected state.
• Failure: The local user receives the AgoraRtmLoginBlock and connectionStateChanged callbacks, and switches to the AgoraRtmConnectionStateDisconnected state.

Discussion

• Success: The local user receives the AgoraRtmLogoutBlock and connectionStateChanged callbacks, and switches to the AgoraRtmConnectionStateDisConnected state.
• Failure: The local user receives the AgoraRtmLogoutBlock callback.

Discussion

You are required to renew your Token when receiving the rtmKitTokenDidExpire callback, and the AgoraRtmRenewTokenBlock callback returns the result of this method call. The call frequency limit for this method is two calls per second.

Discussion

DEPRECATED

We do not recommend using this method to send a peer-to-peer message. Use sendMessage instead.

• Success:
  • The local user receives the AgoraRtmSendPeerMessageBlock callback.
  • The specified remote user receives the messageReceived callback.
• Failure: The local user receives the AgoraRtmSendPeerMessageBlock callback with an error. See AgoraRtmSendPeerMessageErrorCode for the error codes.

NOTE

You can send messages, including peer-to-peer and channel messages, at a maximum speed of 180 calls every three seconds.

Discussion

Downloads a file or image from the Agora server to the local memory by media ID.

NOTE

• This method applies to scenarios requiring quick access to the downloaded file or image.
• The SDK releases the downloaded file or image immediately after returning the AgoraRtmDownloadMediaToMemoryBlock callback.

Discussion

Downloads a file or image from the Agora server to a specified local directory by media ID.

Discussion

Gets an AgoraRtmFileMessage instance by uploading a file to the Agora server.

The SDK returns the result with the AgoraRtmUploadFileMediaBlock callback. If success, this callback returns a corresponding AgoraRtmMessage instance, and then you can downcast it to AgoraRtmFileMessage according to its type.

NOTE

• If you have at hand the media ID of a file on the Agora server, you can call createFileMessageByMediaId to create an AgoraRtmFileMessage instance.
• To cancel an ongoing upload task, call cancelMediaUpload.

Discussion

Gets an AgoraRtmImageMessage instance by uploading an image to the Agora server.

The SDK returns the result by the AgoraRtmUploadImageMediaBlock callback. If success, this callback returns a corresponding AgoraRtmMessage instance, and then you can downcast it to AgoraRtmImageMessage according to its type.

• If the uploaded image is in JPEG, JPG, BMP, or PNG format, the SDK calculates the width and height of the image. You can get the calculated width and height from the received AgoraRtmImageMessage instance.
• Otherwise, you need to set the width and height of the uploaded image within the received AgoraRtmImageMessage instance by yourself.

NOTE

• If you have at hand the media ID of an image on the Agora server, you can call createImageMessageByMediaId to create an AgoraRtmImageMessage instance.
• To cancel an ongoing upload task, call cancelMediaUpload.

Discussion

Cancels an ongoing file or image download task by request ID.

NOTE You can only cancel an ongoing download task. After a download task completes, the corresponding request ID is no longer valid and hence you cannot cancel it.

Discussion

Cancels an ongoing file or image upload task by request ID.

NOTE You can only cancel an ongoing upload task. After an upload task completes, you cannot cancel it and the corresponding request ID is no longer valid.

Discussion

Creates an AgoraRtmFileMessage instance by media ID.

• If you have at hand the media ID of a file on the Agora server, you can call this method to create an AgoraRtmFileMessage instance.
• If you do not have a media ID, then you must call createFileMessageByUploading to get a corresponding AgoraRtmFileMessage instance by uploading a file to the Agora RTM server.

Discussion

Creates an AgoraRtmImageMessage instance by media ID.

• If you have at hand the media ID of an image on the Agora server, you can call this method to create an AgoraRtmImageMessage instance.
• If you do not have a media ID, then you must call createFileMessageByUploading to get a corresponding AgoraRtmImageMessage instance by uploading an image to the Agora RTM server.

Discussion

This method allows you to send a message to a specified user when the user is offline. If you set a message as an offline message and the specified user is offline when you send it, the RTM server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one.

If you use this method to send off a text message that starts off with AGORA_RTM_ENDCALL_PREFIX_<channelId>_<your additional information>, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace <channelId> with the channel ID from which you want to leave (end call), and replace <your additional information> with any additional information. Note that you must not put any “_” (underscore) in your additional information but you can set <your additional information> as empty “”.

• Success:
  • The local user receives the AgoraRtmSendPeerMessageBlock callback.
  • The specified remote user receives the messageReceived callback.
• Failure: The local user receives the AgoraRtmSendPeerMessageBlock callback with an error. See AgoraRtmSendPeerMessageErrorCode for the error codes.

NOTE

You can send messages, including peer-to-peer and channel messages, at a maximum speed of 180 calls every three seconds.

Discussion

NOTE

You can create multiple AgoraRtmChannel instances in an AgoraRtmKit instance. But you can only join a maximum of 20 channels at the same time. As a good practice, Agora recommends calling the destroyChannelWithId method to release all resources of an RTM channel that you no longer use.

Discussion

NOTE

Do not call this method in any of your callbacks.

Discussion

• Online: The user has logged in the Agora RTM system.
• Offline: The user has logged out of the Agora RTM system.

Discussion

For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys and clearLocalUserAttributes taken together: the limit is 10 queries every five seconds.

Discussion

For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys and clearLocalUserAttributes taken together: the limit is 10 queries every five seconds.

This method updates the local user’s attributes if it finds that the attributes has/have the same keys, or adds attributes to the local user if it does not.

Discussion

For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys and clearLocalUserAttributes taken together: the limit is 10 queries every five seconds.

Discussion

For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys and clearLocalUserAttributes taken together: the limit is 10 queries every five seconds.

Discussion

For getUserAttributes and getUserAttributesByKeys taken together, the call frequency limit is 40 queries every five seconds.

Discussion

For getUserAttributes and getUserAttributesByKeys taken together, the call frequency limit is 40 queries every five seconds.

Discussion

NOTE

• The call frequency limit for this method is one query per second.
• We do not support getting the member counts of more than 32 channels in one method call.
• You do not have to join the specified channels to call this method.

Discussion

• You do not have to join the specified channel to reset its attributes.
• The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
• If more than one user can update the channel attributes, then Agora recommends calling getChannelAttributes to update the cache before calling this method.
• For setChannelAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys and clearChannelAttributes taken together: the limit is 10 queries every five seconds.

Discussion

This method updates the specified channel’s attributes if it finds that the attributes has/have the same keys, or adds attributes to the channel if it does not.

• You do not have to join the specified channel to update its attributes.
• The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
• If more than one user can update the channel attributes, then Agora recommends calling getChannelAttributes to update the cache before calling this method.
• For setChannelAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys and clearChannelAttributes taken together: the limit is 10 queries every five seconds.

Discussion

• You do not have to join the specified channel to delete its attributes.
• The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
• If more than one user can update the channel attributes, then Agora recommends calling getChannelAttributes to update the cache before calling this method.
• For setChannelAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys and clearChannelAttributes taken together: the limit is 10 queries every five seconds.

Discussion

• You do not have to join the specified channel to clear its attributes.
• The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
• For getChannelAttributes and getChannelAttributesByKeys taken together, the call frequency limit is 10 queries every five seconds.

Discussion

• You do not have to join the specified channel to get its attributes.
• For getChannelAttributes and getChannelAttributesByKeys taken together, the call frequency limit is 10 queries every five seconds.

Discussion

• You do not have to join the specified channel to get its attributes.
• For getChannelAttributes and getChannelAttributesByKeys taken together, the call frequency limit is 10 queries every five seconds.

Discussion

• When the method call succeeds, the SDK returns the PeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe.
• When the online status of the peers, to whom you subscribe, changes, the SDK returns the PeersOnlineStatusChanged callback to report whose online status has changed.
• If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the PeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server.

NOTE

• When you log out of the Agora RTM system, all the status that you subscribe to will be cleared. To keep the original subscription after you re-log in the system, you need to redo the whole subscription process.
• When the SDK reconnects to the server from the state of being interupted, the SDK automatically subscribes to the peers and states before the interruption without human intervention.

Discussion

NOTE

The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way. Contact support@agora.io for more information.

Discussion

NOTE

• Ensure that the directory holding the log file exists and is writable.
• Ensure that you call this method immediately after calling the initWithAppId method, otherwise the output log may be incomplete.
• The default log file location is as follows:
  • iOS: App Sandbox/Library/caches/agorartm.log
  • macOS
  • Sandbox enabled: App Sandbox/Library/Logs/agorartm.log, for example /Users/<username>/Library/Containers/<App Bundle Identifier>/Data/Library/Logs/agorartm.log.
  • Sandbox disabled: ~/Library/Logs/agorartm.log.

Discussion

You can use one or a combination of the filters. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Discussion