Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Interacting with contacts

Start a BBM chat

Before you begin: Make sure that you have completed the task, /java/documentation/setting_up_your_app_with_the_bbm_platform_1387556_11.html, and that the class that displays the MyBBMChatScreen screen passes in a reference to the application's associated BBMPlatformContext object into the screen's contructor.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
  2. Create a class that extends MainScreen. In the constructor for this screen class, pass in the application's associated BBMPlatformContext.
    public class MyBBMChatScreen extends MainScreen
    {
        public MyBBMChatScreen(BBMPlatformContext platformContext) 
        {
    
        }
    }
  3. Invoke BBMPlatformContext.getUIService().startBBMChat() to open a chat window. You must specify a message as a parameter. This message appears in the reply field of the conversation window. You can specify a contact to chat with by passing in a parameter. If you do not specify a contact, a contact picker UI component containing all the contacts in the user's BlackBerry Messenger contact list will open automatically.
    public class MyBBMChatScreen extends MainScreen
    {
        public MyBBMChatScreen(BBMPlatformContext platformContext) 
        {
            platformContext.getUIService().startBBMChat("Let's chat");
        }
    }

Code sample: Starting a BBM chat

The following code sample assumes that the class that displayed the MyBBMChatScreen has passed a reference to the application's associated BBMPlatformContext object into the MyBBMChatScreen constructor.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;

public class MyBBMChatScreen extends MainScreen
{
    public MyBBMChatScreen(BBMPlatformContext platformContext)
    {
        platformContext.getUIService().startBBMChat("Let's chat!");
    }
}

Send a download invitation to a contact

Before you begin: Make sure you have completed the task, Register your application with the BlackBerry Messenger Platform, and that the class that displays the MyBBMInviteScreen screen passes in a reference to the application's associated BBMPlatformContext object into the screen's contructor.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
    import net.rim.device.api.ui.component.*;
  2. Create a class that extends MainScreen. In the constructor for this screen class, pass in the application's associated BBMPlatformContext.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext)
        {
    
        }
    }
  3. In the constructor, retrieve a reference to the messaging service associated with this application's platform context.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
        }
    }
  4. Invoke MessagingService.sendDownloadInvitation() to invite a contact to download your application. A Contact picker UI component opens for the user to choose a contact to invite.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
            messagingService.sendDownloadInvitation();
        }
    }

Code sample: Sending a download invitation to a contact

The following code sample assumes that the class that displayed the MyBBMInviteScreen has passed a reference to the application's associated BBMPlatformContext object into the MyBBMInviteScreen constructor.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;
import net.rim.device.api.ui.component.*;

public class MyBBMInviteScreen
{
    public MyBBMInviteScreen(BBMPlatformContext platformContext)
    {
        MessagingService messagingService = platformContext.getMessagingService();
        messagingService.sendDownloadInvitation();
    }
}

Send a join invitation to a contact

Before you begin: Make sure that you have completed the task, Register your application with the BlackBerry Messenger platform, and that the class that displays the screen in the following code sample passes in a reference to the application's associated BBMPlatformContext object.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
    import net.rim.device.api.ui.component.*;
  2. Create a class that extends MainScreen. In the constructor for this screen class, pass in the application's associated BBMPlatformContext.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext)
        {
    
        }
    }
  3. In the MyBBMInviteScreen constructor, retrieve a reference to the messaging service associated with this application's platform context.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext)
        {
            MessagingService messagingService = platformContext.getMessagingService();
        }
    }
  4. /java/documentation/defining_service_listeners_1489649_11.html. The code sample in step 5 assumes that you named the listener class, MyChannelListener.
  5. Invoke MessagingService.createChannel() to create a new BBMPlatformChannel, passing in your channel listener class.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext)
        {
            MessagingService messagingService = platformContext.getMessagingService();
            BBMPlatformChannel channel = messagingService.createChannel(new MyChannelListener());
        }
    }
  6. In an if statement that checks whether you created the BBMPlatformChannel successfully, invoke BBMPlatformChannel.sendInvitation() to invite a contact to your application. In the parameters for sendInvitation(), you can specify a message to be displayed when the contact receives the invitation, a parameter that will be passed to the application's main method as args[1], and an expiry time. The following code sample passes in the value 0 for expiry time (that is, the invitation never expires). A Contact picker UI component opens for the user to choose a contact to invite.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext)
        {
            MessagingService messagingService = platformContext.getMessagingService();
            BBMPlatformChannel channel = messagingService.createChannel(new MyChannelListener());
            
            if (channel != null) 
            {
                channel.sendInvitation(“Let's play a game”, "Chess App", 0);
            }
        }
    }
