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.
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.

    User attribute-related 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. AgoraRtmClearLocalUserAttributesBlockreturns 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.

    Joining or leaving a channel

    Method Description
    createChannelWithId Creates an AgoraRtmChannel instance.
    joinWithCompletion Joins the channel.
  • AgoraRtmJoinChannelBlock AgoraRtmRemoteInvitationRefuseBlock 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 AgoraRtmChannel instance.
    Event Description
    memberJoined Occurs when a remote user joins the channel.
    memberLeft Occurs when a remote user leaves the channel.

    Channel message

    Method Description
    initWithText Creates and initializes an AgoraRtmMessage 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 the member list of the channel

    Method Description
    getMembersWithCompletion Retrieves the 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 Description
    getRtmCallKit Gets the AgoraRtmCallKit instance.
    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.
  • 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
    localInvitationCanceled Callback to the caller: occurs when the caller cancels an outgoing call invitation.
    localInvitationReceivedByPeer Callback to the caller: occurs when the callee receives the 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.
  • 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.
    remoteInvitationCanceled Callback to the callee: occurs when the caller cancels the incoming 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 token. AgoraRtmRenewTokenBlock returns the result of this method call.
    Event Description
    rtmKitTokenDidExpire Occurs when the token expires.

    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?