Getting help

If you need assistance, visit the the Rogerthat mailing list.

Rogerthat users

Rogerthat on your smartphone or tablet

Rogerthat Messenger is a free mobile app. It is available on smartphones and tablets. The app can be installed from the various mobile app stores. You need a Google or Facebook account to log in.

Rogerthat in your browser

On devices with a larger screen or keyboard, it is more efficient to use Rogerthat in your browser. The free service is available at https://rogerth.at. Rogerthat will keep the browser and mobile messages perfectly synchronized in real time. You can use both media at the same time.

Rogerthat for services

Services and software tools can use the Rogerthat platform to communicate with Rogerthat users. Services have the following privileges:

  • API and UI to communicate with other Rogerthat users, invite them, starting message flows
  • API and UI to create QR codes and link them to message flows
  • Send “branded messages” i.e. on the smartphone full-screen graphically rich messages, in the browser iframes
  • Features such as alarms, forms

Setup

There are three major components in the setup:

  1. Mobile phones and computers of the users
  2. Rogerthat gateway which is hosted in the cloud
  3. Your server communicating with your users through the Rogerthat gateway

If you start experimenting with Rogerthat services, you should first go through the Quick starter guide.
This way you do not immediately need to start programming on your own server.
Instead you can use a preinstalled server which shows you the power of Rogerthat.

For production setups, you should have your own server which communicates with the Rogerthat gateway and vice-versa. There are two setup types.


Setup type 1: Outbound + inbound HTTP(S)

  • Your server can receive inbound HTTP(S) requests originating from the Rogerthat gateway. Preferably HTTPS.
  • Your server can send outbound HTTPS requests to the Rogerthat gateway.
  • Simple: any kind of web application server can be used.
  • Requires a server which is public on the internet. Requires an SSL certificate for production security.

Setup type 2: Outbound HTTPS + inbound XMPP

  • An XMPP connection is used for communication from the Rogerthat gateway to your server. The XMPP connection is initiated by your service, hence it is an outbound TCP/IP connection. The messages flowing over the connection are primarily inbound i.e. sent by the Rogerthat gateway to your service.
  • Advantage is that you do not need to process incoming TCP connections, hence you do not need a server with a public routable ip address.
  • However, this requires the ability to open a long living TCP connection between your server and to the Rogerthat gateway. Ask your network administrator and check your firewall settings.
  • Requests from your server to the Rogerthat gateway are outbound HTTPS requests.

Authentication

It is important that all communication between your server and the Rogerthat gateway is authenticated and encrypted.

Requests sent by your service to the Rogerthat gateway must be authenticated using a Service API Key, which you can generate in the Service control panel. As described below, the Service API Key must be included in every request you send to the Rogerthat gateway.

Requests sent by Rogerthat to your service will be authenticated using a Service Identifier Key, which you can also generate in the Service control panel. As described below, the Service Identifier Key will be included in every request sent by Rogerthat to your service. Your service should validate the presence and correctness of such a key, to avoid processing non-authenticated requests.

How to send requests from your service to the Rogerthat gateway

Protocol

  • API calls from your service to Rogerthat are HTTPS JSON-RPC POST requests to a fixed URL https://rogerth.at/api/1
  • Content-type is application/json-rpc
  • You need an HTTP header X-Nuntiuz-API-Key with your Service API Key as value. You can find it in your service panel

Simplified example HTTP(S) request from your service to Rogerthat:

POST /api/1/ HTTP/1.1
Content-type: application/json-rpc
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send",
    "params": {
        "message": "Your order 'Animal Farm' has been shipped to you.",  
        "members": [
            "test@example.com" 
        ],
    },
    "id": "a_unique_json_rpc_id_of_your_choice" 
}

Note: We use a green background for requests from your service to Rogerthat.
Note: This is a simplified example; do not try it since a number of mandatory parameters are missing.

How to receive requests from the Rogerthat gateway to your service

As describe before, there are two approaches:

  • Rogerthat gateway sends an HTTP(S) request to a configurable callback URL on your web application server. This URL must be reachable from the internet.
  • Rogerthat gateway sends an XMPP request to a configurable XMPP JID. In some networking and firewall setups this is preferred since an outgoing TCP/IP connection is used instead of incoming HTTPS requests.

How to receive HTTP(S) callback requests from the Rogerthat gateway

See the communication diagram above.

Communication:

  • API callbacks from Rogerthat to your service are HTTPS JSON-RPC POST requests to a configurable URL on your servers. You can configure the URL in the Service Control Panel. You need to check the radio button HTTP(S)
  • Content-type is application/json-rpc
  • Your service must validate that every incoming requests contain HTTP header X-Nuntiuz-Service-Key with a correct value

Example HTTP(S) callback from the Rogerthat gateway to your service

POST /your/rogerthat/callback/url HTTP/1.1
Content-type: application/json-rpc
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "messaging.update",
    "params": {
        "received_timestamp": 1301396903, 
        "member": "test@example.com", 
        "message_key": "7bcc1b94-c193-47bf-ae85-157565ac0e78"
    },
    "id": "a_unique_jsonrpc_id_generated_by_the_rogerthat_gateway" 
}

