Agora RTM Objective-C API Reference for iOS/macOS

API Overview

The Agora RTM SDK provides a stable messaging mechanism for you to implement real-time messaging scenarios.

This page lists the core APIs of the Agora RTM SDK. Unless otherwise specified, most of the core APIs should only be called after the loginByToken method call succeeds and after you receive the AgoraRtmLoginErrorOk error code.

Following are the core functionalities that the Agora RTM SDK.

Login & Logout

The connection state between the SDK and the Agora RTM system is a core concept for you to understand before developing an RTM app. For more information, see:

Method Description
initWithAppId Creates and initializes an AgoraRtmKit instance.
loginByToken Logs in the Agora RTM system. AgoraRtmLoginBlock returns the result of this method call.
logoutWithCompletion Logs out of the Agora RTM system. AgoraRtmLogoutBlock returns the result of this method call.
Event Description
connectionStateChanged Occurs when the connection state between the SDK and the Agora RTM system changes.

Sending a peer-to-peer message

Method Description
initWithText Creates and initializes an AgoraRtmMessage instance.
initWithRawData Creates and initializes an AgoraRtmRawMessage instance.
sendMessage Sends an (offline) peer-to-peer message to a specified user.
  • See AgoraRtmSendMessageOptions for the offline messaging settings.
  • AgoraRtmSendPeerMessageBlock returns the result of this method call.
  • When the message arrives, the specified user receives the messageReceived callback.
  • Event Description
    messageReceived Occurs when receiving a peer-to-peer message.

    Querying the online status of the specified users

    Method Description
    queryPeersOnlineStatus Queries the online status of the specified users. AgoraRtmQueryPeersOnlineBlock returns the result of this method call.

    Subscribing to or unsubscribing from the online status of specified user(s)

    Method Description
    subscribePeersOnlineStatus Subscribes to the online status of the specified user(s).
  • AgoraRtmSubscriptionRequestBlock returns the result of this method call.
  • unsubscribePeersOnlineStatus Unsubscribes from the online status of the specified user(s).
  • AgoraRtmSubscriptionRequestBlock returns the result of this method call.
  • queryPeersBySubscriptionOption Gets a list of the peers, to whose specific status you have subscribed.
  • AgoraRtmQueryPeersBySubscriptionOptionBlock returns the result of this method call.
  • See AgoraRtmPeerSubscriptionOptions for the subscription option type.
  • Event Description
    PeersOnlineStatusChanged Occurs when the online status of the peers, to whom you subscribe, changes.

    User attribute operations

    Method Description
    setLocalUserAttributes Substitutes the local user’s attributes with new ones. AgoraRtmSetLocalUserAttributesBlock returns the result of this method call.
    addOrUpdateLocalUserAttributes Adds or updates the local user’s attribute(s). AgoraRtmAddOrUpdateLocalUserAttributesBlock returns the result of this method call.
    deleteLocalUserAttributesByKeys Deletes the local user’s attributes using attribute keys. AgoraRtmDeleteLocalUserAttributesBlock returns the result of this method call.
    clearLocalUserAttributes Clears all attributes of the local user. AgoraRtmClearLocalUserAttributesBlock returns the result of this method call.
    getUserAttributes Gets all attributes of a specified user. AgoraRtmGetUserAttributesBlock returns the result of this method call.
    getUserAttributesByKeys Gets the attributes of a specified user by attribute keys. AgoraRtmGetUserAttributesBlock returns the result of this method call.

    Channel attribute operations

    Method Description
    setLocalUserAttributes Sets the attributes of a specified channel with new ones.
  • AgoraRtmSetChannelAttributesBlock returns the result of this method call.
  • addOrUpdateChannelAttributes Adds or updates the attribute(s) of a specified channel.
  • AgoraRtmAddOrUpdateChannelAttributesBlock returns the result of this method call.
  • deleteChannelAttributesByKeys Deletes the attributes of a specified channel by attribute keys.
  • AgoraRtmDeleteChannelAttributesBlock returns the result of this method call.
  • clearChannelAttributes Clears all attributes of a specified channel.
  • AgoraRtmClearChannelAttributesBlock returns the result of this method call.
  • getChannelAttributes Gets all attributes of a specified channel.
  • AgoraRtmGetChannelAttributesBlock returns the result of this method call.
  • getChannelAttributesByKeys Gets the attributes of a specified channel by attribute keys.
  • AgoraRtmGetChannelAttributesBlock returns the result of this method call.
  • Event for all channel members Description
    attributeUpdate Occurs when the channel attributes are updated, and returns all attributes of the channel.
  • See enableNotificationToChannelMembers for how to enable this callback.
  • Retrieving channel member count of specified channel(s)

    Method Description
    getChannelMemberCount Gets the member count of specified channel(s).
  • AgoraRtmChannelMemberCountBlock returns the result of this method call.
  • Joining or leaving a channel

    Method Description
    createChannelWithId Creates an AgoraRtmChannel instance.
    joinWithCompletion Joins the channel.
  • AgoraRtmJoinChannelBlock returns the result of this method call.
  • When the user successfully joins the channel, all remote members in the channel receive the memberJoined callback.
  • leaveWithCompletion Leaves the channel.
  • AgoraRtmLeaveChannelBlock returns the result of this method call.
  • When the user successfully leaves the channel, all remote members in the channel receive the memberLeft callback.
  • destroyChannelWithId Destroys a specified local AgoraRtmChannel instance.
    Event Description
    memberJoined Occurs when a remote user joins the channel.
    memberLeft Occurs when a remote member leaves the channel.
    memberCount Occurs when the number of the channel members changes, and returns the new number.

    Channel message

    Method Description
    initWithText Creates and initializes an AgoraRtmMessage instance.
    initWithRawData Creates and initializes an AgoraRtmRawMessage instance.
    sendMessage Allows a channel member to send a message to all members in the channel. AgoraRtmSendChannelMessageBlock returns the result of this method call. When the message arrives, all remote members in the channel receive the messageReceived callback.
    Event Description
    messageReceived Occurs when the local user receives a channel message.

    Retrieving a member list of the channel

    Method Description
    getMembersWithCompletion Retrieves a member list of the channel.
  • See AgoraRtmMember for the data structure of the channel member.
  • AgoraRtmGetMembersBlock returns the result of this method call.
  • Call invitation management

    • API calling sequence for canceling a sent call invitation:

    • API calling sequence for accepting or declining a received call invitation:

    Method for Managing a Call Manager Description
    getRtmCallKit Gets the AgoraRtmCallKit instance.
    Caller Method Description
    initWithCalleeId Allows the caller to create and initialize an AgoraRtmLocalInvitation object.
    sendLocalInvitation Allows the caller to send a call invitation to a remote user.
  • AgoraRtmLocalInvitationSendBlock returns the result of this method call.
  • See AgoraRtmInvitationApiCallErrorCode for the error code.
  • cancelLocalInvitation Allows the caller to cancel a call invitation.
  • AgoraRtmLocalInvitationCancelBlock returns the result of this method call.
  • See AgoraRtmInvitationApiCallErrorCode for the error code.
  • Callee Method Description
    acceptRemoteInvitation Allows the callee to accept a call invitation.
  • AgoraRtmRemoteInvitationAcceptBlock returns the result of this method call.
  • See AgoraRtmInvitationApiCallErrorCode for the error code.
  • refuseRemoteInvitation Allows the callee to refuse a call invitation.
  • AgoraRtmRemoteInvitationRefuseBlock returns the result of this method call.
  • See AgoraRtmInvitationApiCallErrorCode for the error code.
  • Caller Event Description
    localInvitationReceivedByPeer Callback to the caller: occurs when the callee receives the call invitation.
    localInvitationCanceled Callback to the caller: occurs when the caller cancels an outgoing call invitation.
    localInvitationAccepted Callback to the caller: occurs when the callee accepts the call invitation.
    localInvitationRefused Callback to the caller: occurs when the callee declines the call invitation.
    localInvitationFailure Callback to the caller: occurs when the life cycle of an outgoing call invitation ends in failure. See AgoraRtmLocalInvitationErrorCode for the error code.
    Callee Event Description
    remoteInvitationReceived Callback to the callee: occurs when the callee receives a call invitation.
  • At the same time, the SDK returns an AgoraRtmRemoteInvitation object to the callee.
  • remoteInvitationCanceled Callback to the callee: occurs when the caller cancels the incoming call invitation.
    remoteInvitationAccepted Callback to the callee: occurs when the callee accepts a call invitation.
    remoteInvitationRefused Callback to the callee: occurs when the callee declines a call invitation.
    remoteInvitationFailure Callback to the callee: occurs when the life cycle of the incoming call invitation ends in failure. See AgoraRtmRemoteInvitationErrorCode for the error code.

    Renew the Token

    Method Description
    renewToken Renews the current RTM Token. AgoraRtmRenewTokenBlock returns the result of this method call.
    Event Description
    rtmKitTokenDidExpire Occurs when the current RTM Token exceeds the 24-hour validity period.

    Logfile Settings & Version Check

    • Logfile-related operations can be done after creating and initializing the AgoraRtmKit instance and before calling the loginByToken method.
    • getSDKVersion is a static method. You can call it before creating and initializing an AgoraRtmKit instance.
    Method Description
    setLogFile Specifies the default path to the SDK log file.
    setLogFileSize Sets the log file size in KB.
    setLogFilters Sets the output log level of the SDK.
    getSDKVersion Gets the version of the Agora RTM SDK.

    Customized method

    Method Description
    ‭setParameters Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.
    X
    Is this page helpful?