Messaging

Apps can send an invitation asking a user's friends if they'd like to play the app. The invitation comes from the logged in user, contains a link back to the app, and will be approved by the user before it is sent. The invitation is sent via the IMVU messaging system, showing up for the user on the IMVU website, mobile apps and desktop app...along with an email to the user.

In order to send an invitation from your app you must configure your application for this feature. First, turn on the Approved Access permission called Messaging that allows your app to send messages to a user's friends. This permission is configured on the developer page where you registered your app. Second, register an invitation URL for each platform that you wish to send an invitation. This invitation URL is the link that brings users back to your app to play it, for example https://apps.imvu.com/thehunt/eded8eaefe4a2ddc8dd88d487acdf238c8f6bb08/index.html). A separate Invite URL may be specified for each platform on which your app runs. Neglecting to configure this URL in your app settings will result in an invalid invite URL error.

Now that your app is configured you'll need to write some code to create an invitation. Sample code is available in the Messaging demo shipped with the IMVUnity source code. Here you will see that you first get the list of a user's friends, since you can only send a message to a user's friend. Once you let the user choose a friend that they want to send an invitation to you generate a unique token for each invitation. This token is any value you'd like, as it will be sent back to you as a parameter that is added to your Invitation URL. This token allows you to embed any data that helps your invitation retain needed application context. (For instance, if Mike invites Tim to join him in your game's multi-player lobby then this token might contain an ID for that lobby.) If you do not wish to use the token parameter, simply provide a random value. Each token consists of sixty-four (64) hexadecimal digits. This invite_token query parameter will be the only parameter your servers will receive when a message recipient clicks on the message's call-to-action link to join the game.

Messages may be sent to the UserModel of a player's friend. You can only send to 1 friend at a time. To get the UserModel, call the GetFriends() method on the player's UserModel object. This will return a FriendCollection, each item of which is a UserModel for one of the player's friends. Call the SendMessage() method, passing an invite token as discussed above as well as a default message. The default message will be pre-populated into the "personalized message" field when the player authorizes sending the message.

The call to SendMessage() will initiate a callout to the IMVU website, similar to the callout used in the IMVU connection process. In this callout the player can edit their personal messange and can confirm that he/she indeed wishes to send this message. Should the sender authorize the action, the recipient will immediately receive an IMVU message containing a call-to-action URL for your app, along with an optional personalized message from the sender.

The Promise returned from the SendMessage call will indicate whether sending the message succeeded or failed, but no data is returned on success.