Skip to main content

Message Data Model

The message data model represent a message sent from your bot to a subscribed user.
The bots API supports the following message types:

Message Size Limit

The maximum size of a message is 30KB.

Text Message

The text message data model represents a message that contains text only.
The JSON representation of a text message is as follows:

Text
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"text",
"text":"Hello world!"
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional Max 4000 characters
typestringThe message type.Required. Always text.
textstringThe message text.Required. Max 7000 characters.

Picture Message

The picture message data model represents a message that contains a picture.
The JSON representation of a picture message is as follows:

Picture
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"picture",
"text":"My picture",
"media":"http://media.example.com/picture.jpg",
"thumbnail":"http://media.example.com/picture_thumbnail.jpg"
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720.
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional. Max 4000 characters.
typestringThe message type.Required. Always picture.
textstringDescription of the picture.Required. Max 512 characters. Can be an empty string if irrelevant.
mediastringThe URL of the picture. Supported file formats include jpeg, png, and non-animated gif.Required. The URL must have a resource with a .jpeg, .png, or .gif file extension as the last path segment. For example, the URL should be in the format of http://www.example.com/path/image.jpeg. Please note that animated GIFs can be sent as either URL messages or file messages. Additionally, keep in mind that the maximum image size is 1MB on iOS and 3MB on Android.
thumbnailstringURL of a reduced size image to be used as a thumbnail. Supported file formats include jpeg, png, and non-animated gif.Optional. Recommended dimensions for the thumbnail are 4000x400. maxium image size 100KB.

Video Message

The video message data model represents a message that contains a video.
The JSON representation of a video message is as follows:

Video
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"video",
"media":"http://media.example.com/video.mp4",
"thumbnail":"http://media.example.com/video_thumbnail.jpg",
"size":3861139,
"duration": 10
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720.
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional. Max 4000 characters.
typestringThe message type.Required. Always video.
mediastringThe URL of the video. Supported file formats include mp4Required. The URL must have a resource with a .mp4 file extension as the last path segment. For example, the URL should be in the format of http://www.example.com/path/video.mp4.
thumbnailstringURL of a reduced size image to be used as a thumbnail. Supported file formats include jpeg onlyOptional. Recommended dimensions for the thumbnail are 4000x400. maxium image size 100KB.
sizeintegerThe size of the video in bytesRequired. Max size 26MB(27262976b)
durationintegerThe duration of the video in secondsOptional. Max duration 3 minutes(180s)

File Message

The file message data model represents a message that contains a file.
The JSON representation of a file message is as follows:

File
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"file",
"media":"http://media.example.com/file.pdf",
"size":3861139,
"file_name":"file.pdf"
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720.
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional. Max 4000 characters.
typestringThe message type.Required. Always file.
mediastringThe URL of the file.Required. The URL must end with a file extension as the last segment of the path. For instance, the URL should follow this format: http://www.example.com/path/file.pdf. Please note that certain file types are not supported. For a comprehensive list of forbidden file formats, please refer to the forbidden file formats section below
sizeintegerThe size of the file in bytesRequired. Max size 50MB(52428800b)
file_namestringThe name of the fileRequired. Should include the file extension. The maximum length of the file name, including the extension, is 256 characters. Sending a file without an extension or with an incorrect extension could result in the client being unable to open the file. It's essential to ensure that the file name follows the correct naming convention to avoid any issues

Forbidden File Formats

The following file formats are not supported:

  • Windows: .bat, .bin, .cmd, .com, .cpl, .exe, .gadget, .inf1, .ins, .inx, .isu, .job, .jse, .lnk, .msc, .msi, .msp, .mst, .paf, .pif, .ps1, .reg, .rgs, .sct, .shb, .shs, .u3p, .vb, .vbe, .vbs, .vbscript, .ws, .wsf
  • Mac OS: .action, .app, .bin, .command, .csh, .osx, .workflow
  • Linux: .bin, .csh, .ksh, .out, .run
  • Android: .apk
  • iOS: .ipa

Contact Message

The contact message data model represents a message that contains a contact information.
The JSON representation of a contact message is as follows:

Contact
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"contact",
"contact":{
"name":"John Doe",
"phone_number":"+972501234567"
}
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720.
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional. Max 4000 characters.
typestringThe message type.Required. Always contact.
contact.namestringThe name of the contactRequired. Max 28 characters.
contact.phone_numberstringThe phone number of the contactRequired. Max 18 characters. The phone number should contain the country code and should only include numbers. For example, a valid American phone number could be formatted as follows: +15555555555, where +1 is the country code for the United States. Including any characters other than numbers in the phone number field can result in errors or failure to send messages. Please ensure that the phone number follows the correct formatting guidelines to avoid any issues.

