API Manual

Complete API Manaual

BOT Java SDK

An easy to use library to create nandbox Bots

Code Examples

Some source code example for usefule bots.

How to create Bot

In few steps, you can configure and publish your new bots using an interactive menu.
 
NAME POSITION OFFICE AGE START DATE SALARY
Airi Satou Accountant Tokyo 33 2008/11/28 $162,700
Angelica Ramos Chief Executive Officer (CEO) London 47 2009/10/09 $1,200,000
Ashton Cox Junior Technical Author San Francisco 66 2009/01/12 $86,000
Bradley Greer Software Engineer London 41 2012/10/13 $132,000
Brenden Wagner Software Engineer San Francisco 28 2011/06/07 $206,850
Brielle Williamson Integration Specialist New York 61 2012/12/02 $372,000
Caesar Vance Pre-Sales Support New York 21 2011/12/12 $106,450
Cedric Kelly Senior Javascript Developer Edinburgh 22 2012/03/29 $433,060
Hazem Hazem Jazem
Charde Marshall Regional Director San Francisco 36 2008/10/16 $470,600

Introduction for developers

The Bot API allows you to easily create programs that interface with nandbox messaging platform.

What is Bot?

nandbox bots are special accounts created without a phone number that run as third party applications to provide extra functionality by interfacing to nandbox messaging platform. Users can interact with bots by sending them messages, and commands. You control your bots using Websocket messages to nandbox Bot API server.

How Bot works?

Users can interact with bots by sending messages and commands to bots through a direct chat or by adding them to groups. This is useful for example in chat bots or news bots. Messages, commands and requests sent by users are passed to the software running on your servers. Our intermediary server handles all encryption and communication with the nandbox API for you. You communicate with this server via a Websocket interface that offers a simplified version of the nandbox API (Bot API).

How do I create a bot?

Creating bots within nandbox is easy. In few steps, you can configure and publish your new bots using an interactive menu.

  • Use nandbox Android App version 2.1.0 or later.
  • From Settings menu open “Bot Manager”
  • Tap “+” to create a new bot
  
  • Enter your Bot title (Limited to 32 characters)
  • Choose your bot type
    – Choose “Business”, if your bot is associated or will be for use by organization, or business.
    – Choose “Individual” if bot will be for use by individual
  • Enter Bot Description: a short text of up to 120 characters, describing your bot. Users will see this text on the bot’s profile page and when they share your bot with someone, this text is sent together with the link. when they are about to join your bot.
  • Update your Bot Image.
  • Enter “About” section:
    a short text of up to 512 characters, describing your bot. Users will see this text at the beginning of the conversation with the bot.
  • Give your bot a unique handle by providing your business email.
    
Unlike others, we protect your business name from being reserved by others bots. Your bot unique handle will be matching your web domain name. For example, if your business domain name is XYZ.com your bot handle will be “xyz”.
After you reserve and book your bot handle, you can configure the following options:

  • Inline: toggle inline mode for your bot.
  • Private: Private Bot will not appear in Bot index search. Admin must send the Bot link to the user to invite him/her to join the bot.
  • Filter: select which messages your bot will receive when added to a group. Choose from “none”, “when mentioned”, “posts” or “All”.

Once you’ve created a bot, you can obtain the bot’s token by openning it and click “Get token” from overflow menu. The authorization token and Bot Server API link will be sent within the bot chat.

As the owner (creator) of the bot, you will have a chance to test the bot before publishing it. As soon as the bot is tested successfully, you can publish the bot by pressing “publish” button. Within 24 hours, the bot will be published and available for bot public search index.

It is important to know that any change in the bot information will result the bot being unpublished, and the owner must publish his/her bot again to make it available for public search index.

Bot Search

nandbox app users will be able to search bots title, description and username and join them. It is recommended for owners to use keywords within the title, description and handle to better represent their bot functionality for better exposure.
                                                                                                                                

Hazem

JSON Example:

   {
       "method": "message", 
       "message": { 
                      "date": 1512445910180, 
                      "gif": { 
                               "thumbnail": { "width": 256, "id": "cfdb3cc5.gif.thumb.jpg", "height": 191 }, 
                               "size": 4136640, "width": 443, "id": "02505e8f5e01aff254904853.gif",
                               "height": 332
                              },
                      "chat": { "name": "chat 1", "id": "4522291356145774", "type": 0 },
                      "message_id": "d2_QhlW1MAH12617138",
                      "from": { 
                                   "name": "John Smith",
                                   "id": "4521191845180798",
                                   "type": 0,
                                   "version": "('0hn0','1YDA','2ViB','32Fg')" }, 
                                   "type": "gif" }
                   }

Bot Features

