Layer Messaging Experiences

Layer’s XDK provides a framework for building and rendering rich and interactive Messaging Experiences. Each message that is sent/received by an application built using Layer consists of a collection of Message Parts that have MIME Types that define what type of message it is.

This document describes the requirements for each Message Type that Layer ships with.

MIME Type Attributes and Message Part Trees

Messages have a collection of Message Parts. These Parts are assembled into a Tree on Clients using MIME Type Attributes.

Suppose we have the following three Message Parts:

  • Part 1: {"id": id1, "mime_type": "application/vnd.myco.main-text+json;role=root"}
  • Part 2: {"id": id2, "mime_type": "application/vnd.myco.alt-text+json;role=alt-text;parent-node-id=" + uuid(id1)}
  • Part 3: {"id": id3, "mime_type": "application/vnd.myco.custom-type+json;role=custom-type;parent-node-id=" + uuid(id1)}

These there Message Parts are sent to Laye as an Array; but:

  • parent-node-id: provides the UUID portion of the Message Part that is the parent node in the Message Part Tree
    • That means Part 2 and Part 3 are child nodes of Part 1
  • role: provides the meaning of that Child Node to its parent.
    • Roles of alt-text and custom-type, if they are understood by the parent (application/vnd.myco.main-text+json) can be used to enhance/complete the rendering of that Message
    • Role of root is reserved in the system to designate the Message Part that is the root of the Message Part tree

Note

Role of root is required for every Message

Why is it signifcant that we form a tree? Let us take the Carousel Message as an example:

  • Part 1: Declare this to be a Carousel using the role=root and the Carousel MIME Type:
    • ``{“id”: id0, “mime_type”: “application/vnd.layer.carousel+json;role=root”}`
  • Part 2: Carousel Item #1; has a parent-node-id to make it a child node of the Carousel, and a role to define it as a Carousel Item:
    • {"id": id1, "mime_type": "application/vnd.myco.main-text+json;role=carousel-item;parent-node-id=" + uuid(id0)}
  • Part 3: {"id": id2, "mime_type": "application/vnd.myco.alt-text+json;role=alt-text;parent-node-id=" + uuid(id1)}
  • Part 4: {"id": id3, "mime_type": "application/vnd.myco.custom-type+json;role=custom-type;parent-node-id=" + uuid(id1)}
  • Part 5: Carousel Item #2; has a parent-node-id to make it a child node of the Carousel, and a role to define it as a Carousel Item:
    • {"id": id1, "mime_type": "application/vnd.myco.main-text+json;role=carousel-item;parent-node-id=" + uuid(id0)}

This tree can have at most 32 nodes (i.e. at most 32 Message Parts), and can have whatever depth is needed to assemble the Message data to be rendered by clients.

Message Data

Message Parts in each Message consists of a mime_type describing the type of content (and containing any required attributes) and the body containing the content itself. The Root Message Part for any Message will contain a JSON body describing the Message.

Documentation that follows describes the fields that are optional and required in each type of message. The server does not validate these. Messages that lack these fields will be accepted by the server but may not render properly on clients.