Indoona Open Platform Messages - Version 0.9.5

The indoona open platform can send messages to an Application via the endpoint defined at App Creation stage.

Messages are delivered via HTTP(S) protocol: each request is a

POST request with Content-Type=application/x-www-form-urlencoded
and the following parameters:

  • data: a JSON string representing the message;
  • signature_method: the signature algorithm used by the indoona platform to trust the message, according to the method specified at App Creation stage;
  • signature: the signature generated by the indoona platform to trust the message.

All JSON messages have a common structure:


	{
		"id" 		:	"< message unique identifier as string >",
		"type"		:	"< message type as string >",
		"timestamp"	:	"< message timestamp in milliseconds since January 1, 1970 as string >",
		"sender"	:	"< sender resource in the format @, as string >",
		"room"		: 	"< optional group chat unique identifier as string, present only if the sending resource is a group chat >,"
		"owner"		: 	"< owner of the sending resource in the format @, as string >,"
		"recipient"	: 	"< contact representing the message recipient in the format @, as string >"
		"data"		: 	"< custom data depending on the message type, as a JSON object>"
	}

Message list

For the sake of brevity, in this section all possible messages from the indoona platform to an Application are presented and explained through proper examples. For address book contact message format and allowed mime-type in media messages, see API Reference.

Basic messages

Text message


	{
		"id" 		:	"21kj3h12oh3o",
		"type"		:	"text",
		"timestamp" :	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient"	:	"333@appdomain",
		"data"		: 	{
						"body"	:	"the message text"
					}
	}

Sticker message


	{
		"id" 		:	"21kj3h12oh3o",
		"type"		:	"sticker",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"id"	:	"kuma_08.png",
						"uri"	:	"https://media.m.indoona.com/stickers/kuma_08.png"
					}
	}

Location message


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"location",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		: 	{
    						"lat"		:	39.2307765,
			    			"lon"		:	9.073707199999944,
    						"description"	:	"Cagliari"
					}
	}

Address book contact message


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"contact",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		: 	{
    						"vcard"		:	"JohnDoe+393388312302"
					}
	}

Picture message


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"picture",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"id":"2284029_23498s234d72938479823_2893889",
						"type": "picture",
						"file": {
							"uri": "https://media.m.indoona.com/xmsg/2284029_23498s234d72938479823_2893889_o.jpg",
							"width": 1280,
							"height" : 800,
							"mime_type": "image/jpeg",
							"size": 1710480
						},
						"preview": {		// if available
							"uri": "https://media.m.indoona.com/xmsg/2284029_23498s234d72938479823_2893889_p.jpg",
							"width": 256,
							"height" : 160,
							"mime_type": "image/jpeg",
							"size": 3412
						}
					}
	}

Movie message


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"movie",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"id":"9284029_23498s234d72938479823_2893749",
						"type": "movie",
						"file": {
							"uri": "https://media.m.indoona.com/xmsg/9284029_23498s234d72938479823_2893749_o.mov",
							"width": 640,
							"height" : 340,
							"mime_type": "video/quicktime",
							"size": 10380980,
							"duration": 23
						},
						"preview": { 		// if available
							"uri": "https://media.m.indoona.com/xmsg/9284029_23498s234d72938479823_2893749_p.jpg",
							"width": 256,
							"height" : 180,
							"mime_type": "image/jpeg",
							"size": 3809
						}
					}
	}

Audio message

An audio message can be either of type "sound" or "voice": messages of the former type must be intended as audio notes (and should be rendered accordingly), while messages of the latter type represent generic audio files.


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"sound", (or "voice")
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"id":"3384029_23498s234d72938479823_2893755",
						"type": "sound", (or "voice")
						"file": {
							"uri": "https://media.m.indoona.com/xmsg/3384029_23498s234d72938479823_2893755_o.mp3",
							"mime_type": "audio/mp3",
							"size": 780980,
							"duration": 40
						}
					}

	}

File message


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"file",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"id":"1084029_23498s234d72938479823_2893700",
						"type": "file"
						"file": {
							"uri": "https://media.m.indoona.com/xmsg/1084029_23498s234d72938479823_2893700_o.pdf",
							"mime_type": "application/pdf",
							"size": 6680980
						}
					}

	}

Group event messages

This is a set of special messages intended to notify an Application of group-related events which involve (even indirectly) a contact.

Group-invite message

This message notifies the contact "333@appdomain" that it’s been invited by the connected user "aewd558asta9c4sot4fkfj34l@indoona" to the group "dcsurakhg9x4a1rlqxjuawazq".


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-invite",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"subject" : "My group",
						"avatar": "http://myavatar.com/my-group-avatar.jpg",
						"occupants": [
							{"id"	:	"aewd558asta9c4sot4fkfj34l@indoona"},
							{"id"	:	"333@appdomain"},
							{"id"	:	"15@anotherappdomain"}
						],
						"policy": "open"
        				}
	}

Group-bye message

This message notifies the contact "333@appdomain" that it has left the group "dcsurakhg9x4a1rlqxjuawazq" (e.g. due to its owner leaving the group too).


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-bye",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain"
	}

Group-join message

