Viber for Business

Our business messaging API supports sending and receiving Viber for Business messages.

Being able to send Viber messages requires requesting access via the Channels portal. Without onboarding with Viber via the portal, you can not make use of this part of the API. Please be aware that Viber needs to verify the legitimacy of your business and your rationale for usage.

Fact Sheet

Feature	Support	Remarks
delivery notification	yes	Occurs when your message is delivered to the Viber platform. Delivery notifications are sent to the status report webhooks.
text messages	yes	The maximum length of a message is 1000 characters. Text formatting like bold, italics, monospace and strikethrough text are supported (see below).
media	yes	Media URL attributes should end in the proper file extension. Only one media file is allowed per message; when sending multiple files, each file will be sent in its own message. When the linked media doesn't exist/can't be found, the message will not be sent at all.
media: images	yes	Maximum file size for an uploaded image is 200 MB. Supported formats: png, jpeg, jpg, gif.
media: audio	no
media: video	yes	Maximum file size for an uploaded video file is 200 MB. Maximum duration of the video can be up to 10 minutes. Supported formats: mp4. Server which host the video must include 'Content-Length' in response header.
media: document	yes	Maximum file size for an uploaded file is 200 MB. Supported formats: doc(x), xls(x), csv, pdf.
suggestion as button	yes	Only 1 button is possible
rich card	yes	Only 1 button is possible
templates	yes	Predefined OTP templates, configurable with own variables.
carousel	yes	Number of items from 2 to 5. Each item can have a image with expected formatspng, jpeg, jpg. Each item have two buttons ( one of them optional)

Sending messages

Viber is one of the few channels which uses telephone numbers as recipients. This allows SMS to be used as a fallback delivery channel if the recipient doesn't have the Viber app installed on their mobile device.

Please note that when defining fallback text, it is affected by the maximum size limitations of SMS as described in the section on SMS multipart messaging.

Text formatting

Viber allows the usage of formatting text following markdown guidelines:

