Introduction

You can use the Agora RTM SDK to manage a call invitation by:

  • Sending a call invitation.
  • Canceling a sent call invitation.
  • Accepting an incoming call invitation.
  • Refusing an incoming call invitation.

Call invitation also includes the following functions:

  • A caller can attach additional information when sending out a call invitation, such as channel name (channelId) and text messages (content).
  • A callee can attach additional text information using the response parameter when refusing an incoming call invitation.
  • A caller can initiate multiple call invitations at the same time to send call invitations to multiple users.
The call invitation function in the RTM SDK does not handle operations after a callee accepts the invitation, such as joining an RTC channel. You must implement the related media functions using a media SDK, such as the Agora RTC SDK.

Scenarios

  • A call invitation requiring notification of an incoming call.
  • A screen-sharing scenario requiring call invitations.
  • A whiteboard-sharing scenario requiring a video call between two parties.
  • A call invitation requiring synchronizing the states of both parties.

Life cycle of a call invitation

The Agora RTM SDK introduces LocalInvitation and RemoteInvitation for starting a call invitation. You can think of them as the same invitation taking two different forms.

The beginning of a call invitation life cycle

A LocalInvitation object is created when the caller explicitly calls createLocalInvitation. It allows the caller to specify the callee, set text messages, or check the state of the call invitation.
A RemoteInvitation object is returned by the onRemoteInvitationReceived callback when the callee receives the call invitation. It allows the callee to check the ID of the caller, set a response, or check the state of the call invitation.

The end of a call invitation life cycle

The life cycle of a LocalInvitation object ends when the caller receives any of the following callbacks, and the SDK releases it when the corresponding callback ends:

  • onLocalInvitationCanceled: The caller has cancelled the call invitation.

  • onLocalInvitationAccepted: The callee has accepted the call invitation.

  • onLocalInvitationRefused: The callee has refused the call invitation.

  • onLocalInvittionFailure: The call invitation has started but ends in failure. The error code LocalInvitationError that this callback returns covers the following:

    • LOCAL_INVITATION_ERR_PEER_OFFLINE: The callee is offline.
    • LOCAL_INVITATION_ERR_PEER_NO_RESPONSE: The callee does not ACK within 30 seconds after the caller sends out the call invitation.
    • LOCAL_INVITATION_ERR_INVITATION_EXPIRE: The call invitation has expired (It has not been cancelled, accepted, or refused within 60 seconds after being received by the callee).

The life cycle of a RemoteInvitation object ends when the callee receives any of the following callbacks, and the SDK releases it when the corresponding callback ends:

  • onRemoteInvitationCanceled: The caller has cancelled the call invitation.

  • onRemoteInvitationAccepted: The callee has accepted the call invitation.

  • onRemoteInvitationRefused: The callee has refused the call invitation.

  • onRemoteInvitationFailure: The call invitation ends in failure. The error code RemoteInvitationError that this callback returns covers the following:

    • REMOTE_INVITATION_ERR_PEER_OFFLINE: The caller is offline when the callee accepts the call invitation.
    • REMOTE_INVITATION_ERR_ACCEPT_FAILURE: The caller does not ACK after the callee accepts the call invitation.
    • REMOTE_INVITATION_ERR_INVITATION_EXPIRE: The call invitation has expired (It has not been canceled, accepted, or refused within 60 seconds after being received by the callee).

The process of accepting a call invitation is a three-step handshake process:

  • Step 1: The caller calls sendLocalInvitation to send the call invitation, and then the callee receives the onRemoteInvitationReceived callback.
  • Step 2: The callee callsacceptRemoteinvitation and the caller is notified that the callee has accepted the call invitation.
  • Step 3: The callee is notified that the caller has ACKed to this action. The call invitation succeeds.

Behavior boundaries

Now that you understand the life cycle of a call invitation, it is important to understand how to tell normal behaviors from abnormalities. As a golden rule, all call invitation-specific method calls should be conducted within the life cycle of a call invitation.

When the caller calls sendLocalInvitation or cancelLocalInvitation to send or cancel a call invitation, or when the callee calls acceptRemoteInvitation or refuseRemoteInvitation to accept or refuse a call invitation, the SDK validates the behavior and returns the onFailure callback with the corresponding error code invitationApiCallError if it detects a breach of the rule.

Error code Description
INVITATION_API_CALL_ERR_NOT_STARTED The call invitation is not started. For example, the caller calls cancelLocalInvitation before sendLocalInvitation.
INVITATION_API_CALL_ERR_ALREADY_END The caller calls sendLocalInvitation, cancelLocalInvitation, acceptRemoteInvitation, or refuseRemoteInvitation when the lifecycle of a call invitation ends.
INVITATION_API_CALL_ERR_ALREADY_ACCEPT The callee calls the acceptRemoteInvitation method repeatedly.
INVITATION_API_CALL_ERR_ALREADY_SENT The caller calls the sendLocalInvitation method repeatedly.

State diagram

In a call invitation session, the caller can use getState that the LocalInvitation object provides to get the state of the current call invitation. The callee can use getState that the SDK-returned RemoteInvitation object provides to get the state of the current call invitation.

LocalInvitationState

The following diagram shows the change of the call invitation states that are related to the caller.

img

RemoteInvitationState

The following diagram shows the change of the call invitation states that are related to the callee.

img

API call sequence diagram

Cancel a sent call invitation

img

Accept or refuse a call invitation

img

Considerations

  • The content parameter of the local invitation must be in UTF-8 format and not exceed 8 KB in length.
  • The response parameter of the remote invitation must be in UTF-8 format and not exceed 8 KB in length.
  • The channelId parameter of the local invitation is for the interoperability with the legacy Agora Signaling SDK only. Only when you set this parameter can a Signaling SDK user receive the onInviteReceived callback. The channelId parameter must be in UTF-8 format and not exceed 64 KB in length.

API Reference

See Call invitation.

Sample project

We provide a demo project on GitHub. You can try the demo and view the source code.