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 (
- A callee can attach additional text information using the
responseparameter when refusing an incoming call invitation.
- A caller can initiate multiple call invitations at the same time to send call invitations to multiple users.
- 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
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
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.
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
LocalInvitationErrorthat 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
RemoteInvitationErrorthat 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
sendLocalInvitationto send the call invitation, and then the callee receives the
- Step 2: The callee calls
acceptRemoteinvitationand 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.
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
cancelLocalInvitation to send or cancel a call invitation, or when the callee calls
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.
||The call invitation is not started. For example, the caller calls
||The caller calls
||The callee calls the
||The caller calls the
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.
The following diagram shows the change of the call invitation states that are related to the caller.
The following diagram shows the change of the call invitation states that are related to the callee.
API call sequence diagram
Cancel a sent call invitation
Accept or refuse a call invitation
contentparameter of the local invitation must be in UTF-8 format and not exceed 8 KB in length.
responseparameter of the remote invitation must be in UTF-8 format and not exceed 8 KB in length.
channelIdparameter 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
channelIdparameter must be in UTF-8 format and not exceed 64 KB in length.
See Call invitation.