1  # Chat API
 2  
 3  ## Interface Anatomy
 4  
 5  This anatomy establishes the different sections of the chat interface
 6  and establishes a common verbiage. The main components being:
 7  
 8    - Message
 9    - Input
10    - Keyboard
11    - Suggestions
12  
13  ## Accessing a bot
14  
15  `/global` (hidden) Universal command for the bot, allows the bot command
16  to be referenced in any chat via `@botname`. If this exists it should
17  appear in the command list as another section at the bottom.
18  
19  `/init` (hidden)
20  Run on open chat session, only in 1-to-1 chats.
21  
22  `/`<command> bots can register a command handler of any ASCII title,
23  which then Status repeats
24  
25  `@botname/command` if there is multiple bots in a chat context, then the
26  `@botname` can be used to make the distinction (or alternatively a
27  suggestions/commands list should appear to help with the distinction)
28  
29  `Bot Message` a bot can send a message that can only be read by another
30  instance of itself in chat history. This message can send markup to draw
31  and contain data. It is activated by a user tapping on it.
32  
33  `A message parsed from chat history` on 1-to-1 chats, any message the
34  user send can be read by the bot and can activate code via
35  `status.on('chat-update', function () { ... } );` handler.
36  
37  ## Bot Messages
38  
39  A Bot Message can contain it’s own markup and a data payload, this
40  message can be transmitted to the chat context. If it is interactable
41  then the interaction (what we currently call response handler) handles
42  the message when tapped.
43  
44  **If the user does not have the bot installed, then we display a custom
45  keyboard that shows the bot name, its reviews/ reputation and a “Install
46  / Add to Contacts” button, which the user can either cancel or install
47  and continue with response flow.**
48  
49  ## Command Handlers
50  
51  Once a command handler is invoked it is passed the current text / data
52  payload of the message, and is required to return the paramaters (and
53  their placeholder information). The return of the handler must include -
54  `markup` or a `status component(data)` for the suggestions area -
55  `markup` or a `status component(data)` for the the keyboard - an error
56  object - the revised text / data payload.
57  
58  ## Privacy
59  
60    - a bot can only be interacted with via commands or messages via in
61      1-to-1 chats
62    - a bot can only see messages from itself and the current user in
63      group chats.
64  
65  ## Deployment & Testing
66  
67  Console should have some `/debug` mode that allows the user to plugin
68  their phone in and hot-load javascript/webpage to make testing web-based
69  dapps or bots easily from desktop. Ideally it should have integration
70  with [Truffle](http://truffleframework.com/) &
71  [Embark](https://github.com/iurimatias/embark-framework) and pay respect
72  to [EIP190](https://github.com/ethereum/EIPs/issues/190)
73  
74  ## Open Questions
75  
76  Is there an issue of resources and conservation around Otto VM jails?
77  Should it runs per dapp per chat context? or per DApp and then an object
78  in each per chat context?