package common.messagepath.v1

Get desktop application:
View/edit binary Protocol Buffers messages

AdaptiveCardAttachment defines the mechanism that allows bots to send an adaptive card message defined using Microsoft's Adaptive Cards framework (see http://adaptivecards.io). By using this framework, developers can define a card in JSON composed of images, text, buttons and more using Microsoft's schema. These card definitions can be used across multiple platforms. This attachment should be used by the client to determine how to render an adaptive card message.

Used in: CoreMessage

• oneof content

  This split between card_id and card_definition provides flexibility in how adaptive cards get implemented long-term. card_definition will be used for a simpler implementation of sending the JSON directly to the client, while card_id provides a way to work around size limitations if necessary for future features.

  • string card_id = 1

    The ID of the adaptive card definition stored on the bots platform. The client will use this ID to retrieve the JSON definition of the card from the bots platform and then render it.

  • string card_definition = 2

    The dump of the JSON adaptive card definition.

AttributionAttachment is used to define the entity the content should be attributed to. Attribution information is typically displayed below content messages and represents the source of the content.

Used in: LinkMessageAttachment

• string name = 1

  The name of the source

• optional PictureElement icon = 2

  The icon representing the source

CarouselItem defines a single piece of content in a carousel.

Used in: CarouselMessageAttachment

• oneof item

  The option to send either message_id or content provides flexibility in how carousels get implemented. `content` provides the ability for the client to immediately render the content of an item, while message_id provides a way to work around XMPP size limitations if needed. message_id is the ID of a XMPP message stanza that should render as another card in the carousel.

  • XiUuid message_id = 1

  • CarouselItemContent content = 2

Used in: CarouselItem

• optional KeyboardAttachment keyboard_attachment = 30

  Each carousel item can have its own keyboard attachment.

• oneof type

  In the event the client encounters a carousel item type that is newer than its protobuf definition, no `type` will be parseable from the CarouselItemContent that arrives. In this scenario, clients should show the user a carousel item element that indicates this type is not known.

  • LinkMessageAttachment link_message_attachment = 31

CarouselMessageAttachment defines the properties required to render a carousel message sent by a bot. A carousel message contains multiple pieces of content that can be scrolled through horizontally.

Used in: CoreMessage

• repeated CarouselItem items = 1

ChatThemeAttachment defines any updates about chat themes. If this attachment is sent, then the client can assume that the chat theme has changed.

Used in: CoreMessage

• optional entity.v1.ChatThemeElement new_chat_theme = 1

• optional entity.v1.ChatThemeLockElement new_chat_theme_lock = 2

ContentLayoutElement defines which content layout the client should use to render a content message.

Used in: LinkMessageAttachment

• ContentLayoutElement.ContentLayoutType type = 1

Used in: ContentLayoutElement

• DEFAULT = 0

• ARTICLE = 1

• PHOTO = 2

• VIDEO = 3

---------------------------------------------------------------------------------------------- Base attributes 1-499 ----------------------------------------------------------------------------------------------

• optional CarouselMessageAttachment carousel_message_attachment = 515

  ---------------------------------------------------------------------------------------------- Main mutually exclusive attachments 500-999 ----------------------------------------------------------------------------------------------

• optional VisibilityRulesAttachment visibility_rules_attachment = 1000

  This attachment is used to override the clients default rules for where to display the message and how to send push (among other things) - see comments on the message definition for more info. This attachment may ONLY be set on server generated messages and messages from bots. It is NOT valid for native clients to send messages with this attachment.

• optional MentionReplyAttachment mention_reply_attachment = 1002

  For mention replies (from bots to users), this attachment is used to indicate the user who originally mentioned the bot. This should only be used the client for internal logic specific to mention-reply messages (e.g. on iPhone 10.9 it is used to determine whether to show the "Reply" button) DO NOT use this attachment to determine visibility rules (use the visibility_rules_attachment for that). This attachment may ONLY be sent by bots. It is NOT valid for native clients to send messages with this attachment.

