Inviting Members

Overview

This guide covers inviting users to a conversation (members), listening for invites to join a conversation as well as new members joining.

Before you begin, make sure you added the SDK to your app and you are able to create a simple conversation.

NOTE: A step-by-step tutorial to build a chat application is available here.

This guide will introduce you to the following concepts.

  • Invites - you can invite users to a conversation
  • Application Events - member:invited events that fire on an Application, before you are a Member of a Conversation
  • Conversation Events - member:joined and text events that fire on a Conversation, after you are a Member

Listening for Conversation invites and accepting them

Achieved by adding a listener on the application object for the member:invited event:

app.on("member:invited", (member, event) => {
  //identify the sender and type of conversation.
  if (event.body.cname.indexOf("CALL") != 0 && member.invited_by) {
    console.log("*** Invitation received:", event);

    //accept an invitation.
    app.getConversation(event.cid || event.body.cname)
      .then((conversation) => {
        conversation
          .join()
          .then(() => {
            ...
          })
          .catch(this.errorLogger)
      })
      .catch(this.errorLogger)
  }
})
private val memberEventListener = object : NexmoMemberEventListener {
    override fun onMemberInvited(memberEvent: NexmoMemberEvent) {
        Log.d("TAG", "Member ${memberEvent.member.user.name} invited to the conversation")

        // Join user to the conversation (accept the invitation)
        conversation?.join(memberEvent.member.user.name, joinConversationListener)
    }

    override fun onMemberAdded(memberEvent: NexmoMemberEvent) {}

    override fun onMemberRemoved(memberEvent: NexmoMemberEvent) {}
}

private val joinConversationListener = object: NexmoRequestListener<String>{
    override fun onSuccess(memberId: String?) {
        Log.d("TAG", "Member joined the conversation $memberId")
    }

    override fun onError(apiError: NexmoApiError) {
        Log.d("TAG", "Error: Unable to join member to the conversation $apiError")
    }
}

conversation?.addMemberEventListener(memberEventListener)
NexmoMemberEventListener memberEventListener = new NexmoMemberEventListener() {
    @Override
    public void onMemberInvited(@NonNull NexmoMemberEvent memberEvent) {
        Log.d("TAG", "Member " + memberEvent.member.user.name + " invited to the conversation");

        // Join user to the conversation (accept the invitation)
        conversation.join(memberEvent.getMember().getUser().getName(), joinConversationListener);
    }

    @Override
    public void onMemberAdded(@NonNull NexmoMemberEvent memberEvent) {}

    @Override
    public void onMemberRemoved(@NonNull NexmoMemberEvent memberEvent) {}
};

NexmoRequestListener<String> joinConversationListener = new NexmoRequestListener<String>() {
    @Override
    public void onSuccess(@Nullable String memberId) {
        Log.d("TAG", "Member joined the conversation " + memberId);
    }

    @Override
    public void onError(@NonNull NexmoApiError apiError) {
        Log.d("TAG", "Error: Unable to join member to the conversation " + apiError);
    }
};

conversation.addMemberEventListener(memberEventListener);

Add NXMClientDelegate as an extension to a ViewController or similar, and implement client(_ client: NXMClient, didReceive conversation: NXMConversation):

Note: The first 2 methods below are required when implementing NXMClientDelegate:

extension ViewController: NXMClientDelegate {

    func client(_ client: NXMClient, didChange status: NXMConnectionStatus, reason: NXMConnectionStatusReason) {
        ...
    }

    func client(_ client: NXMClient, didReceiveError error: Error) {
        print("✆  ‼️ connection error: \(error.localizedDescription)")
        ...
    }

    func client(_ client: NXMClient, didReceive conversation: NXMConversation) {
        conversation.join { (error, member) in
            if let error = error {
                NSLog("Error joining conversation: \(error.localizedDescription)")
                return
            }
            NSLog("Conversation joined.")
        }
    }
}

Have a ViewController, or similar, conform to NXMClientDelegate and implement client:didReceiveConversation::

Note: The first 2 methods below are required when implementing NXMClientDelegate:

- (void)client:(nonnull NXMClient *)client didChangeConnectionStatus:(NXMConnectionStatus)status reason:(NXMConnectionStatusReason)reason {
    ...
}