Bots send and receive messages in real time. A bot can send many types of media messages including text, image, video, files, voice notes, audio and GIF. As well, bots can receive stickers, location and contact messages in real time. In addition, nandbox offers unique bot features including two types of keypads (normal and inline), offline keypads, and message updates.

Keypads Menu Types

nandbox offers two kinds of keypads: normal keypad and embedded (inline) keypad.  Unlike other apps, pressing buttons on keypads does not necessarily result in messages being sent to the chat. The keypads support buttons that work behind the scenes: callback buttons, URL buttons and next_menu buttons. For more details refer to section Bot API.

Normal Keypad Menu

Whenever your bot sends a message, it can pass along a special keypad with predefined reply options. nandbox apps that receive the message will display your keypad to the user. Tapping any of the buttons will send the respective command. This way you can drastically simplify user interaction with your bot. nandbox currently supports text and emoji for the buttons. Here are some custom keyboard examples:

                                                                                                               

Inline Keypad Menu

There are times when you would prefer to do things directly within the chat, such as when the user is changing settings, is choosing from a selection (e.g. voting) or flipping through search results. In such cases you can use Inline Keypads that are integrated directly into the messages they belong to. When callback buttons are used, your bot can update its existing messages (or just the keyboard) so that the chat remains tidy.

                                                                                                                                                       

Message Edit

Since Inline Keypad Menus do not send additional messages to the chat, it makes sense to give bots a way of updating existing messages, so that they don’t have to send a new message each time they need to update the message which will help building more fluid interfaces. All updated and edited messages will be marked with a small edit icon.

                                                                                                                                              

Bot Types

Chat Bot

Users can interact with chat bots directly by opening the bot chat, or indirectly by communicating with a bot within a group or channel.

Bot Filter

Bots are frequently added to groups and/or channels in order to augment communication between human users, e.g. by providing news, notifications from external services or additional search functionality. In order to insure that the bot is not receiving messages not intended for it, you can configure a bot filter.
A bot running with a filter will not receive all messages that people send to the group. Instead, it will only receive:

  • Messages that are posted by admins (for Channels only)
  • Replies to the bot’s own messages.
  • Service messages (people added or removed from the gronup, etc.)
  • All messages (posts and replies).

This allows the bot developer to save a on resources, since they won’t need to process irrelevant messages.

Bots added as admins to groups or channels have disabled filters by default (i.e. bot admins always receive all messages unless they have a filter).

<<< Image here >>>>

Location and Mobile Number

Some bots need extra data from the user to work properly. For example, knowing the user‘s location helps provide more relevant geo-specific results. The user’s phone number can be very useful for integrations with other services, like banks, etc.
Bots can ask a user for their location and phone number using special buttons. Note that both phone number and location request buttons will only work after the user accepts and grants permission for such service.

Bot API Manual

Hazem2

This is a new post

{
This is code
}

Authentication

Each bot is given a unique authentication token. You can obtain the token through the “Get token” overflow menu from the bot chat. Obtaining a new token will cause any existing token to immediately expire.

 

<<< Image here >>>

Sending Requests

Requests to nandbox Bot API are sent as JSON objects over a WebSocket session. In order to connect to the server, you need to obtain an authentication token first.
The Bot Server WebSocket URL format is:
wss://:/nandbox/api/
The first request over the WebSocket method must be an authentication request. An example of an authentication request is as follows:

{"method":"TOKEN_AUTH","rem":true,"token":"90091784056528980:0:odIgBOQZ4lVpqSIuxpQlGzmse3hwsS"}

If bot is successfully authenticated, you should receive a response like the following:

{"method": "TOKEN_AUTH_OK", "name":"Hello World”,
Bot","ID":"90091784056528980","reference":15269906159119,
"date":1533216558322}

After the bot is successfully authenticated it can send further requests.

Uploading Media

Media files are uploaded using HTTP PUT. You must set the following HTTP headers in the upload request:

  • ” Content-type” = File content type
  • “X-TOKEN” = Bot Token

The Bot Server upload URL format is:

https://<nandboxBotServer>:<port>/nandbox/upload/<filename>

Download Media

Media files are downloaded using HTTP GET. You must set the following HTTP headers in the download request.

  • “Content-type” = application/json
  • “X-TOKEN” = Bot Token

The Bot Server download URL format is:

https://<nandboxBotServer>:<port>/nandbox/download/<file id>

Keypad Menu

Sending Menu to Chat

For both Normal and Inline Keypad menus, the menu structure definition can be sent to chat in two ways:

  1. separately with specific JSON, or
  2. associated with specific message to the chat. The app will define the structure and associate the reference menu to that specific message.

Using Menu