This message notifies the contact "333@appdomain" that the indoona user "1i7qr9t0dxc0kiw8u4fmzx69f@indoona" has been invited to the group "dcsurakhg9x4a1rlqxjuawazq" by the user “aewd558asta9c4sot4fkfj34l@indoona”.


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-join",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"new_user": {"id": "1i7qr9t0dxc0kiw8u4fmzx69f@indoona"},
						"subject" : "My group",
						"avatar": "http://myavatar.com/my-group-avatar.jpg",
						"occupants": [
							{"id"	:	"1i7qr9t0dxc0kiw8u4fmzx69f@indoona"},
							{"id"	:	"aewd558asta9c4sot4fkfj34l@indoona"},
							{"id"	:	"333@appdomain"},
							{"id"	:	"15@anotherappdomain"}
						],
						"policy": "open"
        				}
	}

Group-leave message

This message notifies the contact "333@appdomain" that the indoona user "1i7qr9t0dxc0kiw8u4fmzx69f@indoona" has left the group "dcsurakhg9x4a1rlqxjuawazq".


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-leave",
		"timestamp"	:	"1434613275796",
		"sender"	:	"1i7qr9t0dxc0kiw8u4fmzx69f@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"subject" : "My group",
						"avatar": "http://myavatar.com/my-group-avatar.jpg",
						"occupants": [
							{"id"	:	"aewd558asta9c4sot4fkfj34l@indoona"},
							{"id"	:	"333@appdomain"},
							{"id"	:	"15@anotherappdomain"}
						],
						"policy": "open"
        				}
	}

Group-kick message

This message notifies the contact "333@appdomain" that the indoona user "1i7qr9t0dxc0kiw8u4fmzx69f@indoona" has been kicked out from the group "dcsurakhg9x4a1rlqxjuawazq" by the indoona user "aewd558asta9c4sot4fkfj34l@indoona".


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-kick",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"kicked_user" : {"id": "1i7qr9t0dxc0kiw8u4fmzx69f@indoona"},
						"subject" : "My group",
						"avatar": "http://myavatar.com/my-group-avatar.jpg",
						"occupants": [
							{"id"	:	"aewd558asta9c4sot4fkfj34l@indoona"},
							{"id"	:	"333@appdomain"},
							{"id"	:	"15@anotherappdomain"}
						],
						"policy": "open"
        				}
	}

Group-subject message

This message notifies the contact "333@appdomain" that the indoona user "1i7qr9t0dxc0kiw8u4fmzx69f@indoona" has changed the subject of the group "dcsurakhg9x4a1rlqxjuawazq" to "My group renamed".


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-subject",
		"timestamp"	:	"1434613275796",
		"sender"	:	"1i7qr9t0dxc0kiw8u4fmzx69f@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"subject" : "My group renamed",
						"avatar": "http://myavatar.com/my-group-avatar.jpg",
						"occupants": [
							{"id"	:	"aewd558asta9c4sot4fkfj34l@indoona"},
							{"id"	:	"333@appdomain"},
							{"id"	:	"15@anotherappdomain"}
						],
						"policy": "open"
        				}
	}

Group-avatar message

This message notifies the contact "333@appdomain" that the indoona user "1i7qr9t0dxc0kiw8u4fmzx69f@indoona" has changed the avatar url of the group "dcsurakhg9x4a1rlqxjuawazq" to "http://my-new-avatar.com/my-group-avatar.jpg".


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-avatar",
		"timestamp"	:	"1434613275796",
		"sender"	:	"1i7qr9t0dxc0kiw8u4fmzx69f@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"subject" : "My group renamed",
						"avatar": "http://my-new-avatar.com/my-group-avatar.jpg",
						"occupants": [
							{"id"	:	"aewd558asta9c4sot4fkfj34l@indoona"},
							{"id"	:	"333@appdomain"},
							{"id"	:	"15@anotherappdomain"}
						],
						"policy": "open"
        				}
	}

Group-setting message

This message notifies the contact "333@appdomain" that the indoona user "1i7qr9t0dxc0kiw8u4fmzx69f@indoona" has changed the policy of the group "dcsurakhg9x4a1rlqxjuawazq" to "closed".


	{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-setting",
		"timestamp"	:	"1434613275796",
		"sender"	:	"1i7qr9t0dxc0kiw8u4fmzx69f@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient	:	"333@appdomain",
		"data"		:	{
						"subject" : "My group renamed",
						"avatar": "http://my-new-avatar.com/my-group-avatar.jpg",
						"occupants": [
							{"id"	:	"aewd558asta9c4sot4fkfj34l@indoona"},
							{"id"	:	"333@appdomain"},
							{"id"	:	"15@anotherappdomain"}
						],
						"policy": "closed"
        				}
	}

Control messages

This is a set of special messages addressed to the application, to notify it of events about connected users or the application itself.

User disconnection message

This message notifies the application that the indoona user "aewd558asta9c4sot4fkfj34l@indoona" has been disconnected.


	{
		"id"		:	"21kj3h12oh3o",
		"type"		: 	"control",
		"timestamp"	:	"1434613275796",
		"user_id"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"data"		:	{
							"action"	:	"disconnect"
						}
	}

Message signature

For an Application to trust integrity and source identity of incoming messages, the indoona platform signs all outgoing packets with a proper signature method, according to the what specified at App Creation stage. Available methods are based respectively on MD5 digest and CRC32 checksum.

MD5-based signature

The signature of a packet is generated by pre-pending the app’s client secret to the packet itself as an UTF8 string. Then, the MD5 digest of the obtained string is computed and converted to a hexadecimal string.

CRC32-based signature

The signature of a packet is generated by pre-pending the app’s client secret to the packet itself as an UTF8 string. Then, the CRC32 checksum of the obtained string is computed and the obtained long integer is converted to a hexadecimal string (through its byte array representation).