• optional KeyboardAttachment keyboard_attachment = 1003

  The keyboard attachment is sent by the Bots Platform in order for clients to update their keyboard display. This attachment may not be included in the event that no change in user keyboard is desired from a message. Historically, this property was known as "Suggested Responses", but in the interest of flexibility, and future-compatibility, it was generalized to a field that implies changing a user's input mechanism, rather than only suggesting responses. This attachment may ONLY be set by bots. It is NOT valid for native clients to send messages with this attachment.

• optional KeyboardReplyAttachment keyboard_reply_attachment = 1004

  The keyboard reply attachment is sent by clients in order to identify when a user has used the input mechanism that was provided by a bot-provided keyboard attachment. This attachment may ONLY be set by clients. It is NOT valid for bots to send messages with this attachment.

• optional WidgetAttachment widget_attachment = 1005

  The widget attachment is sent by the Bots Platform in order for clients to update their widget display. This attachment may not be included in the event that no change in conversation widgets is desired from a message. This attachment may ONLY be set by bots. It is NOT valid for native clients to send messages with this attachment.

• optional AdaptiveCardAttachment adaptive_card_attachment = 1006

  For adaptive card messages (from bots to users), this attachment is used to indicate how an adaptive card message should be rendered. This should be used by the client to retrieve the appropriate JSON card definition(s) then render the message. This attachment may ONLY be set by bots. It is NOT valid for native clients to send messages with this attachment.

• optional TextMarkdownAttachment text_markdown_attachment = 1007

  For text messages (from bots to users), this attachment is used by the clients to render markdown text. This attachment may ONLY be set by bots. It is NOT valid for native clients to send messages with this attachment.

• optional ChatThemeAttachment chat_theme_attachment = 1008

  This attachment will be sent with status messages to notify clients about updated chat theme information. This attachment may ONLY be set on the server side. It is NOT valid for native clients to send messages with this attachment.

• optional TransactionDetailsAttachment transaction_details_attachment = 1009

  This attachment will be sent with status messages to notify clients about updated chat theme information. This attachment may ONLY be set on the server side. It is NOT valid for native clients to send messages with this attachment.

• repeated CoreMessageOriginRestriction.Origin deny = 1

  The list of origins which are not allowed to use the particular attachment when sending messages

Used in: CoreMessageOriginRestriction

• MOBILE = 0

  Native mobile clients connecting over XMPP

• BOT = 1

  Bot platform bots sending messages over the WebMessagingBridge (As of Oct 2016)

Reply specific for responses created from friend picker suggested responses.

Used in: SuggestedReply

• repeated XiBareUserJid picked = 1

Container for a friend picker suggested response All fields optional. Fields that are not given values have defaults defined by the API and/or clients, depending on where these defaults are expected to live. Clients will implement sensible default values, and the Bots API will be able to override them as necessary. See: https://docs.google.com/document/d/1v4JtP1fdah5cvgXW2apScf_bemMkrvh_J370X5jJD48/edit And: https://dev.kik.com/#/docs/messaging#friend-picker-response-object

Used in: SuggestedResponseItem

• string body = 1

• int32 min = 2

  Minimum number of users that can be selected in the friend picker shown on clients. Must be less than or equal to the max.

• int32 max = 3

  Maximum number of users that can be selected in the friend picker shown on clients. Must be greater than or equal to the min.

• repeated XiBareUserJid preselected = 4

  List of jids of users that have been chosen to be selected before the user provides any input. If a user that is selected is not on the receiving user's roster, that user will not be selected. If a user that is selected does not have the sending user in their roster, the resulting message will be dropped, as described by the `VisiblityRulesAttachment` that must come with messages that are sent as a result of `FriendPickedResponse`.

A single keyboard defines how a client should render the input space on their screen.

Used in: KeyboardAttachment, TextWidget

• optional XiBareUserJid to = 1

  The user that will receive this particular instance of the keyboard. In the event that this field is omitted, this keyboard should be sent to all users that will receive the message containing this keyboard. TODO: To be removed after switching all consumers to to_v2

• optional v1.XiBareUserJidOrAliasJid to_v2 = 3

  to_v2 will replace non-versioned. The to can be userJid or an aliased jid

