Interfaces

Interfaces

An interface is something that lets your application communicate with Nuntium.

Examples of interfaces

• RSS: your application sends messages to Nuntium by POSTing an RSS feed to an URL in Nuntium. Your application receives messages from Nuntium by GETing an RSS feed from an URL in Nuntium.
• https://bitbucket.org/instedd/wiki/QueueStateTransfer
• HTTP GET: your application sends messages to Nuntium by GETting an url with query parameters. Nuntium sends messages to you application by GETting an url with query parameters.
• HTTP POST: your application sends messages to Nuntium by POSTing url-encoded data. Nuntium sends messages to you application by POSTing url-encoded data.

HTTP interface

When configuring an application's interface to HTTP GET or HTTP POST Nuntium will interpret the HTTP response according to its content type:

• text/plain: an AO message will be routed to the application with the 'from' and 'to' fields being the 'to' and 'from' fields of the AT that caused the HTTP GET or HTTP POST, and the 'body' field being the response body. This is useful to generate a reply to an AT message sender.
• application/json: AO messages will be generated from the given JSON. The JSON must be an array of hashes, each hash containing the properties 'from', 'to', 'body' and so on. Additional properties will be treated as custom attributes, as specified Messages.
• application/xml: AO messages will be generated from the given XML. The XML must comply to the https://bitbucket.org/instedd/geochat/wiki/QueueStateTransfer.

In all of these cases, the generated AO messages will have a Tokens value equal to the AT message's guid, unless overriden in the response. This allows you to relate the AT message with the AO messages generated by the application.

Custom formats

By default the GET query string and the POST data will be of the form:

from=...&to=...&subject=...&body=...&guid=....&channel=...&application=...&custom1=...

You can change this format by specifying a custom format with placeholders. Placeholders have the form ${field}, where field can be:

• from
• from_without_protocol: the from field without the protocol specifier
• to
• to_without_protocol: the to field without the protocol specifier
• subject
• body
• subject_and_body: the concatenation of the subject and body, separated by a dash, or any of them if the other is not present
• guid
• application: the name of the application this message is being sent to
• channel: the name of the channel this message was routed through
• (other): use a custom attribute's value for the placeholder.

So for example if you have an application that accepts messages via GET via the 'text' query string parameter, you can configure the custom format to be:

text=${subject_and_body}