After you finish:

You can interact with the contact that you invited to your channel when they accept your invitation.

Code sample: Sending a join invitation to a contact

The following code sample assumes that the class that displayed the MyBBMInviteScreen has passed a reference to the application's associated BBMPlatformContext object into the MyBBMScreen constructor.

This code sample also assumes that you have completed the task, /java/documentation/defining_service_listeners_1489649_11.html and named the channel listener class, MyChannelListener.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;
import net.rim.device.api.ui.component.*;

public class MyBBMInviteScreen extends MainScreen
{
    public MyBBMInviteScreen(BBMPlatformContext platformContext)
    {
        MessagingService messagingService = platformContext.getMessagingService();
       
        BBMPlatformChannel channel = messagingService.createChannel(new MyChannelListener());

        if (channel != null) 
        {
            channel.sendInvitation(“Let's play a game”, "Chess App", 0);
        }
    }
}

Send a message to a contact

Before you begin: Complete the task, Register your application with the BlackBerry Messenger platform. Verify that the class that displays the screen in the following code sample passes in a reference to the BBMPlatformContext object associated with the application.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.io.*;
    import net.rim.blackberry.api.bbm.platform.profile.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
    import net.rim.device.api.ui.component.*;
  2. Create a class that extends MainScreen. In the constructor for this screen class, pass in the application's associated BBMPlatformContext.
    public class MyBBMScreen extends MainScreen
    {
        public MyBBMScreen(BBMPlatformContext platformContext)
        {
    
        }
    }
  3. Declare an instance of BBMPlatformChannel as a member variable of the MyBBMScreen class.
    public class MyBBMScreen extends MainScreen
    {
        BBMPlatformChannel _channel;
    
        public MyBBMScreen(BBMPlatformContext platformContext)
        {
            
        }
    }
  4. In the MyBBMScreen constructor, retrieve an instance of the messaging service.
    public MyBBMScreen(BBMPlatformContext platformContext)
    {
        MessagingService myMessagingService = platformContext.getMessagingService();
    }
  5. Create a channel passing in an instance of a BBMPlatformChannelListener that you will define in step 9.
    public MyBBMScreen(BBMPlatformContext platformContext)
    {
        MessagingService myMessagingService = platformContext.getMessagingService();
    
        _channel = messagingService.createChannel(_channelListener);
    }
  6. Invite a contact to your application. In the parameters for sendInvitation(), you can specify a message to be delivered when the contact receives the invitation, a parameter that will be passed to the application's main method as args[1], and an expiry time. The following code sample passes in the value 0 for expiry time (that is, the invitation never expires). A Contact picker UI component opens for the user to choose a contact to invite.
    public MyBBMScreen(BBMPlatformContext platformContext)
    {
        MessagingService messagingService = platformContext.getMessagingService();
        _channel = messagingService.createChannel(_channelListener);
            
        _channel.sendInvitation("Let's play a game", "Chess App", 0);
    }
  7. In the MyBBMScreen class, define a helper method, onContactJoined(), which the BBMPlatformChannelListener.contactJoined() callback method invokes. Pass in a reference to the contact who has just joined.
    public class MyBBMScreen extends MainScreen
    {
        BBMPlatformChannel _channel;
    