• bool hidden = 2

  Determines whether or not this keyboard will be shown to the user first. If true, show the user the system default keyboard with the option to toggle to this keyboard. If false, this keyboard should be shown first, with the option to toggle back to the system keyboard.

• oneof type

  • SuggestedResponseKeyboard suggested_response_keyboard = 32

KeyboardAttachment defines the mechanism that allow bots to alter the behavior of keyboards on a user's device. Specifying a Keyboard allows a bot to give the user more information about what kinds of responses they expect from the user at that point in time. Up to 51 of these may be present in a single message to be delivered. The case where this can occur is in the case of a bot responding to a mention in a group containing 50 individuals, and also having a default. If a client receives multiple keyboards in this list. The first one should be taken as the correct one to display. In the future, clients may support multiple keyboards being received. See: https://docs.google.com/document/d/18C33WPHg9v-Yaot1eMeR8bonllo5qbL0oR0pC3ZjDPs/edit And: https://docs.google.com/document/d/11WF4MeW55z1bPkBQwoDlQ1-kT0pQz_or4FWXBZgf2PY/edit And: https://dev.kik.com/#/docs/messaging#keyboards

Used in: CarouselItemContent, CoreMessage

• repeated Keyboard keyboards = 1

Generic container for any kind of reply that's made using a custom keyboard. Each keyboard should define its own reply message type that is sent in the event of a reply directly from interacting with that keyboard.

Used in: CoreMessage

• oneof type

  • SuggestedReply suggested_reply = 1

LinkMessageAttachment defines the information required to render a link message sent by a bot.

Used in: CarouselItemContent

• repeated UriElement uris = 1

  Clients handle up to 10 URIs in a message. The URI of lowest priority is typically set as a fallback page for old versions of iOS and Android that do not support the Kik browser.

• string title = 50

  The title of the link message.

• string text = 51

  The text of the link message.

• optional PictureElement picture = 52

  The picture to display in the link message.

• optional AttributionAttachment attribution = 53

  Describes the entity the link should be attributed to.

• optional ContentLayoutElement content_layout = 54

  Dictates which content layout should be used for this message.

• bool allow_forward = 55

  Dictates if the link message can be forwarded to another conversation or not.

For mention replies (from bots to users), this attachment is used to indicate the user who originally mentioned the bot. See https://github.com/kikinteractive/kik-product/wiki/Bot-Mentions This should only be used the client for internal logic specific to mention-reply messages (e.g. on iPhone 10.9 it is used to determine whether to show the "Reply" button) DO NOT use this attachment to determine visibility rules (use the visibility_rules_attachment for that).

Used in: CoreMessage

• optional XiBareUserJid original_mentioner = 1

  The original user who mentioned the bot. Field is OPTIONAL but should be set when the mentioner is known. TODO: To be removed after switching all consumers to original_mentioner_v2

• optional v1.XiBareUserJidOrAliasJid original_mentioner_v2 = 2

  Version 2 will replace non-versioned. The original_mentioner_v2 can be userJid or an aliased jid

The reply process of Payments uses a mechanism that exists off the standard message path. This message type is provided for the event that this process is consolidated into the standard message path. Fields may be added in the future, but as of Sept 2016, there is nothing that needs to be specifically forwarded on for payment suggested replies. The presence of this field is not required if replying using a payment suggested response.

Used in: SuggestedReply

(message has no fields)

Container for a payment suggested response. Private, and undocumented suggested response type. Only used internally for demoing purposes (as of Sept 2016). The Bots Platform uses the Stripe API for payment functionality. See: https://github.com/kikinteractive/kik-product/wiki/Payments-API-Docs And: https://stripe.com/docs/api

Used in: SuggestedResponseItem

• string description = 1

• int32 amount = 2

• string currency = 3

  ISO 4217 currency code, must be three characters.

• optional XiUuid transaction_id = 4

  Random UUID4 assigned to each payment suggested response by the Bots Platform in order to identify individual transactions.

• optional PaymentSuggestedResponse.SavedCard saved_card = 5

  This message will not be present if the user who is receiving this suggested response does not have a saved payment method.

Container for a saved payment method.

Used in: PaymentSuggestedResponse

• string last_4_digits = 1

  The last 4 digits of a user's saved card, must be 4 digits.