Every menu has a reference identifier. Menus can be called and used in many ways:

  1. Associate menu reference with a specific message to chat. When you associate a menu reference to a message, the message will reference this menu. If the menu is already defined, it will be displayed as inline keypad menu.
  2. Associate menu reference with “start menu button.” When the user presses the start menu button, the menu will be displayed as normal menu.
  3. Menus can also be referenced from any other menu button by defining the menu reference in “next_menu” field.

Menu Button Properties

Each menu is composed from a set of buttons with a set of properties. When the user provides formal input or click a button the app will send the respective command.

Button Call Back

Callback command is sent into “Callback” field when a button is pressed by the user. For example, the bot can use callback command as an identifier for this button action. It is the responsibility of the bot developer to keep unique callback commands for all defined buttons.

Button Inquiry

A button can query some information from the app with the permission of the user. Examples of supported button queries:

  • Location: Ask user permission to inquire about geo-location and and if permission granted provide bot with geo-location coordinates of the device.
  • Contact: Ask user permission to inquire about the mobile number and if permission granted provide bot with mobile number of the device.
Buttons URL

Bots can define Button URL. When the button is pressed, the URL link will be opened.

All buttons with a defined URL will have a small arrow icon to indicate that pressing this button will open an external link.

Button next menu

When the button is pressed, the app will display next menu referenced within that button. This function is a great help for designing browsing menus and offline menus.

API Manual: Incoming Messages

Your bot must be connected and authenticated over the WebSocket session to receive incoming messages. The Bot Server does not store any messages for bots for later retrieval.
The following table lists the different incoming JSON messages for the bot.

method Type Description
message Message New, edited or deleted message
user User New or updated user or bot profile.
chat Chat New or updated Group or Channel profile.
chatMenuCallback ChatMenuCallback Incoming callback command from inline keypad menu
inlineMessageCallback InlineMessageCallback Incoming callback command from normal keypad menu
chatMember ChatMember
chatAdministrators chatAdministrators
myProfile MyProfile
setChatMenu_ack SetChatMenu_ack

Types

Capitalized types are data structures represented as JSON objects. The different types in incoming messages are listed below.

File identifiers in the Photo, Sticker, GIF, Video, Audio, Voice, Document and Text_File document can be used to download the actual file, see Section 4.4

It is safe to use 32-bit signed integers for storing all Integer fields unless otherwise noted.

Long fields are sent as Strings to avoid problems with JavaScript based clients.

Optional fields may be not returned when not relevant.

User

This object represents a nandbox user or bot account.

Field Type Required Description
id String Yes Unique identifier for this user or bot
name String Yes User or bot name.
version String Yes Last updated user profile version.
terminal String Optional Mobile if it is sent from mobile , API if it is sent from API : default is Mobile.
is_bot Boolean Optional True if this user is a bot. Returned only in GetUser
last_seen Timestamp Optional Unix Epoch timestamp. Returned only in GetUser and last_seen is enabled by user.
status String Optional User status. Returned only in GetUser ,
photo Photo Optional Public user’s Photo. Returned only in GetUser

Chat

Chat method is used to get Chat (Group or Channel) information.

 

Field Type Required Description
id String Yes Unique identifier for Group or Channel.
title String Yes Optional. title for Group or Channel
type String Yes “Group” , “Channel” “Contact” Or “Bot”
version String Yes Last updated Group or Channel profile version.
language_code Integer Yes IETF language tag of the main Chat language. Returned only in getChat.
regions String Optional Allowed region, if it is null means “All”. Returned only in getChat.
description String Optional Chat Description. Returned only in getChat.
photo Photo Optional PChat Photo. Returned only in getChat.
category String Optional Chat category. Returned only in getChat.
member_count Integer Optional Total Chat members count. Response only in getChat.
invite_link String Optional Chat invite link. Returned only in getChat.

Message

The main message method defines all parameters for all incoming messages to the bot.

 

Field Type Required Description
message_id String Yes Unique identifier for this message.
reference String Yes Unique local identifier
chat Chat Yes Conversation the message belongs to.
from User Yes Sender User of this message
sent_to User Yes Receiver user, most of the case it is the bot ID except if channel has multiple administrators, it will be the specific admin who should receive the message.
type String Yes “text”: For text messages
“text_file”: Message is a text tile. Any message exceeds 1800 characters will be converted to text file.
“photo”: Message is a photo.
“gif”: Message is a GIF
“sticker”: Message is a sticker.
“video”: Message is a video
“audio”: Message is an audio
“voice”: Message is a voice note
“location”: Message is a location
“contact”: Message is a contact
“document”: Message is a document
date Long Yes Date the message was sent in Unix Epoch timestamp in milliseconds
reply_to_message_id Integer Optional 1 if from user is admin, otherwise it is 0
from_admin String Optional Parent message Unique identifier.
text String Conditional Only available when type is text
text_file Text_File Conditional Only available when type is text_file
photo Photo Conditional Only available when type is photo
gif GIF Conditional Only available when type is gif
sticker Sticker Conditional Only available when type is sticker
video Video Conditional Only available when type is video
audio Audio Conditional Only available when type is audio
voice Voice Conditional Only available when type is voice
document Document Conditional Only available when type is document
location Location Conditional Only available when type is location
contact Contact Conditional Only available when type is contact
status String Optional “deleted” if messages is recalled and “updated” if it is updated.