        public MyBBMScreen(BBMPlatformContext platformContext)
        {
            //code from steps 5 to 7    
        }
       
        private onContactJoined(BBMPlatformContact contact)
        {
    
        }
    }
  8. In the onContactJoined() method, create a message, wrap it in a BBMPlatformData object, and, in a try-catch block, send the message. In the following code sample, the message is sent to all contacts who have joined the channel, informing that a participant has left the game.
    private void onContactLeft(BBMPlatformContact contact)
    {
        String goodbyeMsg = contact.getDisplayName() + " has left the game.";
        BBMPlatformData data = new BBMPlatformData(goodbyeMsg);
    
        try {
            _channel.sendData(data, _channel.getContactList());
        }
        catch (BBMPlatformException e) 
        {
            // Error handler code
        }
    }
  9. In the MyBBMScreen class, define the channel listener, _channelListener, as a private inner class. In the contactJoined() method, invoke the onContactJoined() method passing in the BBMPlatformContact that just joined.
    public class MyBBMScreen extends MainScreen
    {
        public MyBBMScreen(BBMPlatformContext platformContext)
        {
            //code from steps 4 to 6
        }
    
        private void onContactJoined(BBMPlatformContact contact) 
        {
            //code from step 8
        }
    
        private BBMPlatformChannelListener _channelListener = new BBMPlatformChannelListener() 
        {
            public void contactsInvited(BBMPlatformConnection conn, BBMPlatformContactList 
                                         contactList) 
            {
            }
             
            public void contactsJoined(BBMPlatformConnection conn, BBMPlatformContactList
                                       contacts, String cookie, int type) 
            {
            }
    
            public void contactDeclined(BBMPlatformConnection conn, 
                                         BBMPlatformContact contact) 
            {
            }
         
            public void contactLeft(BBMPlatformConnection conn, BBMPlatformContact contact) 
            {
                onContactLeft(contact);
            }
           
            public void dataReceived(BBMPlatformConnection conn, BBMPlatformContact sender, 
                                      BBMPlatformData data) 
            {
            }
            
       			  }
        };
    }

Code sample: Sending a message to a contact

The following code sample assumes that the class that displayed the MyBBMScreen passed a reference to the application's associated BBMPlatformContext object into the MyBBMScreen constructor.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.io.*;
import net.rim.blackberry.api.bbm.platform.profile.*;
import net.rim.blackberry.api.bbm.platform.service.*;
import net.rim.device.api.ui.component.*;

public class MyBBMScreen extends MainScreen
{
    public MyBBMScreen(BBMPlatformContext platformContext)
    {
        MessagingService messagingService = platformContext.getMessagingService();
        _channel = messagingService.createChannel(_channelListener);
        _channel.sendInvitation("Let's play a game", "Chess App", 0);

    }

    private void onContactLeft(BBMPlatformContact contact) 
    {
        String goodbyeMsg = contact.getDisplayName() + " has left the game.";
        BBMPlatformData data = new BBMPlatformData(goodbyeMsg);

        try
        {
            _channel.sendData(data, _channel.getContactList());
        }
        catch (BBMPlatformException e) 
        {
           // Error handler code
        }
    }

    private BBMPlatformChannelListener _channelListener = new BBMPlatformChannelListener() 
    {
        public void contactsInvited(BBMPlatformConnection conn, BBMPlatformContactList contactList ) 
        {
        }
         
        public void contactsJoined(BBMPlatformConnection conn, BBMPlatformContactList contacts, String cookie,
         int type) 
        {
        }
        
        public void contactDeclined(BBMPlatformConnection conn, BBMPlatformContact contact) 
        {
        }
     
        public void contactLeft(BBMPlatformConnection conn, BBMPlatformContact contact) 
        {
            onContactLeft(contact);
        }
       
        public void dataReceived(BBMPlatformConnection conn, BBMPlatformContact sender, BBMPlatformData data) 
        {
        }
        
    };
}

Send a file to a contact