Note: We use a purple background for requests from your Rogerthat to your service.

How to receive XMPP callback requests from the Rogerthat gateway

The XMPP-based setup is slightly different:

  • API callbacks from Rogerthat to your service or software are messages to an XMPP account of your choice. You must select the XMPP radio button in the Service Control Panel and configure an XMPP account that you own. You can create an account for free at jabber.org
  • No need to have a web server running on the internet
  • Your service must check that the message is sent from bot@callback.rogerth.at
  • Your service must check that the message is sent to your XMPP account e.g. service@example.com
  • Check that the message XML node contains exactly one child node with name call and xml namespace mobicage:comm (comm is not a typo – it stands for communication)
  • Check that the call XML node has an attribute sik which is your Service Identifier Key

Incoming XMPP callback request

This is an example incoming XMPP request

<message from='bot@callback.rogerth.at' to='service@example.com'>
  <call xmlns='mobicage:comm'
    sik='Your secret service identifier key'>
eyJwYXJhbXMiOiB7InN0YXR1cyI6IDEsICJyZWNlaXZlZF90aW1lc3RhbXAiOiAxMzE0NjkzOTU0
LCAibWVzc2FnZV9rZXkiOiAiYjJiOTFkNzEtMTU1OS00Y2I0LTliNjYtZTlmOWM0NWQ5YTYwIiwg
Im1lbWJlciI6ICJ1c2VyQGV4YW1wbGUuY29tIiwgICJ0YWciOiAibXNnIHRhZyAwMDAxIiwgImFj
a2VkX3RpbWVzdGFtcCI6IDAsICJhbnN3ZXJfaWQiOiBudWxsfSwgIm1ldGhvZCI6ICJtZXNzYWdp
bmcudXBkYXRlIiwgImlkIjogIjc5NzY2ODdkLWQyZTQtMTFlMC04MTVhLTgxMGYxMGM5NzU0NCJ9
   </call>
</message>

Take the body of the call XML node and base64 decode this multiline string. You get a JSON string

{'id': '7976687d-d2e4-11e0-815a-810f10c97544',
 'method': 'messaging.update',
 'params': {'acked_timestamp': 0,
            'answer_id': None,
            'member': 'user@example.com',
            'message_key': 'b2b91d71-1559-4cb4-9b66-e9f9c45d9a60',
            'received_timestamp': 1314693954,
            'status': 1,
            'tag': 'msg tag 0001'}}

Responding to incoming XMPP callback request

Sending back an XMPP response to this message happens as follows.

First JSON encode the response. For example

{'id': '7976687d-d2e4-11e0-815a-810f10c97544',
 'result': null,
 'error': null}

Now create an XMPP message to Rogerthat

  • Create an XMPP message from your XMPP account to bot@callback.rogerth.at
  • Create XMPP child node result in XML namespace mobicage:comm
  • Put your Service Identifier Key in the sik attribute on the result node
  • Put your base64 encoded JSON response in the body of the result node

Example XMPP response message

<message from='service@example.com' to='callback@rogerth.at'>
  <result xmlns='mobicage:comm'
    sik='Your secret service identifier key'>
eydpZCc6ICc3OTc2Njg3ZC1kMmU0LTExZTAtODE1YS04MTBmMTBjOTc1NDQnLAogJ3Jlc3VsdCc6
IG51bGwsCiAnZXJyb3InOiBudWxsfQ==
   </result>
</message>

Check this Python code for an example implementation.

How to test your service

Click the button “Test Configuration” in the Service Control Panel.
This will validate the HTTP(S) or XMPP callback communication path.
You cannot enable a service which did not pass the test callback.

The test method sends a random test challenge. Your service is expected to return the identical challenge. Your service has to respond within 10 seconds. Once your service sent a successful response to a test challenge, you will be able to enable your service.

Example HTTP(S) call from Rogerthat to your service

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "test.test",
    "params": {
        "value": "random test 012345"
    },
    "id": "1658829C-ECBA-47A0-A30E-44569D84BA1B"
}

Example HTTP(S) response

HTTP/1.0 200 OK
Content-type: application/json-rpc
{
    "result": "random test 012345",
    "error": null,
    "id": "1658829C-ECBA-47A0-A30E-44569D84BA1B"
}

Playing around with the API

We now list a few API calls that you can try out to:

  • Invite a user to your service
  • Send a message to the user and receive callbacks
  • Start a message flow and receive the flow result

For a complete overview, please refer to the API reference.

How to manage your service

Enable/disable service

Once you have clicked Test Configuration and the test was successful, you can enable or disable your service using the checkbox on top of the Service Control Panel.

Service logs

Select Logs in the left menu pane in the Service Control Panel. You can inspect the calls and callbacks of your service.

Users of your service

Select Users in the left menu pane in the Service Control Panel. You see a list of users of your service.

Service menu

Every service has its own “home screen” inside the Rogerthat app.

Screen branding

Messages, service menus, about pages and static content pages can all be branded. You can manage your screen brandings in this menu.

QR codes

You can manage QR code brandings, and you can create as many QR codes as you need.

Message flows

You can design and manage your message flows, and try them out.