• string brand = 2

  The brand of the user's saved card. In order to validate credit card numbers, the client needs the brand as well in addition to the last 4 digits. See http://www.freeformatter.com/credit-card-number-generator-validator.html for more information. See for https://stripe.com/docs/api#card_object-brand Stripe's supported brands

PictureElement is used to define a picture sent in a message

Used in: AttributionAttachment, LinkMessageAttachment

• string url = 1

  The URL of the full-sized image

Reply specific for picture suggested responses.

Used in: SuggestedReply

• optional XiUuid pic_id = 5

  The original pic ID as was sent in the picture suggested response that the user actioned upon.

Container for a picture suggested response. See: https://docs.google.com/document/d/1dzZHfT99cD0356C7i7VR6WDyTH6DlSF98eu_pgqEHGo/edit

Used in: SuggestedResponseItem

• string thumbnail_url = 1

  The contents of this URL will be what appear in the client's picture suggested response rendering. This thumbnail will have been generated and hosted by the Bots Platform from the content provided by the bot.

• string pic_url = 3

  The URL of the full size image that will be made available to clients after sending the image as a response to the bot.

• optional XiUuid pic_id = 5

  Created by the Bots Platform, and may be used to uniquely identify images.

The entity that is returned to the Bot Platform when a user has selected a response that was provided in a bot-supplied suggested response keyboard.

Used in: KeyboardReplyAttachment

• string metadata = 1

  Metadata field as provided, verbatim, from the the suggested response item that was provided to the client.

• oneof type

  • TextSuggestedReply text_reply = 32

  • PaymentSuggestedReply payment_reply = 33

  • FriendPickerSuggestedReply friend_picker_reply = 34

  • PictureSuggestedReply picture_reply = 35

A suggested response item represents a single item within a possible list of options for a SuggestedResponseKeyboard.

Used in: SuggestedResponseKeyboard

• string metadata = 1

  Metadata is provided by bots, and must be returned back to the Bot Platform upon users selecting this instance of response. This metadata should be attached to a SuggestedReplyItem when being passed back to the bots platform. Metadata should not be inspected or interpreted by clients.

• oneof type

  In the event the client encounters a suggested response type that they have never seen before (i.e. their protobuf definitions predate the development of a suggested response type), no `type` will be parseable from the SuggestedResponseItem that arrives. In this scenario, clients are expected to show the user a suggested response element indicating that this type is not known by the client.

  • TextSuggestedResponse text_response = 32

  • PaymentSuggestedResponse payment_response = 33

  • FriendPickerSuggestedResponse friend_picker_response = 34

  • PictureSuggestedResponse picture_response = 35

SuggestedResponseKeyboards allow bots to provide an ordered list of options that a user can select from in order to respond to the conversation. See: https://dev.kik.com/#/docs/messaging#suggested-response-keyboard

Used in: Keyboard

• repeated SuggestedResponseItem responses = 1

  The Bots Platform may apply additional validation against ordering of values provided in this list.

TextMarkdownAttachment defines the mechanism that allows bots to send a text message containing text with markdown. This attachment should be used by the client to render text with markdown.

Used in: CoreMessage

• string markdown = 1

Empty object that exists solely for the purpose of parity with the SuggestedResponseItem definition. Fields may be added in the future, but as of Sept 2016, there is nothing that needs to be specifically forwarded on for text suggested replies. The presence of this field is not required if replying using a text suggested response.

Used in: SuggestedReply

(message has no fields)

Container for a text message suggested response. See: https://dev.kik.com/#/docs/messaging#text-response-object

Used in: SuggestedResponseItem

• string body = 1

TextWidget allow bots to provide text to be shown at the top of the conversation window.

Used in: Widget

• string body = 1

• string title = 2

• optional Keyboard keyboard = 3

  You can attach a Keyboard to a TextWidget, which specifies the keyboard to be shown when a reply button is pressed on the widget The `to` field of this Keyboard is ignored and overrided by the `to` field of the widget

TransactionDetailsAttachment is meant to be attached to status messages related to feature payments It contains the intended target of the status message

Used in: CoreMessage