Before you begin: Make sure that you have completed the task, Register your application with the BlackBerry Messenger platform, and that the class that displays the MyBBMScreen screen in the following code sample passes in a reference to the application's associated BBMPlatformContext object.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
  2. Create a class that extends MainScreen. In the constructor for this screen class, pass in the BBMPlatformContext that is associated with your application.
    public class MyBBMScreen extends MainScreen
    {
        public MyBBMScreen(BBMPlatformContext platformContext) 
        {
    
        }
    }
  3. In the constructor, invoke UIService.showContactPicker() to display a contact picker that allows the user to choose the contact to send the file too. The following code sample displays a contact picker with all the user's BlackBerry Messenger contacts. The selected set of contacts is returned as an enumeration.
    public class MyBBMScreen extends MainScreen
    {
        public MyBBMScreen(BBMPlatformContext platformContext) 
        {
            BBMPlatformContactList contacts = plstformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false);
        }
    }
  4. If the user chose a contact from the contact picker, retrieve a reference to first element in the enumeration.
    public class MyBBMScreen extends MainScreen
    {
        public MyBBMScreen(BBMPlatformContext platformContext) 
        {
            BBMPlatformContactList contacts = plstformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false);
        
            if (contacts.size() > 0)
            {
                BBMPlatformContact contact = (BBMPlatformContact)contacts.getAll().nextElement();
            }
        }
    }
  5. Invoke FilePicker.getInstance() to display a file picker that allows the user to choose the file that they want to send. When the user has selected a file, assign the file path to a String.
    public class MyBBMScreen extends MainScreen
    {
        public MyBBMScreen(BBMPlatformContext platformContext) 
        {
            BBMPlatformContactList contacts = plstformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false);
        
            if (contacts.size() > 0)
            {
                BBMPlatformContact contact = (BBMPlatformContact)contacts.getAll().nextElement();
       
                FilePicker filePicker = FilePicker.getInstance();
                String filePath = filePicker.show();
            }
        }
    }
  6. Invoke MessagingService.sendFile() to send the file.
    public class MyBBMScreen extends MainScreen
    {
        public MyBBMScreen(BBMPlatformContext platformContext) 
        {
            BBMPlatformContactList contacts = plstformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false);
        
            if (contacts.size() > 0)
            {
                BBMPlatformContact contact = (BBMPlatformContact)contacts.getAll().nextElement();
       
                FilePicker filePicker = FilePicker.getInstance();
                String filePath = filePicker.show();
    
                platformContext.getMessagingService().sendFile(contact, filePath, "Here's the file");
            }
        }
    }

Code sample: Sending a file to a contact

The following code sample assumes that the class that pushed the MyBBMScreen has access to the BBMPlatformContext object for this application and has passed it into the MyBBMScreen constructor.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;

public class MyBBMScreen extends MainScreen
{
    public MyBBMScreen(BBMPlatformContext platformContext) 
    {
        BBMPlatformContactList contacts = platformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false);
    
        if (contacts.size() > 0)
        {
            BBMPlatformContact contact = (BBMPlatformContact)contacts.getAll().nextElement();
   
            FilePicker filePicker = FilePicker.getInstance();
            String filePath = filePicker.show();

            platformContext.getMessagingService().sendFile(contact, filePath, "Here's the file");
        }
    }
}

Display a list of contacts who have installed your application