Format	Markdown	Text to be sent	Message appearance
Bold	One asterisk at each end of the text: *	This text will be bold	This text will be bold
Italics	One underscore at each end of the text: _	_This text will be in italics_	This text will be in italics
Monospace	Three backticks at each end of the text: ```	```This text will be in monospace```	`This text will be in monospace`
Strikethrough	One tilde at each end of the text: ~	~This text will have a strikethrough~	~~This text will have a strikethrough~~

URL requirements

Viber enquires the following requirements that apply to using (image) URLs

Only use secured HTTPS links
Make sure that image URLs are not protected by a captcha
Make sure the image URLs include file extensions (.mp4, .png, .jpeg)
Links to one of the following apps are not allowed
- Facebook
- Instagram
- Line
- Signal
- Telegram
- WhatsApp

Text

The example below will send a simple text-only Viber message.

{
    "messages": {
        "msg": [
            {
                "from": "Your Sender",
                "to": [
                    {
                        "number": "Phone number recipient"
                    }
                ],
                "allowedChannels": [
                    "Viber"
                ],
                "body": {
                    "type": "auto",
                    "content": ""
                },
                "richContent": {
                    "conversation": [
                        {
                            "text": "Be part of it."
                        }
                    ]
                }
            }
        ]
    }
}

Media

The following media types are supported:

Media type	Supported formats	Mimetype	Supported size maximum
Image	png, jpeg, gif	image/png, image/jpeg, image/gif	200MB
Video	mp4	video/mp4	200MB
Document	doc(x), xls(x), csv, txt, pdf	application/msword, application/vnd.ms-excel, text/csv, text/plain, application/pdf	200MB

Direct message with text and image

In the example below we send a simple rich content message that contains both text and an image.

{
  "messages": {
    "msg": [
      {
        "from": "Your sender",
        "to": [
          {
            "number": "Phone number"
          }
        ],
        "allowedChannels": [
          "Viber", "SMS"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback Text"
        },
        "richContent": {
          "conversation": [
            {
              "text": "CM.com - Be part of it.",
              "media": {
                "mediaUri": "https://www.cm.com/cdn/cm/cm.png",
                "mimeType": "image/png",
                "mediaName": "cm.png"
              }
            }
          ]
        }
      }
    ]
  }
}

Direct message with text and video

In the example below we send a simple rich content message that contains both text and a video.

{
  "messages": {
    "msg": [
      {
        "from": "Your sender",
        "to": [
          {
            "number": "Phone number"
          }
        ],
        "allowedChannels": [
          "Viber", "SMS"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback Text"
        },
        "richContent": {
          "conversation": [
            {
              "text": "CM.com - Be part of it.",
              "media": {
                "mediaUri": "your-video-url.mp4",
                "mimeType": "video/mp4",
                "mediaName": "your-video.mp4"
              }
            }
          ]
        }
      }
    ]
  }
}

Direct message with document

In the example below we send a simple rich content message that contains a document.

{
  "messages": {
    "msg": [
      {
        "from": "Your sender",
        "to": [
          {
            "number": "Phone number"
          }
        ],
        "allowedChannels": [
          "Viber", "SMS"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback Text"
        },
        "richContent": {
          "conversation": [
            {
              "text": "CM.com - Be part of it.",
              "media": {
                "mediaUri": "your-document.pdf",
                "mimeType": "application/pdf",
                "mediaName": "your-document.pdf"
              }
            }
          ]
        }
      }
    ]
  }
}

Suggestion

Suggestions provide a way to present a button in your message the user can press to perform an action. Only 1 button per message is supported.

The following actions are supported by Viber as rich card buttons.

Action	Remarks
OpenURL	Maximum length of label is 30 characters, url required.
Dial	Maximum length of label is 30 characters, phone number required.

The following restrictions apply for a suggestion:

Field	Required	Remarks
label	Yes	Maximum length is 30 characters.
url	Only for OpenURL	Must be a valid URL
phoneNumber	Only for Dial	Must be a valid phone number

Message with open url action

In the example below, we send a simple rich content message that contains elements that Viber will display as an open URL action.

{
  "messages": {
    "msg": [
      {
        "from": "Your sender",
        "to": [
          {
            "number": "Phone number"
          }
        ],
        "allowedChannels": [
          "Viber", "SMS"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback Text"
        },
        "richContent": {
          "conversation": [
            {
              "text": "CM.com - Be part of it.",
              "suggestions": [
                {
                  "action": "OPENURL",
                  "label": "Visit CM.com",
                  "url": "https://www.cm.com/",
                  "postbackdata": "WEBSITE"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Message with dial action

In the example below, we send a simple rich content message that contains elements that Viber will display as an dial action.

{
  "messages": {
    "msg": [
      {
        "from": "Your sender",
        "to": [
          {
            "number": "Phone number"
          }
        ],
        "allowedChannels": [
          "Viber", "SMS"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback Text"
        },
        "richContent": {
          "conversation": [
            {
              "text": "CM.com - Be part of it.",
              "suggestions": [
                {
                  "action": "DIAL",
                  "label": "Call us",
                  "dial": {
                  	"phoneNumber": "0031612345678"
                  },
                  "postbackdata": "DIAL"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Rich card

Rich cards offer a way for you to offer a richer in-conversation experience than standard text messages by integrating buttons, images and more alongside text in a single message. Rich cards can be used for many purposes, such as displaying product information or asking the message recipient to choose from a pre-determined set of options.

The following restrictions apply for using a rich card:

Field	Required	Remarks
header	Yes	Displayed as the title. Maximum length is 30 characters.
text	No	Displayed as the subtitle. Maximum length is 900 characters.
mediaUri	No	The URL of the image to display.
suggestions	No	Suggestions as buttons. Maximum of 1 button per card.

The following actions are supported by Viber as rich card buttons.

Action	Remarks
OpenURL	Maximum length of label is 30 characters, url required.
Dial	Maximum length of label is 30 characters, phone number required.

In the example below we send a rich content message that contains rich card properties. The rich card is composed of a title, a subtitle, a media image and a suggestion.

{
  "messages": {
    "msg": [
      {
        "from": "Your sender",
        "to": [
          {
            "number": "Phone number"
          }
        ],
        "allowedChannels": [
          "Viber", "SMS"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback Text"
        },
        "richContent": {
          "conversation": [
            {
              "header": "We are CM.com!",
              "text": "Visit our website or start a chat with one of our employee's!",
              "media": {
                "mediaUri": "https://www.cm.com/cdn/cm/cm.png",
                "mimeType": "image/png",
                "mediaName": "cm.png"
              },
              "suggestions": [
                {
                  "action": "OPENURL",
                  "label": "Visit our website!",
                  "url": "https://www.cm.com",
                  "postbackdata": "WEBSITE"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Carousel

Carousel message offer a way for you to send a single message featuring text and multiple customizable sections (items), each showcasing different products or services along with dedicated media and call-to-action.

The following restrictions apply for using a rich card:

Field	Required	Remarks
text	Yes	Message text. Up to 1000 characters. Recommended length is 200 characters.
items	Yes	From 2 to 5 items.
items title	Yes	Item title text. From 2 to 38 characters.
mediaUri	Yes	The URL of the image to display. One per item.
suggestions	Yes	Maximum 2 suggestions per item. One of them optional.

The following actions are supported by Viber as rich card buttons.

Action	Remarks
OpenURL	Maximum length of label is 30 characters, url required.
Dial	Maximum length of label is 30 characters, phone number required.

The following restrictions apply for suggestions

Field	Required	Remarks
label	Yes	Maximum length is 10 characters. Optional suggestion maximum 12 characters.
url	Only for OpenURL	Must be a valid URL

In the example below we send a rich content message that contains a carousel with two items. Each item is composed of a title, a media image and a two suggestions.

{
  "messages": {
    "msg": [
      {
        "from": "Your sender",
        "to": [
          {
            "number": "Phone number"
          }
        ],
        "allowedChannels": [
          "Viber", "SMS"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback Text"
        },
        "richContent": {
          "conversation": [
              {
                 "carousel": {
                     "cardWidth": "Medium",
                     "cards": [
                        {
                           "header": "WhatsApp Business",
                           "text": "Start the conversation on WhatsApp",
                           "media": {
                                "mediaName": "WhatsApp",
                                "mediaUri": "https://i.imgur.com/JY2i6gc.png",
                                "mimeType": "image/png"
                            },
                            "suggestions": [
                              {
                                 "action": "OpenUrl",
                                 "label": "Buy",
                                 "url": "https://www.cm.com/register/",
                                 "postbackdata": "OpenUrl (WAB)"
                               },
                               {
                                 "action": "OpenUrl",
                                 "label": "Buy",
                                 "url": "https://www.cm.com/register/",
                                 "postbackdata": "OpenUrl (WAB)"
                                }
                               ]
                             },
                         {
                            "header": "CM.COM",
                            "text": "The tech behind Conversational Comme",
                            "media": {
                                "mediaName": "CM.com",
                                "mediaUri": "https://www.cm.com/cdn/web/hero/homepage-pink.png",
                                "mimeType": "image/png"
                             },
                             "suggestions": [
                                {
                                  "action": "OpenUrl",
                                  "label": "Buy",
                                  "url": "https://www.cm.com/register/",
                                  "postbackdata": "OpenUrl (WAB)"
                                 },
                                 {
                                   "action": "OpenUrl",
                                   "label": "Read more",
                                   "url": "https://www.cm.com/nl-nl/over-cm/",
                                   "postbackdata": "OpenUrl (CM)"
                                  }
                                ]
                           }
                      ]
            }
          ]
        }
      }
    ]
  }
}