- (void)client:(nonnull NXMClient *)client didReceiveError:(nonnull NSError *)error {
    NSLog(@"✆  ‼️ connection error: %@", [error localizedDescription]);
    ...
}

- (void)client:(NXMClient *)client didReceiveConversation:(NXMConversation *)conversation {
    [conversation join:^(NSError * _Nullable error, NXMMember * _Nullable member) {
        if (error) {
            NSLog(@"Error joining conversation: %@", error.localizedDescription);
            return;
        }
        NSLog(@"Conversation joined.");
    }];
}

Listening for members who joined a conversation

Listen for the member:joined event on the conversation:

conversation.on("member:joined", (member, event) => {
  const date = new Date(Date.parse(event.timestamp))
  console.log(`*** ${member.user.name} joined the conversation`)
  ...
})

private val memberEventListener = object : NexmoMemberEventListener {
    override fun onMemberInvited(memberEvent: NexmoMemberEvent) {}

    override fun onMemberAdded(memberEvent: NexmoMemberEvent) {
        Log.d("TAG", "Member ${memberEvent.member.user.name} added to the conversation")
    }

    override fun onMemberRemoved(memberEvent: NexmoMemberEvent) {}
}

conversation?.addMemberEventListener(memberEventListener)
NexmoMemberEventListener memberEventListener = new NexmoMemberEventListener() {
    @Override
    public void onMemberInvited(@NonNull NexmoMemberEvent memberEvent) {}

    @Override
    public void onMemberAdded(@NonNull NexmoMemberEvent memberEvent) {
        Log.d("TAG", "Member " + memberEvent.getMember().getUser().getName() + " added the conversation");
    }

    @Override
    public void onMemberRemoved(@NonNull NexmoMemberEvent memberEvent) {}
};

conversation.addMemberEventListener(memberEventListener);

Add NXMConversationDelegate as an extension to a ViewController or similar, and implement conversation(_ conversation: NXMConversation, didReceive event: NXMMemberEvent):

Note: The first method below is required when implementing NXMConversationDelegate:

extension ViewController: NXMConversationDelegate {
    func conversation(_ conversation: NXMConversation, didReceive error: Error) {
        NSLog("Conversation error: \(error.localizedDescription)")
    }
    func conversation(_ conversation: NXMConversation, didReceive event: NXMMemberEvent) {
        if event.state == .joined {
            NSLog("\(event.member.user.name) joined.")
        }
    }
}

Have a ViewController, or similar, conform to NXMConversationDelegate and implement conversation:didReceiveImageEvent::

Note: The first method below is required when implementing NXMConversationDelegate:

- (void)conversation:(NXMConversation *)conversation didReceive:(NSError *)error {
    NSLog(@"Conversation error: %@", error.localizedDescription);
}
- (void)conversation:(NXMConversation *)conversation didReceiveMemberEvent:(NXMMemberEvent *)event {
    if (event.state == NXMMemberStateJoined) {
        NSLog(@"%@ joined", event.member.user.name);
    }
}

Inviting users to a conversation

Users can be invited to join conversation - their username will be used:

conversation.invite({ user_name: "Jane" }).then((member) => {
  console.log(member.state + " user: " + member.user.id + " " + member.user.name);
}).catch((error) => {
  console.log(error);
});
conversation.invite(userName,  object: NexmoRequestListener<String>{
    override fun onSuccess(result: String?) {
        Log.d("TAG", "User invited $result")
    }

    override fun onError(apiError: NexmoApiError) {
        Log.d("TAG", "Error: Unable to invite user ${apiError.message}")
    }
})
conversation.invite(userName, new NexmoRequestListener<String>() {
    @Override
    public void onSuccess(@Nullable String result) {
        Log.d("TAG", "User invited " + result);
    }

    @Override
    public void onError(@NonNull NexmoApiError apiError) {
        Log.d("TAG", "Error: Unable to invite user " + apiError.getMessage());
    }   
});
conversation.inviteMember(withUsername: "Jane", completion: { (error) in
    if let error = error {
        NSLog("Error inviting user: \(error.localizedDescription)")
        return
    }
    NSLog("User invited")
})
[conversation inviteMemberWithUsername:@"Jane" completion:^(NSError * _Nullable error) {
    if (error) {
        NSLog(@"Error inviting user: %@", error);
        return;
    }
    NSLog(@"User invited");
}];