JSON Example:

   {
       "method": "message", 
       "message": { 
                      "date": 1512445910180, 
                      "gif": { 
                               "thumbnail": { "width": 256, "id": "cfdb3cc5.gif.thumb.jpg", "height": 191 }, 
                               "size": 4136640, "width": 443, "id": "02505e8f5e01aff254904853.gif",
                               "height": 332
                              },
                      "chat": { "name": "chat 1", "id": "4522291356145774", "type": 0 },
                      "message_id": "d2_QhlW1MAH12617138",
                      "from": { 
                                   "name": "John Smith",
                                   "id": "4521191845180798",
                                   "type": 0,
                                   "version": "('0hn0','1YDA','2ViB','32Fg')" }, 
                                   "type": "gif" }
                   }

Text

This object represents Text entry.

Field Type Required Description
text String Yes The actual UTF-8 text of the message, 0-1800 characters.

Photo

This object represents Text entry.

Field Type Required Description
id String Yes Unique identifier for this file
width Integer Yes Photo width
height Integer Yes Photo height
size Integer Optional Photo size
thumbnail Photo Optional Thumbnail of the photo

GIF

This object represents GIF image.

Field Type Required Description
id String Yes Unique identifier for this file
width Integer Yes GIF width
height Integer Yes GIF height
size Integer Optional GIF size
thumbnail Photo Optional Thumbnail of the photo

Sticker

This object represents Sticker Photo.

Field Type Required Description
id String Yes Unique identifier for this file
width Integer Optional Sticker width
height Integer Optional Sticker height
size Integer Optional Sticker size
thumbnail Photo Optional Thumbnail of the photo

Video

This object represents a video file.

Field Type Required Description
id String Yes Unique identifier for this file
width Integer Yes Video width
height Integer Yes Video height
duration Integer Yes Duration of the video in seconds.
size Integer Yes Video size
thumbnail Photo Optional Video thumbnail

Audio

This object represents a audio file.

Field Type Required Description
id String Yes Unique identifier for this file
duration Integer Yes Duration of the audio file.
performer String Optional Performer of the audio as defined by sender or by audio tags.
title String Optional Title of the audio of the audio as defined by sender or by audio tags
size Integer Yes Audio file size

Voice

This object represents a voice note.

Field Type Required Description
id String Yes Unique identifier for this file
duration Integer Yes Duration of the voice note.
size Integer Yes Voice file size

Document

This object represents a general file (as opposed to photos, voice messages and audio files).

Field Type Required Description
id String Yes Unique identifier for this file
name Integer Optional Document name as defined by Sender.
size Integer Yes Document file size.

Text File

This object represents a text file.

Field Type Required Description
id String Yes Unique identifier for this file
size Integer Yes File size.

Location

This object represents a point on the map.

Field Type Required Description
longitude String Yes longitude
Latitude String Yes latitude
name String Optional Location name
details String Optional Location details

Contact

This object represents a phone contact.

Field Type Required Description
phone_number String Yes Contact’s phone number
Name String Yes Contact full name

ChatMenuCallback

This object represents an incoming callback query from a callback button associated with a normal keypad menu.

Field Type Required Description
button_callback String Yes Unique identifier for button as defined by bot.
menu_ref String Yes Menu Unique identifier defined by bot where button belongs to.
from User Yes Sender User who pressed the button.
chat Chat Yes Conversation the message belongs to.
date Long Yes Long date format in milliseconds
next_menu Integer Optional The menu to navigate to it when the button pressed.
button_query_result ButtonQueryResult Optional Returned inquiry information from app. The field either will return
“Location” in form of longitude and latitude respectively as comma separated.
“Phone number” depends on the buttonQuery.

InlineMessageCallback

This object represents an incoming callback query from a callback button within an inline keypad menu associated with a specific message. If the button that originated the query was attached to a message sent by the bot, the field message_id will be present.

Field Type Required Description
button_callback String Yes Unique identifier for button as defined by bot.
menu_ref String Yes Menu reference
from User Yes Sender User of the message
chat Chat Yes Conversation the message belongs to.
message_id String Yes Associated message Global Unique identifier where the menu belong to.
reference long Yes Associated message Unique local identifier as defined by the bot.
date Long Yes Long date format in milliseconds
next_menu Integer Optional The menu to navigate to it when the button pressed.
button_query_result ButtonQueryResult Optional Returned inquiry information from app. The field either will return
“Location” in form of longitude and latitude respectively as comma separated.
“Phone number” depends on the buttonQuery.