Before you begin: Make sure that you have completed the task, Register your application with the BlackBerry Messenger platform, and that the class that displays the screen passes in a reference to the BBMPlatformContext object associated with your application.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
    import net.rim.device.api.ui.container.*;
    import java.util.*;
  2. Create a class that extends MainScreen. In the constructor for this screen class, pass in the application's associated BBMPlatformContext.
    public class MyBBMContactListScreen extends MainScreen
    {
        public MyBBMContactListScreen(BBMPlatformContext platformContext) 
        {
    
        }
    }
  3. In the constructor, invoke BBMPlatformContext.getContactListService() to retrieve a reference to the ContactListService object that is associated with the application.
    ContactListService contactListService = platformContext.getContactListService();
  4. In the constructor, invoke ContactListService.getContacts() to retrieve a BBMPlatformContactList object that contains all of the contacts who have installed this application.
    BBMPlatformContactList contacts = contactListService.getContactList();
  5. In the constructor, invoke BBMPlatformContactList.getAll() to retrieve an enumeration object of all of the contacts in the BBMPlatformContactList.
    Enumeration contactsEnum = contacts.getAll();
  6. In the constructor, you can now traverse the enumeration. The following code sample demonstrates how to display the names of the contacts.
    while(contactsEnum.hasMoreElements()) 
    {
        BBMPlatformContact contact = (BBMPlatformContact)contactsEnum.nextElement();
        myScreen.add(new LabelField(contact.getDisplayName());
    }

Code sample: Displaying a list of contacts who have installed your application

The following code sample assumes that the class that displayed the MyBBMContactListScreen has passed a reference to the application's associated BBMPlatformContext object into the MyBBMContactListScreen constructor.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;
import net.rim.device.api.ui.container.*;
import java.util.*;

public class MyBBMContactListScreen extends MainScreen 
{    
    public MyBBMContactListScreen(BBMPlatformContext platformContext) 
    {
        ContactListService contactListService = platformContext.getContactListService();
        BBMPlatformContactList contacts = contactListService.getContactList();
        Enumeration contactsEnum = contacts.getAll();

        while(contactsEnum.hasMoreElements())
        { 
            BBMPlatform contact = (BBMPlatformContact)contactsEnum.nextElement();
            add(new LabelField(contact.getDisplayName());
        }
    }
}

Respond to a contact's changes in your contact list

Before you begin: Make sure that you have completed the task, Register your application with the BlackBerry Messenger platform, and that the class that displays the screen passes in a reference to the application's associated BBMPlatformContext object.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
    import net.rim.device.api.ui.component.*;
  2. Create a class that implements the PresenceListener interface and extends MainScreen. In the constructor for this screen class, pass in the application's associated BBMPlatformContext object.
    public class MyBBMContactListScreen implements PresenceListener extends MainScreen
    {
        public MyBBMContactListScreen(BBMPlatformContext platformContext) 
        {
    
        }
    }
  3. In the constructor, invoke BBMPlatformContext.getContactListService().setPresenceListener() to assign the PresenceListener to your application.
    public class MyBBMContactListScreen implements PresenceListener
    {
        public MyBBMContactListScreen(BBMPlatformContext platformContext) 
        {
            platformContext.getContactListService().setPresenceListener(this);
        }
    }
  4. In the MyBBMContactListScreen class, implement the PresenceListener.presenceUpdated() method. The following code displays a dialog box that informs the user of changes to a contact in your BlackBerry Messenger contact list. The following code sample uses a helper method, getEventName(), to parse the eventType parameter and return a readable String.
    public void presenceUpdated(BBMPlatformContact contact, int eventType)
    {
        final String str = "[" + getEventName(eventType) + "] was changed by " + contact.getDisplayName();
        Dialog.inform(str);
    }
    
    private String getEventName(int eventType)
    {
        String eventName;
    
        switch(eventType)
        {
            case PresenceListener.EVENT_TYPE_DISPLAY_PICTURE:
                eventName = "Display picture";
                break;
            
            case PresenceListener.EVENT_TYPE_DISPLAY_NAME:
                eventName = "Display name";
                break;
            
            case PresenceListener.EVENT_TYPE_PERSONAL_MESSAGE:
                eventName = "Personal Message";
                break;
            
            case PresenceListener.EVENT_TYPE_STATUS:
                eventName = "Status";
                break;
            
            default:
                eventName = "Default";
        }
    }

Code sample: Responding to a contact's changes in your contact list

The following code sample assumes that the class that pushed the MyBBMContactListScreen has access to the BBMPlatformContext object for this application and has passed it into the MyBBMContactListScreen constructor.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.device.api.ui.component.*;

public class MyBBMContactListScreen implements PresenceListener
{
    public MyClass(BBMPlatformContext platformContext) 
    {
       platformContext.getContactListService().setPresenceListener(this);
    }

    public void presenceUpdated(BBMPlatformContact contact, int eventType)
    {
        final String str = "[" + getEventName(eventType) + "] was changed by " + contact.getDisplayName();
        Dialog.inform(str);
    }
 
    private String getEventName(int eventType)
    {
        String eventName;

        switch(eventType)
        {
            case PresenceListener.EVENT_TYPE_DISPLAY_PICTURE:
                eventName = "Display picture";
                break;
        
            case PresenceListener.EVENT_TYPE_DISPLAY_NAME:
                eventName = "Display name";
                break;
        
            case PresenceListener.EVENT_TYPE_PERSONAL_MESSAGE:
                eventName = "Personal Message";
                break;
        
            case PresenceListener.EVENT_TYPE_STATUS:
                eventName = "Status";
                break;
        
            default:
                eventName = "Default";
        }
    }
}

Send a session invitation to a contact

Before you begin: Make sure that you have completed the task, Register your application with the BlackBerry Messenger platform, and that the class that displays the screen passes in a reference to the application's associated BBMPlatformContext object into the screen's contructor.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
    import net.rim.device.api.ui.component.*;
  2. /java/documentation/defining_service_listeners_1489649_11.html. The code sample in step 5 assumes that you named the listener class, MySessionListener.
  3. Create a class that extends MainScreen. In the constructor for this screen class, pass in the application's associated BBMPlatformContext object.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
    
        }
    }
  4. In the constructor, retrieve a reference to the messaging service associated with this application's platform context.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
        }
    }
  5. Invoke MessagingService.createSession() to create a new BBMPlatformSession instance. Pass in an instance of the listener, that you defined in step 2, as a parameter.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
            BBMPlatformSession mySession = messagingService.createSession(new MySessionListener());
        }
    }
  6. Invoke BBMPlatformSession.sendInvitation() to invite a contact to your session. The sendInvitation()method can take three parameters. The first parameter specifies a message to be delivered when the contact receives the invitation. The second parameter is an argument that will be passed to the application's main method as args[1]. The third parameteris the invitation's expiry time. The following code sample passes in the value 0 for expiry time (that is, the invitation never expires). A Contact picker UI component will automatically open for the user to choose a contact to invite.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
            BBMPlatforSession mySession = messagingService.createSession(new MySessionListener());
    
            if (mySession != null) 
            {
                mySession.sendInvitation(“Let's play a game”, "Poker App", 0);
            }
            
        }
    }