• TransactionDetailsAttachment.Target target = 1

Used in: TransactionDetailsAttachment

• UNKNOWN = 0

• SENDER = 1

• RECIPIENT = 2

UriElement is used to describe a URI sent in a message

Used in: LinkMessageAttachment

• string uri = 1

• UriElement.Platform platform = 100

  The platform this URI should be displayed on.

• uint32 priority = 1000

  Describes the priority of the URI (the lower the number the higher the priority)

Used in: UriElement

• ALL = 0

• WEB = 1

• IOS = 2

• ANDROID = 3

• WIDGET = 4

'Visibility' relates to: - Where the convo appears (new people/main chat) - How push is sent - What content is blurred - What profile pics are blurred - If bottom bar shows up This attachment represents a minimal set of overrides to the default rules the client applies.

Used in: CoreMessage

• optional XiBareUserJid initiator = 1

  The initiator is distinctly different from the sender of the message. It SHOULD NOT be set to the same value as the sender. The initiator can be a user or a bot. This field is OPTIONAL. TODO: To be removed after switching all consumers to initiator_v2

• optional v1.XiBareUserJidOrAliasJid initiator_v2 = 4

  Version 2 will replace non-versioned. The initiator can be userJid or an aliased jid

• bool drop_if_initiator_not_friend = 2

  'Friend' is defined as: (in roster AND not blocked) OR yourself Push should NEVER be sent if the initiator is not a friend. The server WILL NOT filter these messages, it is up to the receiving client to drop, but still ack (if necessary), the message. If the initiator is a friend, continue processing the other rules defined in this attachment. The initiator field SHOULD be set, if this field is true. If initiator is not set, this option is ignored. Initial usecase for this is viral invites for bots (https://docs.google.com/document/d/1v4JtP1fdah5cvgXW2apScf_bemMkrvh_J370X5jJD48). Message should be dropped by the client, not simply hidden (although acked through QoS as necessary).

• VisibilityRulesAttachment.Rule rule = 3

  If UKNOWN, use the default rule: USE_SENDER_FOR_VISIBILITY (ie: for forwards compatibility).

Used in: VisibilityRulesAttachment

• USE_SENDER_FOR_VISIBILITY = 0

  Use this rule if the current value is UNKNOWN (for forwards compatibility). Similar to the default client behaviour, use the sender for determining push and convo location. Respect the blocked status of the sender AND initiator: if either is blocked, DO NOT send push. Initial usecase for this is viral invites for bots (https://docs.google.com/document/d/1v4JtP1fdah5cvgXW2apScf_bemMkrvh_J370X5jJD48). Note that for the viral invites case, the sender should always be a bot.

• USE_INITIATOR_FOR_VISIBILITY = 1

  Convo location (new pople/main list) and push behavior should be based on the initiator (if present). Respect the blocked status of the sender AND initiator: if either is blocked, DO NOT send push. The initiator field SHOULD be set but if the initiator field is not set, use the sender for all visibility rules. Initial usecase for this is mention replies from bots to users (https://kikinteractive.atlassian.net/browse/SERVER-257)

Used in: WidgetAttachment

• optional XiBareUserJid to = 1

  The user that will receive this particular Widget instance. In the event that this field is omitted, this widget should be sent to all users that will receive the message containing this widget.

• oneof type

  • TextWidget text_widget = 32

WidgetAttachment defines the mechanism that allow bots to alter the behavior of dynamic content that supplements the chatbot experience. Specifying a Widget allows a bot to give the user additional information that provides more context to a conversation. TextWidget is an example of a widget that stays at the top of the screen, providing persistent information all users in a conversation. Up to 51 of these may be present in a single message to be delivered. The case where this can occur is in the case of a bot responding to a mention in a group containing 50 individuals, and also having a default. If a client receives multiple widgets in this list directed at a single user, the first one should be taken as the one to display. Support for displaying multiple widgets may be added in the future. See: https://docs.google.com/a/kik.com/document/d/1Y2tnA5KfCma0wmGoqnoqFKWTJZa-beU0mvU3v8A3UN0/edit

Used in: CoreMessage

• repeated Widget widgets = 1