ButtonQueryResult

This object represents an incoming button query results from a callback button.

Field Type Required Description
latitude String Optional Only sent in case of buttonQuery is location
longitude String Optional Only sent in case of buttonQuery is location
contact String Option Only sent in case of buttonQuery is phone_number

Chat Member

This object represents a chat member user. Returned in getChatMember banChatMember, unbanChatMember, removeChatMember and when user leaves the chat.

Field Type Required Description
user User Yes Member User Unique identifier
chat Chat Yes Chat Unique identifier where member belongs or used to belongs to
type String Yes “member” if user is a member, “admin” if user is an admin.
member_since Timestamp Optional unique Epoch timestamp.
status String Yes “active”: where user is an active member in the Chat
“deleted” : where user has been deleted from Chat.
“banned”: when user has been banned from Chat.
“left” : when user left the Chat.

JSON Example:

 
{ 
	"chatMember":{ 
				"user":{ “id”:"4521191845180798" },
				"chat":{ “id”:"4522291356145774" },
				"type":"Admin",
				"status":"Active",
				"member_since":1512440093000
				},
	"method":"chatMember" 
}

Chat Administrators

This object represents chat administrator users. Returned in getChatAdministrators.

Field Type Required Description
administrators Array of User Yes List of All admin Users Unique identifiers
chat Chat Yes Chat Unique identifier where member belongs or used to belongs to
  
{
	"chatAdministrators":{
		"administrators":[
			{
				“id”:"4521191845180798"
			},
			{
				“id”:"4523390866547577"
			} 
		], 
			"chat”: { ":4522291356145774
		},
	"method":"chatAdministrators"
	}

My Profile

This object represents Bot profile. Returned in getMyProfile or setMyProfile

Field Type Required Description
user User Yes List of All admin Users Unique identifiers
chat Chat Yes Chat Unique identifier where member belongs or used to belongs to

JSON Example:

	{
		"method": "myProfile",
		"user": {
				"name": "Bot Title",
				"photo": {
						"thumbnail": { 
									"width": 120,
									"id": "7e8bc6cddff924.jpg.thumb.jpg",
									"height": 120 
								},
								"width": 256,
								"id": "7e8bc6cddff92487fbeb4074e.jpg",
								"height": 256 
					},
					"id": "4521191845180798",
					"version": "0btm",
					"status": "Bot Status", 
		}
	}

SetChatMenu_ack

This object represents acknowledgement of receipt new or updated normal keypad menu in returned for setChatMenu.

Field Type Required Description
chat Chat Yes Conversation Chat which menu send to.

JSON Example:

	{
		method:"setChatMenu_ack",
		“chat”:{
			“id”:"4522291356145774"
		}
	}

API Manual: Outgoing Messages

Send Message

Field Type Required Description
method String Yes “SendMessage”
chat_id String Yes Unique identifier for the target chat or User_id
text String Yes Text to send
disable_web_page_preview Boolean Optional Disables link previews for links in this message
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id String Optional If the message is a reply, unique identification for the original (parent) message.
reference long Yes Unique local identifier for the target chat/user
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
echo Integer Optional 1= to eacho sent message back to bot
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.
inline_menu Array of Menu Optional Inline menu object to hold menus.
If both inline_menu and menu_ref are defined. Priority for inline_menu.

Send Photo

Use this method to send photos. On success, the sent Message is returned. Bots can currently send phot files of up to 20 MB in size, this limit may be changed in the future.

Field Type Required Description
method String Yes “SendVideo”
chat_id String Yes Unique identifier for the target chat or User_id
video String Yes video to send. Pass a file_id as String to send a video that exists on the nandbox servers (recommended), pass an HTTP URL as a String for nandbox to get a video from the Internet.
caption String Optional “Video caption 0-256 characters
disable_web_page_preview Boolean Optional Disables link previews for links in this message
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id String Optional If the message is a reply, ID of the original message
reference long Yes Unique local identifier for the target chat/user
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
echo Integer Optional 1= to eacho sent message back to bot
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.
inline_menu Array of Menu Optional Inline menu object to hold menus.
If both inline_menu and menu_ref are defined. Priority for inline_menu.

Send Video

Use this method to send videos. nandbox clients support mp4 videos (other formats mybe sent as Document). On success, the sent Message is returned. Bots can currently send phot files of up to 50 MB in size, this limit may be changed in the future.