Location Message

The location message data model represents a message that contains the user's location.
The JSON representation of a location message is as follows:

Location
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"location",
"location":{
"lat":32.0853,
"lon":34.7818
}
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720.
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional. Max 4000 characters.
typestringThe message type.Required. Always location.
location.latfloatThe latitude of the location.Required.
location.lonfloatThe longitude of the location.Required.

URL Message

The URL message data model represents a message that contains a URL.
The JSON representation of a contact message is as follows:

URL
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"url",
"media":"http://www.example.com"
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720.
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional. Max 4000 characters.
typestringThe message type.Required. Always url.
mediastringThe URL to open.Required. Max 2000 characters

Sticker Message

The sticker message data model represents a message that contains a sticker.
The JSON representation of a sticker message is as follows:

Sticker
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"sticker",
"sticker_id":"40129"
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720.
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional. Max 4000 characters.
typestringThe message type.Required. Always sticker.
sticker_idstringThe sticker ID.Required.

Rich Media Message

The Rich Media message enables the sending of messages with predefined layouts,
including height (number of rows), width (number of columns), text, images, and buttons.

As an example, the Carousel Content Message allows a user to scroll through a list of
items, each composed of an image, description, and call-to-action button.

Each item on the list shown to the user is called a "card," and each card has its own
grid layout, which can have a maximum of 7 rows and a maximum of 6 columns.
You can send a minimum of one card and a maximum of six cards.
Cards are fully customizable, and you can learn more on how to design your cards in the
Designing Rich Media Message Card section below.

Pay Attention

The following restrictions apply to the Rich Media message:

  • The Rich Media message is supported only on Viber version 6.7 and above.
  • The Rich Media message cannot be forwarded.

The JSON representation of a Rich Media message is as follows:

Rich
{
"receiver":"jc9HsWTZ2Yf2NkRZ8KcNug==",
"min_api_version":1,
"sender":{
"name":"My Awesome Bote",
"avatar":"http://avatar.example.com"
},
"tracking_data":"tracking data",
"type":"rich_media",
"rich_media":{
"Type":"rich_media",
"ButtonsGroupColumns":6,
"ButtonsGroupRows":7,
"BgColor":"#FFFFFF",
"Buttons":[
{
"Columns":6,
"Rows":3,
"ActionType":"open-url",
"ActionBody":"https://www.google.com",
"Image":"http://html-test:8080/myweb/guy/assets/imageRMsmall2.png"
},
{
"Columns":6,
"Rows":2,
"Text":"<font color=#323232><b>Headphones with Microphone, On-ear Wired earphones</b></font><font color=#777777><br>Sound Intone </font><font color=#6fc133>$17.99</font>",
"ActionType":"open-url",
"ActionBody":"https://www.google.com",
"TextSize":"medium",
"TextVAlign":"middle",
"TextHAlign":"left"
},
{
"Columns":6,
"Rows":1,
"ActionType":"reply",
"ActionBody":"https://www.google.com",
"Text":"<font color=#ffffff>Buy</font>",
"TextSize":"large",
"TextVAlign":"middle",
"TextHAlign":"middle",
"Image":"https://s14.postimg.org/4mmt4rw1t/Button.png"
},
{
"Columns":6,
"Rows":1,
"ActionType":"reply",
"ActionBody":"https://www.google.com",
"Text":"<font color=#8367db>MORE DETAILS</font>",
"TextSize":"small",
"TextVAlign":"middle",
"TextHAlign":"middle"
},
{
"Columns":6,
"Rows":3,
"ActionType":"open-url",
"ActionBody":"https://www.google.com",
"Image":"https://s16.postimg.org/wi8jx20wl/image_RMsmall2.png"
},
{
"Columns":6,
"Rows":2,
"Text":"<font color=#323232><b>Hanes Men's Humor Graphic T-Shirt</b></font><font color=#777777><br>Hanes</font><font color=#6fc133>$10.99</font>",
"ActionType":"open-url",
"ActionBody":"https://www.google.com",
"TextSize":"medium",
"TextVAlign":"middle",
"TextHAlign":"left"
},
{
"Columns":6,
"Rows":1,
"ActionType":"reply",
"ActionBody":"https://www.google.com",
"Text":"<font color=#ffffff>Buy</font>",
"TextSize":"large",
"TextVAlign":"middle",
"TextHAlign":"middle",
"Image":"https://s14.postimg.org/4mmt4rw1t/Button.png"
},
{
"Columns":6,
"Rows":1,
"ActionType":"reply",
"ActionBody":"https://www.google.com",
"Text":"<font color=#8367db>MORE DETAILS</font>",
"TextSize":"small",
"TextVAlign":"middle",
"TextHAlign":"middle"
}
]
}
}
FieldTypeDescriptionNotes
receiverstringThe unique ID of the subscriber to send the message to.Required.
min_api_versionintegerThe minimum API version required by clients to receive this message
(default 1).
Optional. It is important to note that the client version must support the API version specified. If the version number is set below the required version for certain features, those features may not work as expected.
sender.namestringThe name of the bot.Required. Max 28 characters.
sender.avatarstringThe URL of the bot's avatar.Optional. the avatar size should not exceed 100KB. The recommended dimensions for the avatar are 720x720.
tracking_datastringAllow the bot to track messages and user’s replies. The tracking_data value sent with the message will be returned with the user's reply.Optional. Max 4000 characters.
typestringThe message type.Required. Always rich_media.
rich_media.TypestringThe type of the rich media message.Required. Always rich_media.
rich_media.ButtonsGroupColumnsintegerThe number of columns in the grid of each card.Required. The number of columns must be between 1 and 6.
rich_media.ButtonsGroupRowsintegerThe number of rows in the grid of each card.Required. The number of rows must be between 1 and 7.
rich_media.BgColorstringThe background color of the card.Required. The color must be in hexadecimal format.
rich_media.ButtonsarrayThe list of cards.Required. The list must contain between 1 and 6 cards. A new card starts when the sum of rows reaches the number of rows defined in the rich_media.ButtonsGroupRows.

