Update chat-api.md

docs/proposals/chat-api.md

@@ -11,31 +11,38 @@ This anatomy establishes the different sections of the chat interface and establ
 
 ![](img/chat-anatomy.png)
 
-## Commands
+## Accessing a bot
 
-!init (hidden)  
-    - if it exists run on open chat session, only in 1-to-1 chats.  
-!help  
-!settings
+`/global` (hidden)
+Universal command for the bot, allows the bot command to be referenced in any chat via `@botname`.
 
-### Explicitly calling commands
+`/init` (hidden)  
+Run on open chat session, only in 1-to-1 chats.  
 
-DApps are namespaced with @dappname!command, which can be useful if same commands used by multiple bots are available, alternatively these can be used for commands when bot is not actually in the chat, ie @wallet!send
+`/<command>` bots can register a command handler of any ASCII title, which then Status repeats
 
-## Custom Keyboards
+`@botname/command` if there is multiple bots in a chat context, then the `@botname` can be used to make the distinction (or alternatively a suggestions/commands list should appear to help with the distinction)
 
-Parameters use custom keyboards (instead of types, we adapt our types to be keyboards themselves?)  
+`Bot Message` a bot can send a message that can only be read by another instance of itself in chat history. This message can send markup to draw and contain data. It is activated by a user tapping on it.
 
-Make our emoji/sticker market with this, otherwise accessible through commands
-ie !init command with param that opens up a config
+`A message parsed from chat history` on 1-to-1 chats, any message the user send can be read by the bot and can activate code via `status.on('chat-update', function () { ... } );` handler.
 
-## Messages
+## Bot Messages
 
-- subscription to message feed
-- api for sending messages, and setting things like "typing"
-- not available in group
+A Bot Message can contain it's own markup and a data payload, this message can be transmitted to the chat context. If it is interactable then the interaction (what we currently call response handler) handles the message when tapped. 
+
+**If the user does not have the bot installed, then we display a custom keyboard that shows the bot name, its reviews/ reputation and a "Install / Add to Contacts" button, which the user can either cancel or install and continue with response flow.**
+
+
+## Command Handlers
+
+Once a command handler is invoked it is passed the current text / data payload of the message, and is required to return the paramaters (and their placeholder information). The return of the handler must include 
+- `markup` or a `status component(data)` for the suggestions area 
+- `markup` or a `status component(data)` for the the keyboard
+- an error object
+- the revised text / data payload.
 
 ## Privacy
 
-- by default does not receive all messages in group chat
-- only commands and in 1-to-1
+- a bot can only be interacted with via commands or messages via in 1-to-1 chats
+- a bot can only see messages from itself and the current user in group chats.