Field Type Required Description
method String Yes “SendVideo”
chat_id String Yes Unique identifier for the target chat or User_id
video String Yes video to send. Pass a file_id as String to send a video that exists on the nandbox servers (recommended), pass an HTTP URL as a String for nandbox to get a video from the Internet.
caption String Optional “Video caption 0-256 characters
disable_web_page_preview Boolean Optional Disables link previews for links in this message
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id String Optional If the message is a reply, ID of the original message
reference long Yes Unique local identifier for the target chat/user
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
echo Integer Optional 1= to eacho sent message back to bot
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.
inline_menu Array of Menu Optional Inline menu object to hold menus.
If both inline_menu and menu_ref are defined. Priority for inline_menu.

Send Audio

Use this method to send audio files, if you want nandbox clients to display them in the music player. Your audio must be in the .mp3 format. On success, sent Message is returned. Bots can currently send audio files of up to 50 MB in size, this limit may be changed in the future.

Field Type Required Description
method String Yes “SendAudio”
chat_id String Yes Unique identifier for the target chat or User_id
audio String Yes Audio to send. Pass a file_id as String to send an audio that exists on the nandbox server.
performer String Optional Audio file performer
title String Optional Audio file title
caption String Optional “Audio caption 0-256 characters”
disable_web_page_preview Boolean Optional Disables link previews for links in this message.
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id String Optional If the message is a reply, unique identification for the original (parent) message.
reference long Yes Unique local identifier for this message as defined by bot.
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
echo Integer Optional 1= repeat message
0= no echo
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.
inline_menu Array of Menu Optional Inline menu object to hold menus.
If both inline_menu and menu_ref are defined. Priority for inline_menu.

Send Voice

Use this method to send voice note. If you want nandbox clients to display the file as a playable voice message, your voice audio must be in an .ogg file encoded with OPUS (other format may be sent as Audio or Document). On success, the sent Message is returned. Bots can currently send voice note files of up to 50 MB in size, this limit may be changed in the future.

Field Type Required Description
method String Yes “SendVoice”
chat_id String Yes Unique identifier for the target chat or User_id
size String Optional Size of document
voice String Yes Voice note to send. Pass a file_id as String to send a voice note that exists on the nandbox servers .
caption String Optional Voice note caption 0-256 characters
disable_web_page_preview Boolean Optional Disables link previews for links in this message
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id String Optional If the message is a reply, unique identification for the original (parent) message.
reference long Yes Unique local identifier for the target chat/user
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
echo Integer Optional 1= repeat message
0= no echo
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.
inline_menu Array of Menu Optional Inline menu object to hold menus.
If both inline_menu and menu_ref are defined. Priority for inline_menu.

Send Document

Use this method to send general files. On success, the sent Message is returned. Bots can currently send files of any type of up to 50 MB in size, this limit may be changed in the future.

Field Type Required Description
method String Yes “SendDocument”
chat_id String Yes Unique identifier for the target chat or User_id
name String Optional Name of document
size String Optional Size of document
caption String Optional “Photo caption 0-256 characters”
disable_web_page_preview Boolean Optional Disables link previews for links in this message
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id String Optional If the message is a reply, unique identification for the original (parent) message.
reference long Yes Unique local identifier for the target chat/user
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
echo Integer Optional 1= repeat message
0= no echo
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.
inline_menu Array of Menu Optional Inline menu object to hold menus.
If both inline_menu and menu_ref are defined. Priority for inline_menu.

Send Location

Use this method to send location and point of map. On success, the sent Message is returned.

Field Type Required Description
method String Yes “SendLocation”
chat_id String Yes Unique identifier for the target chat or User_id
longitude String Yes longitude
latitude String Yes latitude
name String Optional Location name
details String Optional Location details
caption String Optional “Location caption 0-256 characters
disable_web_page_preview Boolean Optional Disables link previews for links in this message
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id String Optional If the message is a reply, unique identification for the original (parent) message.
reference long Yes Unique local identifier for the target chat/user
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
echo Integer Optional 1= repeat message
0= no echo
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.
inline_menu Array of Menu Optional Inline menu object to hold menus.
If both inline_menu and menu_ref are defined. Priority for inline_menu.

Send Contact

API Manual

Complete API Manaual

BOT Java SDK

An easy to use library to create nandbox BotsOK

Code Examples

Some source code example for usefule bots.

How to create Bot

In few steps, you can configure and publish your new bots using an interactive menu.

NAME POSITION OFFICE AGE START DATE SALARY
Airi Satou Accountant Tokyo 33 2008/11/28 $162,700
Angelica Ramos Chief Executive Officer (CEO) London 47 2009/10/09 $1,200,000
Ashton Cox Junior Technical Author San Francisco 66 2009/01/12 $86,000
Bradley Greer Software Engineer London 41 2012/10/13 $132,000
Brenden Wagner Software Engineer San Francisco 28 2011/06/07 $206,850
Brielle Williamson Integration Specialist New York 61 2012/12/02 $372,000
Caesar Vance Pre-Sales Support New York 21 2011/12/12 $106,450
Cedric Kelly Senior Javascript Developer Edinburgh 22 2012/03/29 $433,060
Hazem Hazem Jazem
Charde Marshall Regional Director San Francisco 36 2008/10/16 $470,600