Desiging Cards

The following table shows the properties of a card:

FieldTypeDescriptionNotesDefault
ColumnsintegerThe number of columns the card occupies.Optional. The number of columns must be between 1 and 6.6
RowsintegerThe number of rows the card occupies.Optional. The number of rows must be between 1 and 7.1
BgColorstringThe background color of the card.Optional. The color must be in hexadecimal format.Default Viber button color
SilentbooleanIf set to true, the user action will not be displayed in the conversation.Optional. Supported only on Viber 6.7 and abovefalse
BgMediaTypestringThe type of the background media.Optional. The value can be picture or gif. For picture jped and png file formats are supportedpicture
BgMediastringThe URL of the background media.Optional. The media size should not exceed 500KB.
BgMediaScaleTypestringThe scale type of the background media.Optional.You can choose from the following options: crop: scales the contents to fill the view with a fixed aspect ratio, which may result in some portions of the content being clipped. fill: scales the contents to fill the view without maintaining a fixed aspect ratio. fit: ensures that at least one axis (either X or Y) fits exactly while maintaining the aspect ratio of the content.
ImageScaleTypestringThe scale type of the image.Optional. You can choose from the following options: crop: scales the contents to fill the view with a fixed aspect ratio, which may result in some portions of the content being clipped. fill: scales the contents to fill the view without maintaining a fixed aspect ratio. fit: ensures that at least one axis (either X or Y) fits exactly while maintaining the aspect ratio of the content.
BgLoopbooleanIf set to true, the background media will loop.Optional.true
ActionTypestringThe type of the action the card will perform when pressed.Optional. The value can be reply, open-url, location-picker, share-phone, buy or none. reply - will send a reply to the bot. open-url - will open the specified URL and send the URL as reply to the bot. Note: location-picker and share-phone are not supported on desktop, and require adding any text in the ActionBody parameter.reply
ActionBodystringThe body of the action.Required. Text for ActionType reply or none. Valid URL for ActionType open-url
ImagestringURL of image to place on top of the card backgroundOptional. This can be a partially transparent image that will allow some of the background to show through. The image will be placed using an aspect-fill logic. Supported format - png and jpeg. Max size 500Kb
TextstringText to display on top of the card backgroundOptional. You can use the following HTML tags in your text messages:: <b/>, <i/>, <u/>, <br/>, <s/>(from API v4). You can also control the font size by using the <font/> tag with the size attribute like this: <font size="12"></font>. Note that the minimum font size is 12 and the maximum size is 32. This feature is available on API v4 and above. Additionally, you can control the font color by using the <font/> tag with the colort attribute, like this: <font color="#7F00FF"></font>. The color must be specified in hexadecimal format. Please note that the maximum length of the text is 250 characters. If the text exceeds this limit, it will be cropped and presented as "...".
TextVAlignstringVertical alignment of the textOptional. The value can be top, middle or bottom.middle
TextHAlignstringHorizontal alignment of the textOptional. The value can be left, center or right.center
TextPaddingsarrayPadding of the textOptional. The array must contain 4 integers. The first value is the top padding, the second is the right padding, the third is the bottom padding and the fourth is the left padding. Values can be between 0 and 12. Supported on API v4 and above.[12, 12, 12, 12]
TextOpacityintegerOpacity of the textOptional. The value can be between 0 and 100.100
TextSizestringSize of the textOptional. The value can be small, regular or large.regular
OpenURLTypestringThe type of the URL to open.Optional. The value can be internal (the URL will be opened inside the app) or external (the URL will be opened in an external browser).internal
OpenURLMediaTypestringDetermines the URL media type.Optional. not-media - force browser usage. video - will be opened via media player. gif - client will play the gif in full screen mode. picture - client will open the picture in full screen modenot-media
TextBgGradientColorstringThe background gradient color of the text.Optional. The color must be in hexadecimal format. Works only if TextVAlign is set to top or bottom
TextShouldFitbooleanIf set to true, the text will be resized to fit the card.Optional. Supported on API v6 and above. Minimum font seize is 12ptfalse
InternalBrowserJSON Objectconfiguration for open-url action with internal typeOptional. Supported on API v3 and above.
InternalBrowswer.ActionButtonstrinAction button in internal’s browser navigation barOptional. Supported on API v3 and above. Types can be forward, send, open-externally, send-to-bot, none. forward - will open the forward via Viber screen and share current URL or predefined URL. send - sends the currently opened URL as an URL message, or predefined URL if property ActionPredefinedURL is not empty. open-externally - opens external browser with the current URL. send-to-bot - (api level 6) sends reply data in msgInfo to bot in order to receive message. none - will not display any buttonforward
InternalBrowswer.ActionPredefinedURLstringPredefined URL for action buttonOptional. Supported on API v3 and above.
InternalBrowser.TitleTypestringType of title for internal browser if has no CustomTitle fieldOptional. Supported on API v3 and above. Types can be default, domain. default means the content in the page’s <OG:title> element or in <title> tag. domain means the top level domaindefault
InternalBrowser.CustomTitlestringCustom title for internal browserOptional. Supported on API v3 and above. Max 15 characters
InternalBNrowser.ModestringIndicates that browser should be opened in a full screen or in partial size (50% of screen height). Full screen mode can be with orientation lock (both orientations supported, only landscape or only portrait)Optional. Supported on API v3 and above. Types can be fullscreen, fullscreen-portrait, fullscreen-landscape, partial-size. normal means the browser will be opened in a small window. fullscreen means the browser will be opened in full screen modefullscreen
InternalBrowser.FooterTypestringType of footer for internal browserOptional. Supported on API v3 and above. Types can be default, hidden. default means the content in the page’s <OG:description> element or in <meta name="description"> tag. hidden means the footer will be hiddendefault
InternalBrowser.ActionReplyDatastringData that will be sent to bot when user clicks on action buttonOptional. Supported on API v6 and above. Custom reply data for send-to-bot action that will be resent in msgInfo
MapJSON ObjectConfiguration for for open-map action with internal typeOptional. Supported on API v6 and above.
Map.LatitudefloatLatitude of the locationOptional. (format: “12.12345”)
Map.LongitudefloatLongitude of the locationOptional. (format: “3.12345”)
FrameJSON ObjectDraw frame above the background on the card, the size will be equal the size of the cardOptional. Supported on API v6 and above.
Frame.BorderWidthintegerWidth of the frame borderOptional. Supported on API v6 and above., Values between 0 and 101
Frame.BorderColorstringColor of the frame borderOptional. Supported on API v6 and above. The color must be in hexadecimal format.#000000
Frame.CornerRadiusintegerRadius of the frame cornersOptional. Supported on API v6 and above. Values between 0 and 100
MediaplayerJSON ObjectSpecifies media player optionsOptional. Supported on API v6 and above. Will be ignored if OpenURLMediaType is not video or audio
Mediaplayer.TitlestringTitle of the media playerOptional. Supported on API v6 and above.
Mediaplayer.SubtitlestringSubtitle of the media playerOptional. Supported on API v6 and above.
Mediaplayer.ThumbnailURLstringURL of the thumbnail imageOptional. Supported on API v6 and above.
Mediaplayer.LoopbooleanIf set to true, the video will be loopedOptional. Supported on API v6 and above.false