Code sample: Sending a session join invitation to a contact

The following code sample assumes that the class that displayed the MyBBMInviteScreen has passed a reference to the application's associated BBMPlatformContext object into the MyBBMScreen constructor.

This code sample also assumes that you have completed the task, /java/documentation/defining_service_listeners_1489649_11.html and named the session listener class, MySessionListener.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;
import net.rim.device.api.ui.component.*;

public class MyBBMSessionScreen extends MainScreen
{
    public MyBBMSessionScreen(BBMPlatformContext platformContext)
    {
        MessagingService messagingService = platformContext.getMessagingService();
        BBMPlatforSession mySession = messagingService.createSession(new MySessionListener());

        if (mySession != null) 
        {
            mySession.sendInvitation(“Let's play a game”, "Poker App", 0);
        }
    }
}

Host a public session

A public session is a BlackBerry Messenger public chat with multiple users, in which every user can see and respond to each message in the chat.
Before you begin: Make sure that you have completed the task, Register your application with the BlackBerry Messenger platform, and that the class that displays the screen passes in a reference to the BBMPlatformContext object associated with your application into the screen's constructor.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
    import net.rim.device.api.ui.component.*;
    import net.rim.device.api.ui.container.MainScreen;
  2. /java/documentation/defining_service_listeners_1489649_11.html. The code sample in step 5 assumes that you named the listener class, MySessionListener.
  3. Create a class that extends MainScreen. In the constructor for this screen class, pass in the BBMPlatformContext object associated with your application.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
    
        }
    }
  4. In the constructor, retrieve a reference to the messaging service for this application.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
        }
    }
  5. Invoke MessagingService.createSession() to create a new BBMPlatformSession instance. Pass in an instance of the listener you defined in step 2 as a parameter.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
            BBMPlatformSession mySession = messagingService.createSession(new 
                 MySessionListener());
        }
    }
  6. Invoke BBMPlatformSession.setPublic() to set this session as public so that contacts who are not in your BlackBerry Messenger contact list can join. A confirmation dialog is presented to the user when this method is invoked.
    public class MyBBMInviteScreen extends MainScreen
    {
        public MyBBMInviteScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
            BBMPlatformSession mySession = messagingService.createSession(new 
             MySessionListener());
    
            boolean isHosting = mySession.setPublic();
    
             if (isHosting)
             {
                 // add code to send PIN and PPID to your web service
             }
        }
    }
    After you confirm that you want to host the session, you must send your web service your PIN and PPID. You can now receive join requests from users looking to join your session even if they are not one of your BlackBerry Messenger contacts. The joinRequestReceived() method in your BBMPlatformSessionListener implementation is invoked when a BBMPlatformIncomingJoinRequest object is received by your application. You can accept or decline this request by invoking BBMPlatformIncomingJoinRequest.accept() or BBMPlatformIncomingJoinRequest.decline(), respectively.