Update Message

Use this message to update existing Message sent. On success, the sent Message is returned with status “updated”

Field Type Required Description
method String Yes “updateMessage”
message_id String Yes Old message ID that you want to edit it
text String Conditional Only use if you want to update Message has type of “text”
caption String Conditional Only use if you want to update Message has type of other than “text” e.g. photo, video, audio,..etc.
chat_id String Yes Unique identifier for the target chat or User_id
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.
inline_menu Array of Menu Optional Inline menu object to hold menus. Previous menu will be dropped and replaced by the updated one.
If both inline_menu and menu_ref are defined. Priority for inline_menu.

Set Chat Menu

Use this message to set normal keypad menus “Chat Menu”. This message will overwrite the existing Chat Menus. If bot wants to update specific item in the Chat Menus, bot must send the entire menus again to the target chat. On success, setChatMenu_ack will be returned.

Field Type Required Description
method String Yes “setChatMenu”
menus Menu Yes New or updated Menus
chat_id String Yes Unique identifier for the target chat or User_id
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
	{ 
	"method":setChatMenu,
		"chat_id":"4522291356145774",
		"menus":[
			{ 
				"menu_ref":"KEY1", 
				"rows":[ 
				{ 
					"buttons":[ 
						{ 
							"next_menu":null,
							"button_span":1,
							"button_order":1,
							"button_textcolor":"white",
							"button_callback":"B1",
							"button_bgcolor":"black",
							"button_label":"B1",
							"button_url":"abc",
							"button_query":"abc"
						} 
					],
					"row_order":1
				} 
			]
		} 
	 ]
	}

Types

The following data structures represents custom keypad menus with reply options

Menu

Each Menu composes of set of rows. At least one row should be defined.

Field Type Required Description
menu_ref String Yes Unique identifier of this Menu as defined by bot.
rows Array of Row Yes Rows belong to this menu. Row which is an Array of buttons
Row

Each row belongs to one keypad menu that composes of set of buttons. At least one button should be defined.

Field Type Required Description
buttons Array of Button Yes Button belongs to the row.
row_order Integer Yes Row order in the menu.
Button

This object represents button of reply. Button must have a button_callback which is the unique identifier defined by bot.

Field Type Required Description
button_callback String Yes This is unique identifier as defined by bot.
The button_callback returned in inlineMessageCallback
and ChatMenuCallbakc when button pressed.
next_menu Menu Optional Menu unique identifier that reference the next menu to
navigate to it when the button pressed.
button_span Integer Optional Button Span
button_order Integer Optional The number of button order by ascending
button_text_color String Optional Text color of the button Title
button_bg_color String Optional Button background color
button_label String Optional Button label or title.
button_url String Optional Button URL. When button pressed, an external URL link will be opened
button_query String Optional Field used to query information from app, this can take one of two values as follows
Location: to ask user to get location or point of map information.
Contact : to ask user to get his contact number.
button_chat Chat Optional Chat unique identifier that reference the specific chat to be opened when button is pressed.
if button_url and button_chat are both defined, button_chat priority to button_chat.

Set Navigation Button

Use this method to set the navigation button with the menu reference. When navigation button is pressed the referenced menu will be displayed as normal keypad menu “Chat Menu”.

Field Type Required Description

 

method String Yes “setNavigationButton”
menu_ref String Yes Menu unique identifier that reference the next menu to navigate to it when the navigation button pressed.
chat_id String Yes Unique identifier for the target chat or User_id
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id String Optional If the message is a reply, unique identification for the original (parent) message.
reference long Yes Unique local identifier for the target chat/user
to_user_id String Optional if reply or send message to target user within a group chat or channel, unique identifier of the target user.
echo Integer Optional 1= to eacho sent message back to bot
menu_ref String Optional Menu reference for existing predefined Menu. The menu will be displayed as inline menu associated to the message.

Get User

Use this method to get profile for a user. On success, User is returned.

Field Type Required Description
method String Yes “getUser”
user_id String Yes Unique identifier for this user or bot.
	{
		method: "getUser",
		user_id: "4521191845180798"	
	}

Get Chat

Use this method to get Group or Channel information. On success, Chat is returned.

Field Type Required Description
method String Yes “getChat”
chat_id String Yes Unique identifier for Group or Channel

Json example

	{
		method: "getChat",
		chat_id: "4522291356145774"	
	}

Get Chat Member

Use this method to get Chat Member user public profile. On success, ChatMember is returned.

