Payload Type Conventions

PubNub doesn't have a means of defining the type of message or object to send. However, in many use cases it makes sense to have descriptive, predefined messages to ensure that as your app grows and expands its functionality, you aren't limited by basic messaging structures.

Types of messages can include:

  • Text messaging
  • Text messaging with language translations embedded in the message.
  • Hosted image/file messages, where the file is static and the URL is referenced.
  • Video files that contain thumbnails and loading icons.
  • Polling and questionnaire messages where you also supply predefined answers.
  • Invitations to new channels for private or group chat.
  • Action messages for the app to do something for this user.
  • Session data linked to a third-party such as video service or streaming event.

Descriptive Message Types

Consider these three messages:

  • {payload: “Hello I am a Message"}
  • {payload: "https://cdn.app/your/image/here.png"}
  • {payload: "https://cdn.app/your/video/here.mp4"}

Because of the way these messages are constructed, you may run into a number of problems while trying to interpret their payloads in your app. Should you just scan for text? Should you check if every message starts with https? Should you look for .fileType at the end of each message?

You can make your app easier to expand upon by including file types and definitions into the message. Making the payloads more descriptive also makes it easier to interpret these messages later on.

Generic payloadDescriptive payload
{payload: “Hello I am a Message"}{type :"text", message:"Hello I am a Message"}
{payload: "https://cdn.app/your/image/here.png"}{type: "image", full:"https://cdn.app/your/image/here.png", thumbnail:" https://cdn.app/your/image/here_thumbnail.png"}
{payload: "https://cdn.app/your/video/here.mp4"}{type: "video", url:"https://cdn.app/your/video/here.mp4", thumbnail:"https://cdn.app/your/video/here_thumbnail.png"}

When your app receives these kinds of messages, it can process them differently displaying text, images and videos according to their respective types.

Future-proof message types

You can add fail-safe measures into your app. If you introduce new messaging types, older versions of your app can prompt users to upgrade to unlock the features the new message types provide.

Message types should be easy to read and extendable. As your app grows, you want to ensure that future releases don't break old versions.

Below is a list of message types that might be helpful to you:

Text

{
"content": {
"type": "text",
"message": "This is a message"
},
"sender": "Mathew.Jenkinson"
}

Multi-language Text

{
"content": {
"type": "text",
"message": {
"en": "This is a message",
"es": "Este es un mensaje",
"de": "Dies ist eine Nachricht",
"nl": "Dit is een bericht"
}
},
"sender": "Mathew.Jenkinson"
}

Text with Image

{
"content": {
"type": "text",
"text": "The weather is gorgeous today. Who's available to meet up for lunch at Bob’s Diner? 🌞",
"attachments": [
{
"type": "image",
"image": {
"source": "https://pubnub.github.io/react-chat-components/samples/clouds.jpg"
}
}
],
"sender": "Mathew.Jenkinson"
}
}

Image

{
"content": {
"type": "image",
"full": "https://my/full/image.png",
"thumbnail": "https://my/thumbnail/image.png"
},
"sender": "Mathew.Jenkinson"
}

Video

{
"content": {
"type": "image",
"url": "https://my/video/file.png",
"thumbnail": "https://my/video/image.png"
},
"sender": "Mathew.Jenkinson"
}

Typing Indicator

{
"content": {
"type": "action",
"event": "typing"
},
"sender": "Mathew.Jenkinson"
}

Chat Invitation

{
"content": {
"type": "chatInvite",
"channel": "this is the channel you are being invited too",
"message":"Hi Craig, welcome to the team!"
},
"sender": "Mathew.Jenkinson"
}

Video Invitation

{
"content": {
"type": "videoInvite",
"session": "your-token-here"
},
"sender": "Mathew.Jenkinson"
}

Poll

{
"content": {
"type": "poll",
"question": "What do people want for lunch?",
"answers": {
"pizza": 0,
"tacos": 0,
"sushi": 0
}
},
"sender": "Mathew.Jenkinson"
}