path: root/README.md

# N Core - the backend of N  

Build upon [crow](https://github.com/ipkn/crow) [forked](https://git.niklashalle.net/crow) to fix a deprecation in boost 1.7+

## N protocol  
### request  
Each message sent to the N core server must be valid JSON and have a `command` field. It contains the command for N to handle, sanitized (i.e. no leading '/' or trailing username etc).  
The arguments field contains the remaining text just as was send to the bridge.  
All messages may optionally include an `session` field. When you authorize against N core or switch to a menu, you will be returned (see next section) a session id which you can then send with this field to follow up on the initial command.  
  
| Field | Type | Description |  
|-------|------|-------------|  
| `command` | string | The command N core should handle |  
| `arguments` | string | The arguments to the command (i.e. all remaining text in the message - can be empty) |  
| `session` | string | The session id, should default to `"null"` |  
  
### answer  
The answer consists of an array of `reply` objects, an `success`-flag and a `session`-id provided by N core.  
The reply objects enable N core to request certain formatting from the bridges, which they should try to implement as close as the underlying platform supports it. In any case, the plain text stringed together from all replies `text` field should be enough to get the message to the user, annotations should be fully optional.  
The session id can be ignored by bridges, but this will opt the bridge out of more complex (context specific) commands.  
JSON object overview:  
  
| Field | Type | Description |  
|-------|------|-------------|  
| `reply` | array of `reply`-objects | The reply from N core |  
| `success` | bool | Whether the command was successful |  
| `session` | string | A session id, defaults to `"null"` |  
  
#### `reply`  
The `reply` object:  
  
| Field | Type | Description |  
|-------|------|-------------|  
| `text` | string | A part of the answer |  
| `annotations` | array of `annotation`-objects | The annotations to this answer part |  
  
#### `annotation`  
The `annotation` object:  
  
| Field | Type | Description |  
|-------|------|-------------|  
| `type` | string | A part of the answer |  
| `extra` | array of `reply`-objects | Extra content specific to the annotation type |  
  
The currently specified annotation types are enumerated below:  
  
##### `none`
The text should be printed as plain text.  
No extra content.  
  
##### `bold`
The text should be printed bold.  
No extra content.  
  
##### `italic`
The text should be printed italic.  
No extra content.  
  
##### `strikethrough`
The text should be printed strikethrough.  
No extra content.  
  
##### `underline`
The text should be printed underlined.  
No extra content.  
  
##### `attachment`
The text is the caption of an attached file.
Extra content: String of content: "`file_name`;`file_type`;`file_content`", where `file_content` is base64 encoded.  
E.g.: "image.png;png;iVBORw0KGgoAAAANSUhEUgAAABwAAAAMBAMAAACD9cA8AAAALVBMVEX///8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAOrOgAAAADnRSTlMAELt2Mu9Eic1mIqtU3XZzvlQAAAAJcEhZcwAADsQAAA7EAZUrDhsAAACJSURBVAgdY2BgFGCAARCTyQDGAzP5HOBcENMVzgMx0zsqGXjmGDBwzpwFYjJoMjBsZkhjOMlQCWIyvGLgvMBQxVDhIABkMrAFMPDqTE5gWPv0AJDJwL6BQW4ByLTlD4BMBo4JMnJADscBhgAgk4HXwYDXgeEINwMbkDZg4LFZwFVzUoAt5ySICQDlYB5evEnwqgAAAABJRU5ErkJggg=="  
  
##### `command`
The text should be formatted in a way to underlying platform of the bridge would recognize it (e.g. prefix with '/').  
Extra content: the description of the command.  
  
##### `link`
The text should be formatted as a link.  
Extra content: the alt text for the uri - the uri should be the text itself, so that clients ignoring this annotation still show the real uri.