Field Type Required Description
method String Yes “getChatMember”
chat_id String Yes Unique identifier for Group or Channel where member belongs to.
user_id String Yes Unique identifier for this user member.

JSON Example:

	{
		method: "getChatMember",
		chat_id: "4522291356145774",
		user_id: "4521191845180798"
	}

 

Get Chat Administrators

Use this method to get Chat Administrators. On success, ChatAdministrators is returned.

Field Type Required Description
method String Yes “getChatAdministrators”
chat_id String Yes Unique identifier for Group or Channel.

 

JSON Example:

{ method: "getChatAdministrators", 
chat_id: "4522291356145774" }

Ban Chat Member

Use this method to ban a Chat Member from accessing Chat. On success, ChatMember is returned with status “banned”. Ban is a black list, user will not be able to join Chat again.

Field Type Required Description
method String Yes “banChatMember”
chat_id String Yes Unique identifier for Group or Channel where member belongs to.
user_id String Yes Unique identifier for this user member.

JSON Example:

{ 
method: "banChatMember", 
chat_id: "4522291356145774", 
user_id: "90089584758972053" }

Unban Chat Member

Use this method to unban a Chat Member from accessing Chat. On success, ChatMember is returned with status “Active”. unBan is remove from black list, user will be able to join Chat once again.

Field Type Required Description
method String Yes “unbanChatMember”
chat_id String Yes Unique identifier for Group or Channel where member belongs to.
user_id String Yes Unique identifier for this user member.

JSON Example:

{ method: "unbanChatMember", 
chat_id: "4522291356145774", 
user_id: "90089584758972053" }

Remove Chat Member

Use this method to remove a Chat Member from Chat. On success, ChatMember is returned with status “removed”. Remove user is a temprorary kicking the user out from the Group or Channel. User will be able to join Chat once again.

Field Type Required Description
method String Yes “removeChatMember”
chat_id String Yes Unique identifier for Group or Channel where member belongs to.
user_id String Yes Unique identifier for the banned user.

JSON Example:

{ method: "removeChatMember", 
chat_id: "4522291356145774", 
user_id: "90089584758972053" 
}

Set Chat

Use this method to remove a Chat Member from Chat. On success, ChatMember is returned with status “removed”. Remove user is a temprorary kicking the user out from the Group or Channel. User will be able to join Chat once again.

Field Type Required Description
method String Yes “setChat”
chat Chat Yes Unique identifier for Group or Channel.

JSON Example:

{ method: "setChat", 
chat: { 
id: "4522291356145774", 
name: "CHANGE 3", 
photo: { 
id: "8d7773be38db78.jpg" } } }

Recall Message

Use this method to set Chat Group or Channel information. On success, chat is returned.

Field Type Required Description
method String Yes “recallMessage”
chat_id String Yes Unique identifier of chat id
message_id String Yes Global Unique identifier for message requested to be recalled.

JSON Example:

{ method: "recallMessage", 
chat_id: "4522291356145774",
 message_id: "d2_F4k48l1t12617132" 
}

Set My Profile

Use this method to set Bot Profile. On success, myProfile is returned.

Field Type Required Description
method String Yes “setMyProfile”
user User Yes Bot profile user object
message_id Chat Yes Global Unique identifier for message requested to be recalled.

JSON Example:

{ method: "recallMessage", 
chat_id: "4522291356145774", 
message_id: "d2_F4k48l1t12617132" 
}

hazem

text here

Get My Profiles

Use this method to get Bot Profile. On success, myProfile is returned.

Field Type Required Description
method String Yes “getMyProfile”

JSON Example:

{ method: "getMyProfiles" }

Feature Posts

API Manual

Complete API Manaual

BOT Java SDK

An easy to use library to create nandbox BotsOK

Code Examples

Some source code example for usefule bots.

How to create Bot

In few steps, you can configure and publish your new bots using an interactive menu.

NAME POSITION OFFICE AGE START DATE SALARY
Airi Satou Accountant Tokyo 33 2008/11/28 $162,700
Angelica Ramos Chief Executive Officer (CEO) London 47 2009/10/09 $1,200,000
Ashton Cox Junior Technical Author San Francisco 66 2009/01/12 $86,000
Bradley Greer Software Engineer London 41 2012/10/13 $132,000
Brenden Wagner Software Engineer San Francisco 28 2011/06/07 $206,850
Brielle Williamson Integration Specialist New York 61 2012/12/02 $372,000
Caesar Vance Pre-Sales Support New York 21 2011/12/12 $106,450
Cedric Kelly Senior Javascript Developer Edinburgh 22 2012/03/29 $433,060
Hazem Hazem Jazem
Charde Marshall Regional Director San Francisco 36 2008/10/16 $470,600