Code sample: Hosting a public session

The following code sample assumes that the class that displayed the MyBBMInviteScreen has passed a reference to the application's associated BBMPlatformContext object into the MyBBMInviteScreen constructor.

This code sample also assumes that you have completed the task, /java/documentation/defining_service_listeners_1489649_11.html and named the session listener class, MySessionListener.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.MainScreen;

public class MyBBMInviteScreen extends MainScreen
{
    public MyBBMInviteScreen(BBMPlatformContext platformContext)
    {
        MessagingService messagingService = platformContext.getMessagingService();
        BBMPlatformSession mySession = messagingService.createSession(new 
         MySessionListener());
        boolean isHosting = mySession.setPublic();

        if (isHosting) 
		{
			// add code to send PIN and PPID to your web service
		}	
    }
}

Join a public BBM session

A public session is a BlackBerry Messenger public chat with multiple users, in which every user can see and respond to each message in the chat.
Before you begin: Make sure that you have registered your application with the BlackBerry Messenger platform, and that the class that displays the MyBBMSessionScreen screen passes in a reference to the application's associated BBMPlatformContext object into the screen's contructor.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.blackberry.api.bbm.platform.service.*;
  2. Create a class that extends MainScreen. In the constructor for this screen class, pass in the BBMPlatformContext object that is associated with your application.
    public class MyBBMSessioncreen extends MainScreen
    {
        public MyBBMSessionScreen(BBMPlatformContext platformContext) 
        {
    
        }
    }
  3. In the constructor, retrieve a reference to the messaging service for the application.
    public class MyBBMSessionScreen extends MainScreen
    {
        public MyBBMSessionScreen(BBMPlatformContext platformContext) 
        {
            MessagingService messagingService = platformContext.getMessagingService();
        }
    }
  4. Invoke MessagingService.sendJoinRequest() to send a join request to a public session with the specified host ID, host PPID, and another parameter that you want to send to the host (for example, you could tell the host what level you would like to start on if the event is a game). The host must provide you with the host ID, host PPID, and a string that provides some additional information (this can be achieved using a matchmaking server that you must set up). The sendJoinRequest() method returns a BBMPlatformOutgoingJoinRequest object. A confirmation dialog is displayed when you invoke this method. If you want to cancel the join request before it is accepted or declined by the host, invoke BBMPlatformOutgoingJoinRequest.cancel().
    public class MyBBMSessionScreen extends MainScreen
    {
        public MyBBMSessionScreen(BBMPlatformContext platformContext) 
        {
            BBMPlatformOutgoingJoinRequest request = 
             messagingService.sendJoinRequest(123456, "12344567", "My game");
            if (request.getStatus() == BBMPlatformJoinRequest.REQUEST_STATUS_ACCEPTED)
             {
                 Dialog.inform("Welcome to My Chess Game");
             }
             else
             {
                 Dialog.inform("The request was declined");
             }
    	   }
    }

