Skip to content

Latest commit

 

History

History
376 lines (243 loc) · 20.1 KB

VIBER_CUSTOM_MESSAGES.md

File metadata and controls

376 lines (243 loc) · 20.1 KB

Viber Custom Messages and Message Templates

In this guide:

  1. Intro
  2. Text messages
  3. Custom Keyboard
  4. Photo messages
  5. Video messages
  6. File messages
  7. Contact messages
  8. Location messages
  9. URL messages
  10. Sticker messages
  11. Sending multiple messages
  12. Handling errors

Intro

Viber Template Message builder allows you to generate more complex messages for Viber without writing JSON files manually.

To use it, just require viberTemplate function from Claudia Bot Builder:

const viberTemplate = require('claudia-bot-builder').viberTemplate;

viberTemplate exports an object that contains multiple classes that allows you to generate different types of structured messages for Viber:

  • Text messages (we need a template for this just in case you want to add custom keyboard to it)
  • Photo
  • Video
  • File
  • Contact
  • Location
  • Url
  • Sticker

More info about each type of structured messages can be found in the official documentation.

Text messages

If you simply want to answer with the text you can just return text. But in case you want to answer with text with a custom keyboard you should use Text method.

API

Text (class) - Class that allows you to build text messages with custom keyboard.

Arguments:

  • text, string (required) - a simple text to send as a reply.

Methods

Method Required Arguments Returns Description
addReplyKeyboard No isDefaultHeight (boolean, optional, is keyboard default height, default is true),

backgroundColor (string, optional, keyboard background color)		 this for chaining Adds a custom keyboard
addKeyboardButton No text (string, required, button text),

buttonValue (string, required, url or text value that will be returned on press),

columnSize (number, optional, a width of the button),

rowSize (number, optional, a height of the button),

buttonObj (object, optional, additional button settings, should be a valid values from Viber Keyboard docs)		 this for chaining Viber button on a keyboard, more info is available here
get Yes No arguments Formatted JSON to pass as a reply Get method is required and it returns a formatted JSON that is ready to be passed as a response to Viber

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    new viberTemplate.Text(`What's your favorite House in Game Of Thrones`)
      .addReplyKeyboard()
        .addKeyboardButton('Stark', 'STARK', 6, 1)
        .addKeyboardButton('Lannister', 'LANNISTER', 6, 1)
        .addKeyboardButton('Targaryen', 'TARGARYEN', 6, 1)
        .addKeyboardButton('None of the above', 'OTHER', 6, 1)
      .get();
});

Custom Keyboards

Each of the methods below has 2 methods for adding custom keyboards and buttons.

Following methods are allowed:

  • addReplyKeyboard
  • addKeyboardButton - only when keyboard is added, otherwise it'll throw an error

If you add multiple keyboards only the last one will be active

Photo messages

Photo attachment allows you to send images.

API

Photo (class) - Class that allows you to build a photo messages with optional custom keyboards.

Arguments:

  • photo, string (required) - an url or an ID of already uploaded image.
  • caption, string (optional) - a caption for an image, default is an empty string ('')

Methods

Method Required Arguments Returns Description
addReplyKeyboard No isDefaultHeight (boolean, optional, is keyboard default height, default is true),

backgroundColor (string, optional, keyboard background color)		 this for chaining Adds a custom keyboard
addKeyboardButton No text (string, required, button text),

buttonValue (string, required, url or text value that will be returned on press),

columnSize (number, optional, a width of the button),

rowSize (number, optional, a height of the button),

buttonObj (object, optional, additional button settings, should be a valid values from Viber Keyboard docs)		 this for chaining Viber button on a keyboard, more info is available here
get Yes No arguments Formatted JSON to pass as a reply Get method is required and it returns a formatted JSON that is ready to be passed as a response to Viber

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    return new viberTemplate.Photo('https://claudiajs.com/assets/claudiajs.png').get();
});

Video messages

Video message allows you to send videos.

API

Video (class) - Class that allows you to build a video messages with optional custom keyboards.

Arguments:

  • media, string (required) - an url of a video.
  • size, number (required) - a size of the video in bytes.
  • duration, integer (optional) - an optional duration of a video file.

Methods

Method Required Arguments Returns Description
addReplyKeyboard No isDefaultHeight (boolean, optional, is keyboard default height, default is true),

backgroundColor (string, optional, keyboard background color)		 this for chaining Adds a custom keyboard
addKeyboardButton No text (string, required, button text),

buttonValue (string, required, url or text value that will be returned on press),

columnSize (number, optional, a width of the button),

rowSize (number, optional, a height of the button),

buttonObj (object, optional, additional button settings, should be a valid values from Viber Keyboard docs)		 this for chaining Viber button on a keyboard, more info is available here
get Yes No arguments Formatted JSON to pass as a reply Get method is required and it returns a formatted JSON that is ready to be passed as a response to Viber

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    return new viberTemplate.Video('http://example.com/videos/video.mp4', 1024).get();
});

File messages

File messages allows you to send files with optional custom keyboard. Multiple file formats can be sent, but there's a list of forbidden formats in Viber documentation.

API

File (class) - Class that allows you to build a file messages with optional custom keyboards.

Arguments:

  • media, string (required) - an url of a file.
  • size, number (required) - file size in bytes.
  • filename, string (required) - a name of the file

Methods

Method Required Arguments Returns Description
addReplyKeyboard No isDefaultHeight (boolean, optional, is keyboard default height, default is true),

backgroundColor (string, optional, keyboard background color)		 this for chaining Adds a custom keyboard
addKeyboardButton No text (string, required, button text),

