SDKsAndroidEnterprise

Start a single call

Initiate a direct audio or video call and acquire room credentials using signalingInvite().

Initiate a direct audio or video call. The OpenIM Android SDK handles signaling negotiation and room state synchronization; once room credentials are returned, connect to your real-time audio/video media engine.

Code example

SignalingInvitationInfo invitation = new SignalingInvitationInfo();
invitation.setInviterUserID(currentUserID);
invitation.setInviteeUserIDList(Collections.singletonList(peerUserID));
invitation.setGroupID("");
invitation.setRoomID(roomID);
invitation.setTimeout(30);
invitation.setMediaType("video");
invitation.setSessionType(ConversationType.SINGLE_CHAT);
invitation.setPlatformID(Platform.ANDROID);
invitation.setCustomData("{\"source\":\"contact-card\"}");

SignalingInfo info = new SignalingInfo();
info.setInvitation(invitation);
info.setOfflinePushInfo(offlinePushInfo);

OpenIMClient.getInstance().signalingManager.signalingInvite(
    new OnBase<SignalingCertificate>() {
        @Override
        public void onSuccess(SignalingCertificate credentials) {
            // credentials provides roomID, token, and liveURL to join the media room.
        }

        @Override
        public void onError(int code, String error) {
            // code and error describe the failure.
        }
    },
    info
);

Parameters

Calling method:

signalingInvite(OnBase<SignalingCertificate> callback, SignalingInfo info)

The parameters below represent public properties on Android's SignalingInfo and its nested objects. When initiating a call, populate invitation and optional offlinePushInfo; participant and top-level userID are typically populated in incoming event payloads rather than outgoing invitations.

Parameter	Type	Required	Description
`invitation`	`SignalingInvitationInfo`	Yes	Call invitation payload.
`invitation.inviterUserID`	`String`	Yes	Inviter user ID; pass the authenticated user ID.
`invitation.inviteeUserIDList`	`List<String>`	Yes	Callee user list; contains exactly one peer user ID in direct calls.
`invitation.groupID`	`String`	Yes	Target group ID; pass an empty string `""` for direct calls.
`invitation.roomID`	`String`	Yes	Unique room identifier used to track and merge call state.
`invitation.timeout`	`long`	Yes	Invitation timeout interval in seconds.
`invitation.mediaType`	`String`	Yes	Media stream type, conventionally `"audio"` or `"video"`.
`invitation.sessionType`	`int`	Yes	Set `ConversationType.SINGLE_CHAT` for direct calls, or `ConversationType.SUPER_GROUP_CHAT` for group calls.
`invitation.platformID`	`int`	Yes	Current client platform identifier; pass `Platform.ANDROID`.
`invitation.customData`	`String`	No	Custom business metadata string attached to the invitation.
`invitation.initiateTime`	`long`	No	Timestamp when the invitation was initiated. Managed automatically by the signaling layer.
`offlinePushInfo`	`OfflinePushInfo`	No	Push notification payload delivered when invitees are offline.
`offlinePushInfo.title`	`String`	Conditional	Notification title; required when `offlinePushInfo` is provided.
`offlinePushInfo.desc`	`String`	Conditional	Notification body text; required when `offlinePushInfo` is provided.
`offlinePushInfo.ex`	`String`	Conditional	Extension string attached to push payload; pass `""` if not needed.
`offlinePushInfo.iOSPushSound`	`String`	Conditional	Sound resource for iOS push notifications; required when providing push info.
`offlinePushInfo.iOSBadgeCount`	`boolean`	Conditional	Whether to badge iOS app icons; required when providing push info.
`participant`	`ParticipantMeta`	No	Participant profile metadata; omit when sending invitations.
`userID`	`String`	No	User ID associated with the operation; omit when sending invitations.

Return value

Upon success, credentials in onSuccess returns a SignalingCertificate object containing:

roomID: Unique global identifier of the call room.
token: Authentication token used to join the media room.
liveURL: Media server endpoint URL.
busyLineUserIDList: List of busy user IDs if the target is already engaged in another call.

State changes after the call

Callback confirmation: The onSuccess callback confirms that the signaling request succeeded and room credentials were acquired. It does not indicate that the remote peer has answered or joined media streams.
Asynchronous event delivery: Both caller and callee track subsequent call events (such as answer, reject, cancel, or timeout) through OnSignalingListener. Track the overall call using roomID and monitor participant transitions using roomID:userID.
Media connection: Connect to the real-time audio/video engine only after obtaining a valid token and roomID. For real-time updates regarding participant entries and stream states, see Handle call events.

Was this page helpful?