From Message.schema.yaml (ratatoskr/Message.schema)
---
$id: https://skeleton.botmd.io/ratatoskr/Message.schema
$schema: http://json-schema.org/draft-07/schema#
title: Message
description: >-
This is the schema for messages as described and proposed in the [Ratatoskr: Data Models for Messages RFC](https://gitlab.com/fivehealth/engineering/-/blob/master/rfcs/0019-message-data-models.md).
type: object
additionalProperties: false
required: [type, message]
_type: &type_title_description
title: Type
description: The type of this element.
#end _type
properties:
type:
<<: *type_title_description
const: message
message:
title: Message
description: Message element metadata.
anyOf:
- $ref: "#/definitions/text_types/Text Types"
- $ref: "#/definitions/media_types/Media Types"
- $ref: "#/definitions/action_types/Action Types"
- $ref: "#/definitions/quick_reply_types/Quick Reply Types"
- $ref: "#/definitions/location_types/Location Types"
- $ref: "#/definitions/container_types/Container Types"
- $ref: "#/definitions/Carousel"
- $ref: "#/definitions/Application Payload"
- $ref: "#/definitions/Email"
- $ref: "#/definitions/WhatsApp Template"
- $ref: "#/definitions/Empty Message"
#end anyOf
#end message
favorite:
$ref: "#/definitions/metadatas/Favorite"
provider_metadata:
$ref: "MessageProviderMetadata.schema"
reply_to:
$ref: "ReplyTo.schema"
#end properties
definitions:
text_types:
Text Types:
anyOf:
- $ref: "#/definitions/text_types/Title"
- $ref: "#/definitions/text_types/Subtitle"
- $ref: "#/definitions/text_types/Text"
#end Text Types
Title:
title: Title
description: Title primitive element.
type: object
additionalProperties: false
required: [type, title]
properties:
type:
<<: *type_title_description
const: title
#end type
title:
$ref: "#/definitions/metadatas/Title"
#end properties
#end Title
Subtitle:
title: Subtitle
description: Subtitle primitive element.
type: object
additionalProperties: false
required: [type, subtitle]
properties:
type:
<<: *type_title_description
const: subtitle
#end type
subtitle:
$ref: "#/definitions/metadatas/Subtitle"
#end properties
#end Subtitle
Text:
title: Text
description: Text primitive element.
type: object
additionalProperties: false
required: [type, text]
properties:
type:
<<: *type_title_description
const: text
#end type
text:
$ref: "#/definitions/metadatas/Text"
#end properties
#end Text
#end text_types
media_types:
Media Types:
anyOf:
- $ref: "#/definitions/media_types/Image"
- $ref: "#/definitions/media_types/Audio"
- $ref: "#/definitions/media_types/Video"
- $ref: "#/definitions/media_types/Attachment"
#end Media Types
Image:
title: Image
description: Image primitive element.
type: object
additionalProperties: false
required: [type, image]
properties:
type:
<<: *type_title_description
const: image
#end type
image:
$ref: "#/definitions/metadatas/Image"
#end properties
#end Image
Audio:
title: Audio
description: Audio primitive element.
type: object
additionalProperties: false
required: [type, audio]
properties:
type:
<<: *type_title_description
const: audio
#end type
audio:
$ref: "#/definitions/metadatas/Audio"
#end properties
#end Audio
Video:
title: Video
description: Video primitive element.
type: object
additionalProperties: false
required: [type, video]
properties:
type:
<<: *type_title_description
const: video
#end type
video:
$ref: "#/definitions/metadatas/Video"
#end properties
#end Video
Attachment:
title: Attachment
description: Attachment primitive element.
type: object
additionalProperties: false
required: [type, attachment]
properties:
type:
<<: *type_title_description
const: attachment
#end type
attachment:
$ref: "#/definitions/metadatas/Attachment"
#end properties
#end Attachment
#end media_types
action_types:
Action Types:
anyOf:
- $ref: "#/definitions/action_types/Button"
#end Action Types
Button:
title: Button
description: Button action primitive element.
type: object
additionalProperties: false
required: [type, button]
properties:
type:
<<: *type_title_description
const: button
#end type
button:
$ref: "#/definitions/metadatas/Button"
#end properties
#end Button
#end action_types
quick_reply_types:
Quick Reply Types:
anyOf:
- $ref: "#/definitions/quick_reply_types/Quick Reply"
#end Quick Reply Types
Quick Reply:
title: Quick Reply
description: Quick reply primitive element.
type: object
additionalProperties: false
required: [type, quick_reply]
properties:
type:
<<: *type_title_description
const: quick_reply
#end type
quick_reply:
$ref: "#/definitions/metadatas/Quick Reply"
#end properties
#end Quick Reply
#end quick_reply_types
location_types:
Location Types:
anyOf:
- $ref: "#/definitions/location_types/Location Request"
- $ref: "#/definitions/location_types/Location Response"
#end Location Types
Location Request:
title: Location Request
description: Location request primitive element.
type: object
additionalProperties: false
required: [type, location_request]
properties:
type:
<<: *type_title_description
const: location_request
#end type
location_request:
$ref: "#/definitions/metadatas/Location Request"
#end properties
#end Location Request
Location Response:
title: Location Response
description: Location request primitive element.
type: object
additionalProperties: false
required: [type, location_response]
properties:
type:
<<: *type_title_description
const: location_response
#end type
location_response:
$ref: "#/definitions/metadatas/Location Response"
#end properties
#end Location Response
#end location_types
container_types:
Container Types:
title: Container Types
description: Container types wrap around other primitive types.
anyOf:
- $ref: "#/definitions/container_types/Quick Replies"
- $ref: "#/definitions/container_types/Sections"
- $ref: "#/definitions/container_types/Paragraphs"
- $ref: "#/definitions/container_types/Actions"
#end Container Types
Carousel Container Types:
title: Carousel Container Types
description: Container types wrap around other primitive types. These types are used in carousels.
anyOf:
- $ref: "#/definitions/container_types/Sections"
- $ref: "#/definitions/container_types/Paragraphs"
- $ref: "#/definitions/container_types/Actions"
#end Container Types
Quick Replies:
title: Quick Replies
description: Quick replies container element.
type: object
additionalProperties: false
required: [type, quick_replies]
properties:
type:
<<: *type_title_description
const: quick_replies
quick_replies:
title: Quick Replies
description: Array of quick replys.
type: array
minItems: 1
maxItems: 16
items:
$ref: "#/definitions/quick_reply_types/Quick Reply"
#end quick_replies
#end properties
#end Quick Replies
Sections:
title: Sections
description: >-
Sections are container types for up to at most 3 elements.
These are most likely to be used for rich messages that include media, paragraphs, and actions.
type: object
additionalProperties: false
required: [type, sections]
properties:
type:
<<: *type_title_description
const: sections
#end type
sections:
title: Sections
description: An array of section elements.
type: array
minItems: 1
maxItems: 5 # allow more than 3 during definition (some elements will be hidden by UI after preprocessing eg. Image/Video/Audio)
items:
anyOf:
# Media Types
- $ref: "#/definitions/media_types/Audio"
- $ref: "#/definitions/media_types/Image"
- $ref: "#/definitions/media_types/Video"
- $ref: "#/definitions/media_types/Attachment"
- $ref: "#/definitions/container_types/Paragraphs"
- $ref: "#/definitions/container_types/Actions"
- $ref: "#/definitions/text_types/Text"
#end anyOf
#end items
#end sections
favorite:
$ref: "#/definitions/metadatas/Favorite"
#end properties
#end Sections
Actions:
title: Actions
description: Actions container element.
type: object
additionalProperties: false
required: [type, actions]
properties:
type:
<<: *type_title_description
const: actions
#end type
actions:
title: Actions
description: An array of action elements.
type: array
minItems: 1
maxItems: 8
items:
anyOf:
- $ref: "#/definitions/action_types/Button"
#end actions
favorite:
$ref: "#/definitions/metadatas/Favorite"
#end properties
#end Actions
Paragraphs:
title: Paragraphs
description: Paragraphs container element.
type: object
additionalProperties: false
required: [type, paragraphs]
properties:
type:
<<: *type_title_description
const: paragraphs
#end type
paragraphs:
title: Paragraphs
description: An array of paragraph elements.
type: array
minItems: 1
maxItems: 3
items:
anyOf:
- $ref: "#/definitions/text_types/Title"
- $ref: "#/definitions/text_types/Subtitle"
- $ref: "#/definitions/text_types/Text"
#end paragraphs
favorite:
$ref: "#/definitions/metadatas/Favorite"
#end properties
#end Paragraphs
#end container_types
Carousel:
title: Carousel
description: Carousel container element.
type: object
additionalProperties: false
required: [type, carousel]
properties:
type:
<<: *type_title_description
const: carousel
carousel:
title: Carousel
description: Carousel element metadata.
type: array
minItems: 1
maxItems: 10
items:
anyOf:
- $ref: "#/definitions/container_types/Carousel Container Types"
- $ref: "#/definitions/media_types/Media Types"
- $ref: "#/definitions/text_types/Text Types"
- $ref: "#/definitions/action_types/Action Types"
#end items
#end carousel
#end properties
#end Carousel
Application Payload:
title: Application Payload
description: Application payload message.
type: object
additionalProperties: false
required: [type, application_payload]
properties:
type:
<<: *type_title_description
const: application_payload
application_payload:
title: Application Payload Metadata
description: Application payload element metadata.
type: object
additionalProperties: false
required: [application]
properties:
application:
title: Application
description: Application origin of the data payload
type: string
minLength: 1
#end application
payload:
title: Payload
description: Arbitrary payload to be used by application. Can be any JSON object.
type: [object, string]
required: []
additionalProperties: true
#end payload
#end properties
#end application_payload
#end properties
#end Application Payload
Email:
title: Email
description: This is a high level representation of [MIME emails](https://docs.python.org/3/library/email.html).
type: object
additionalProperties: false
required: [type, email]
properties:
type:
<<: *type_title_description
const: email
#end type
email:
title: Email Metadata
description: Email element metadata.
type: object
required: [subject, text]
properties:
subject:
title: Subject
description: A short string identifying the topic of the message ([RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822#section-3.6.5)).
type: string
minLength: 1
text:
title: Text
description: The main body of the email in plain text.
type: string
html:
title: HTML
description: The main body of the email in HTML.
type: string
minLength: 1
attachments:
title: Attachments
description: Attachments to the email.
type: array
minItems: 1
items:
$ref: "#/definitions/metadatas/Attachment"
#end properties
#end email
#end properties
#end Email
WhatsApp Template:
title: WhatsApp Template
description: A message type encapsulating the WhatsApp template syntax. It is currently used by [MessageBird](https://developers.messagebird.com/api/conversations/#whatsapp-api).
type: object
additionalProperties: false
required: [type, whatsapp_template]
properties:
type:
<<: *type_title_description
const: whatsapp_template
#end type
whatsapp_template:
$ref: "#/definitions/metadatas/WhatsApp Template"
#end properties
#end WhatsApp Template
Empty Message:
title: Empty Message
description: An empty message with no content whatsoever.
type: object
additionalProperties: false
required: [type]
properties:
type:
<<: *type_title_description
const: empty
#end type
empty:
type: object
additionalProperties: false
#end properties
#end Empty Message
metadatas:
Image:
title: Image Metadata
description: Image element metadata.
type: object
additionalProperties: true # so that we can union with other sub-schemas (eg. Jarvis uses a `hide` property)
required: [url]
properties:
url:
title: URL
description: URL to the image file.
minLength: 1
scale:
title: Scale
description: Overrides frontend's default image scaling algorithm.
enum: [center, center-crop, center-inside]
actionable:
title: Actionable
description: Action to take when clicking on the image (or preview image). Defaults to opening the image in viewer.
$ref: "#/definitions/metadatas/Actionable"
#end properties
#end Image
Audio:
title: Audio Metadata
description: Audio element metadata.
type: object
additionalProperties: true # so that we can union with other sub-schemas (eg. Jarvis uses a `hide` property)
required: [url]
properties:
url:
title: URL
description: URL to the audio file.
minLength: 1
preview_image:
title: Preview Image
description: Preview image of audio. Defaults to a generic audio icon.
$ref: "#/definitions/metadatas/Image"
#end properties
#end Audio
Video:
title: Video Metadata
description: Video element metadata.
type: object
additionalProperties: true # so that we can union with other sub-schemas (eg. Jarvis uses a `hide` property)
required: [url]
properties:
url:
title: URL
description: URL to the video file.
minLength: 1
preview_image:
title: Preview Image
description: Preview image of video. Defaults to first frame of video.
$ref: "#/definitions/metadatas/Image"
preview_autostart:
title: Preview Autostart
description: Whether to auto play video in preview view. Defaults to `false`.
type: boolean
#end properties
#end Video
Attachment:
title: Attachment Metadata
description: Attachment element metadata.
type: object
additionalProperties: false
required: [url]
properties:
url:
title: URL
description: URL to the attachment file.
type: string
pattern: '^((https|s3|gs|file)\:\/\/|\$)'
filename:
title: Filename
description: Filename for attachment. This is useful when the filename cannot be inferred from the URL.
type: string
minLength: 1
content_type:
title: Content Type
description: The MIME type of the attachment. This is guessed from the extension of the `filename` followed by the `url`. See [`scalpel.messages.url.ContentTypeMixin`](https://gitlab.com/fivehealth/hippocrates/-/blob/staging/hippocrates/scalpel/messages/url.py) for content type guessing logic.
type: string
minLength: 1
preview_image:
title: Preview Image
description: Preview image of attachment. Defaults to first frame of attachment.
$ref: "#/definitions/metadatas/Image"
einstein:
title: Einstein attachment metadata
description: Einstein-specific metadata for this attachment
type: object
properties:
document_uid:
title: Document UID
description: Einstein Document UID for attachment.
type: string
minLength: 1
#end Attachment
Location Request:
title: Location Request Metadata
description: Location request element metadata.
type: object
additionalProperties: false
required: [text]
properties:
text:
title: Text
description: Prompt for the user when requesting for location.
type: string
minLength: 1
#end properties
#end Location Request
Location Response:
title: Location Response Metadata
description: Location response element metadata.
type: object
additionalProperties: false
required: [latitude, longitude]
properties:
latitude:
title: Latitude
description: Location latitude.
type: number
longitude:
title: Longitude
description: Location longitude.
type: number
name:
title: Name
description: Name of the location.
type: string
minLength: 1
address:
title: Address
description: Human-readable address of the location.
type: string
minLength: 1
#end properties
#end Location Response
Title:
title: Title
description: Title content.
type: string
minLength: 1
#end Title
Subtitle:
title: Subtitle
description: Subtitle content.
type: string
minLength: 1
#end Subtitle
Text:
title: Text
description: Text content.
type: string
minLength: 1
#end Text
Button:
title: Button Metadata
description: Button action element metadata.
allOf:
- title: Visuals
description: Metadata to describe the visual aspect of a button.
type: object
additionalProperties: true # so that we can union with other sub-schemas
required: [text]
properties:
text:
title: Text
description: Display text.
type: string
minLength: 1
style:
title: Style
description: Button styling options. `cta` refers to call to action buttons that have a blue background, while `link` buttons have white background. Defaults to `link`.
enum: [cta, link]
#end properties
- $ref: "#/definitions/metadatas/Actionable"
#end Button
Actionable:
title: Actionable metadata
description: Metadata to describe actions that are taken when a UI element is triggered (e.g., tapped, clicked, etc).
type: object
additionalProperties: true
required: [url]
properties:
url:
title: URL
description: "URL to the link file. Could be application internal links too. Currently supported internal links are: `botmd://hospital/postMessage`, `botmd://hospital/emobot`, `botmd://hospital/gql`, and `botmd://hospital/jarvisQuery."
type: string
minLength: 1
external_browser:
title: External Browser
description: >-
Whether to open the `url` in an external browser instead of our own webview.
Defaults to `false`.
type: boolean
content_type:
title: Content Type
description: >-
The MIME type of the content at URL. This is guessed from the extension of the `url`. If it is a `http`/`https` URL and there are no file extensions, `text/html` is assumed.
This is useful to override the default app responsible for opening it.
See [`scalpel.messages.url.ContentTypeMixin`](https://gitlab.com/fivehealth/hippocrates/-/blob/staging/hippocrates/scalpel/messages/url.py) for content type guessing logic.
type: string
minLength: 1
event:
$ref: "#/definitions/metadatas/Event"
#end properties
#end Actionable
Event:
title: Event Metadata
description: Metadata to describe an event that can be posted to Shadowfax. This is usually part of an `Actionable`.
type: object
additionalProperties: false
required: [type]
properties:
type:
title: Type
description: Event type that will be posted to Shadowfax (i.e., `event_type`) when this action is taken.
type: string
minLength: 1
properties:
title: Properties
description: Optional event properties that will be posted to Shadowfax (i.e., `event_properties`) when this action is taken.
type: object
required: []
additionalProperties: true
#end properties
#end Event
Favorite:
title: Favorite metadata
description: When specified, the message / carousel item can be favorited on the frontend.
type: object
additionalProperties: false
required: [title, url]
properties:
title:
title: Title
description: Title to show in the favorites menu.
type: string
minLength: 1
url:
title: URL
description: URL to favorite item. This could be an internal `botmd://` link or an external link.
type: string
minLength: 1
expires_on:
title: Expires On
description: This is used with `botmd://hospital/jarvisQuery` links using `uid`s. If frontend decides to cache the content of this favorite message, it should be refreshed against the backend after the expiry.
type: string
format: date-time
#end properties
#end Favorite
Quick Reply:
title: Quick Reply Metadata
description: Quick reply element metadata.
allOf:
- title: Visuals
description: Metadata to describe the visual aspect of a quick reply.
type: object
additionalProperties: true # so that we can union with other sub-schemas
required: [text]
properties:
text:
title: Text
description: Display text.
type: string
minLength: 1
#end properties
- $ref: "#/definitions/metadatas/Actionable"
#end allOf
#end Quick Reply
WhatsApp Template:
title: WhatsApp Template
description: WhatsApp template element metadata.
type: object
additionalProperties: false
required: [template_name]
properties:
template_name:
title: Template Name
description: WhatsApp template name to use for this message.
type: string
minLength: 1
namespace:
title: Namespace
description: WhatsApp namespace associated with the WABA. Defaults to the provider settings `namespace`.
type: string
minLength: 1
fallback_text:
title: Fallback Text
description: For non-WhatsApp capable providers, it will be sent as a text message containing this string.
type: string
minLength: 1
language_code:
title: Language code
description: Language code of the template. Note that language `policy` of the template message will always be `deterministic`. Defaults to `en`.
type: string
minLength: 1
header_parameters:
title: Header Parameters
description: Array of parameters in header component of the template message. Applies to media templates only.
type: array
items:
type: object
required: [type]
additionalProperties: false
properties:
type:
title: Type
description: Type of header
enum: [image, document, video]
image:
title: Image
description: Image header.
type: object
required: [url]
properties:
url:
title: URL
description: URL to the image.
type: string
pattern: '^((https|s3|gs)\:\/\/|\$)'
#end properties
#end
video:
title: Video
description: Video header.
type: object
required: [url]
properties:
urls:
title: URL
description: URL to the videos.
type: string
pattern: '^((https|s3|gs)\:\/\/|\$)'
#end properties
#end image
document:
title: Document
description: Document attachment in media template.
type: object
required: [url]
properties:
url:
title: URL
description: URL to the document.
type: string
pattern: '^((https|s3|gs)\:\/\/|\$)'
caption:
title: Caption
description: Caption to accompany the document attachment.
type: string
minLength: 1
filename:
title: Filename
description: Filename of document attachment. If `caption` is not specified, `filename` will be used instead.
type: string
minLength: 1
#end properties
#end document
#end properties
#end items
#end header_parameters
body_parameters:
title: Body Parameters
description: Array of parameters in body component of the template message. Applies to both text and media templates.
type: array
items:
type: object
required: []
additionalProperties: false
properties:
type:
title: Type
description: Type of body.
enum: [text]
text:
title: Text
description: Text to use in body parameter.
type: string
default:
title: Default (Deprecated)
description: Text to use in body parameter.
type: string
#end properties
#end body_parameters
button_parameters:
title: Button Parameters
description: Array of parameters in button component of the template message. Note that dynamic CTA is a very new feature (as of 2021-09-24).
type: array
items:
type: object
additionalProperties: false
oneOf:
- required: [url]
- required: [text]
properties:
url:
title: URL
description: Either the full URI or path to use for CTA button. Note that only the path, query, and fragment will be used.
type: string
minLength: 1
text:
title: Text (Legacy)
description: Either the full URI or path to use for CTA button. Note that only the path, query, and fragment will be used.
type: string
minLength: 1
index:
title: Index
description: Position index of the button. You can have up to 3 buttons using index values of 0 to 2. Defaults to 0.
enum: [0, 1, 2]
#end properties
#end items
#end button_parameters
#end properties
#end WhatsApp Template
#end metadatas
#end definitions