buttonValue (string, required, url or text value that will be returned on press),

columnSize (number, optional, a width of the button),

rowSize (number, optional, a height of the button),

buttonObj (object, optional, additional button settings, should be a valid values from Viber Keyboard docs)		 this for chaining Viber button on a keyboard, more info is available here
get Yes No arguments Formatted JSON to pass as a reply Get method is required and it returns a formatted JSON that is ready to be passed as a response to Viber

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    return new viberTemplate.File('http://example.com/files/file.pdf', 1024, 'Random file').get();
});

Contact messages

Contact messages allows you to send a contact info.

API

Contact (class) - Class that allows you to build a contact messages with optional custom keyboards.

Arguments:

  • name, string (required) - contact name.
  • phoneNumber, string (required) - contact phone number.

Methods

Method Required Arguments Returns Description
addReplyKeyboard No isDefaultHeight (boolean, optional, is keyboard default height, default is true),

backgroundColor (string, optional, keyboard background color)		 this for chaining Adds a custom keyboard
addKeyboardButton No text (string, required, button text),

buttonValue (string, required, url or text value that will be returned on press),

columnSize (number, optional, a width of the button),

rowSize (number, optional, a height of the button),

buttonObj (object, optional, additional button settings, should be a valid values from Viber Keyboard docs)		 this for chaining Viber button on a keyboard, more info is available here
get Yes No arguments Formatted JSON to pass as a reply Get method is required and it returns a formatted JSON that is ready to be passed as a response to Viber

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    return new viberTemplate.Contact('Alex', '+972511123123').get();
});

Location messages

Location template allows you to send a location.

API

Location (class) - Class that allows you to build a location messages with optional custom keyboards.

Arguments:

  • latitude, number (required) - location latitude.
  • longitude, number (required) - location longitude.

Methods

Method Required Arguments Returns Description
addReplyKeyboard No isDefaultHeight (boolean, optional, is keyboard default height, default is true),

backgroundColor (string, optional, keyboard background color)		 this for chaining Adds a custom keyboard
addKeyboardButton No text (string, required, button text),

buttonValue (string, required, url or text value that will be returned on press),

columnSize (number, optional, a width of the button),

rowSize (number, optional, a height of the button),

buttonObj (object, optional, additional button settings, should be a valid values from Viber Keyboard docs)		 this for chaining Viber button on a keyboard, more info is available here
get Yes No arguments Formatted JSON to pass as a reply Get method is required and it returns a formatted JSON that is ready to be passed as a response to Viber

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    return new viberTemplate.Location(44.831115, 20.421277).get();
});

URL messages

URL template allows you to send a link.

API

Url (class) - Class that allows you to build a link messages with optional custom keyboards.

Arguments:

  • url, string (required) - valid URL.

Methods

Method Required Arguments Returns Description
addReplyKeyboard No isDefaultHeight (boolean, optional, is keyboard default height, default is true),

backgroundColor (string, optional, keyboard background color)		 this for chaining Adds a custom keyboard
addKeyboardButton No text (string, required, button text),

buttonValue (string, required, url or text value that will be returned on press),

columnSize (number, optional, a width of the button),

rowSize (number, optional, a height of the button),

buttonObj (object, optional, additional button settings, should be a valid values from Viber Keyboard docs)		 this for chaining Viber button on a keyboard, more info is available here
get Yes No arguments Formatted JSON to pass as a reply Get method is required and it returns a formatted JSON that is ready to be passed as a response to Viber

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    return new viberTemplate.Url('https://claudiajs.com').get();
});

Sticker messages

Sticker template allows you to send a Viber sticker.

API

Sticker (class) - Class that allows you to build a sticker messages with optional custom keyboards.

Arguments:

Methods

Method Required Arguments Returns Description
addReplyKeyboard No isDefaultHeight (boolean, optional, is keyboard default height, default is true),

backgroundColor (string, optional, keyboard background color)		 this for chaining Adds a custom keyboard
addKeyboardButton No text (string, required, button text),

buttonValue (string, required, url or text value that will be returned on press),

columnSize (number, optional, a width of the button),

rowSize (number, optional, a height of the button),

buttonObj (object, optional, additional button settings, should be a valid values from Viber Keyboard docs)		 this for chaining Viber button on a keyboard, more info is available here
get Yes No arguments Formatted JSON to pass as a reply Get method is required and it returns a formatted JSON that is ready to be passed as a response to Viber

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    return new viberTemplate.Sticker(40126).get();
});

Sending multiple messages

It's easy to send multiple messages, just pass an array with at least one of the methods mentioned above. You can combine them how ever you want.

Example

const botBuilder = require('claudia-bot-builder');
const viberTemplate = botBuilder.viberTemplate;

module.exports = botBuilder(message => {
  if (message.type === 'viber')
    return [
      'Hello!',
      new viberTemplate.Text(`What's your favorite House in Game Of Thrones`)
        .addReplyKeyboard()
          .addKeyboardButton('Stark', 'STARK', 6, 1)
          .addKeyboardButton('Lannister', 'LANNISTER', 6, 1)
          .addKeyboardButton('Targaryen', 'TARGARYEN', 6, 1)
          .addKeyboardButton('None of the above', 'OTHER', 6, 1)
        .get()
    ];
});

Handling errors

Viber Template Message Builder checks if messages you are generating are following Viber Messenger guidelines and limits, in case they are not an error will be thrown.

Example:

Calling new viberTemplate.Text() without text will throw Text is required for the Viber Text template error.

All errors that Claudia bot builder's viberTemplate library is throwing can be found in the source code.

Errors will be logged in Cloud Watch log for your bot.