Code sample: Joining a public session

The following code sample assumes that the class that displayed the MyBBMChatScreen has passed a reference to the application's associated BBMPlatformContext object into the MyBBMChatScreen constructor.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;

public class MyBBMInviteScreen extends MainScreen
{
    public MyBBMInviteScreen(BBMPlatformContext platformContext) 
    {
        BBMPlatformOutgoingJoinRequest request = 
             messagingService.sendJoinRequest(123456, "12344567", "My game");
           if (request.getStatus() == BBMPlatformJoinRequest.REQUEST_STATUS_ACCEPTED)
           {
              Dialog.inform("Welcome to My Chess Game");
           }
           else
           {
              Dialog.inform("The request was declined");
           }
    }
}

Send a message to all participants in a session

Before you begin: /java/documentation/interacting_with_contacts_1448256_11.html to populate your session's contact list with contacts.
  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.bbm.platform.*;
    import net.rim.device.api.ui.component.*;
  2. In the if statement that you created when you completed the /java/documentation/interacting_with_contacts_1448256_11.html task, invoke BBMPlatformSession.getContactList() to retrieve an instance of BBMPlatformContactList. The returned contact list contains all the contacts that have accepted your invitation.
    if(mySession != null)
    {
        BBMPlatformContactList contacts = mySession.getContactList();
    }
  3. Create an instance of the BBMPlatformData class (a wrapper class for your data message) and String object (the body of your message). The following code sample uses the BBMPlatformData constructor that defines a content type (the first parameter of the constructor), the data itself (the second parameter), and an application defined ID (the third parameter). You can define the content type and ID using any String and int value respectively that your application requires for parsing. You can also send a message without those values if they are not needed.
    String myMsg = "Test data";
    BBMPlatformData data = new BBMPlatformData("Message", myMsg.getBytes(), 0);
  4. Invoke BBMPlatformSession.broadcastData(), inherited from its parent class, to send the message. The following code sample displays a dialog box confirming that the message has been sent.
    String myMsg = "Test data";
    BBMPlatformData data = new BBMPlatformData("Message", myMsg.getBytes(), 0);
         
    mySession.broadcastData(data, contacts);

Code sample: Sending a message to all participants in a session

The following code sample assumes that the class that displayed the MyBBMScreen has passed a reference to the application's associated BBMPlatformContext object into the MyBBMScreen constructor.

This code sample also assumes that you have completed the task, /java/documentation/defining_service_listeners_1489649_11.html, and that you named the session listener class, MySessionListener.

import net.rim.blackberry.api.bbm.platform.*;
import net.rim.blackberry.api.bbm.platform.service.*;
import net.rim.device.api.ui.component.*;

public class MyBBMScreen extends MainScreen
{
    public MyBBMScreen(BBMPlatformContext platformContext)
    {
        MessagingService messagingService = platformContext.getMessagingService();
       
        BBMPlatformSession mySession = messagingService.createSession(new MySessionListener());

        if (mySession != null) 
        {
            channel.sendInvitation("Lets play a game", "Poker App", null, 0);

            BBMPlatformContactList contacts = channel.getContactList();

            String myMsg = "Test data";
            BBMPlatformData data = new BBMPlatformData("Message", myMsg.getBytes(), 0);

            mySession.sendData(data, contacts);
        }
    }
}