API reference

Overview

The Rogerthat API allows your software or service to interact with Rogerthat users.

Check Getting Started for a description on

• How to set up, manage and test your service account
• How to configure authentication
• How to send HTTP(S) calls to and receive HTTP(S) or XMPP callbacks from Rogerthat

There are two types of users in Rogerthat

• Human users: They are identified by their email address. Communication is free of charge. They use the mobile, desktop, or in-browser Rogerthat client. They can receive messages from service users or from each other, send messages to each other, send one-click responses to services or each other. They cannot use the API and cannot send branded messages.
• Service users: They are identified by their email address. They use the API to send messages to users and receive message delivery updates, one-click responses, invite users, react on invitations.

A single email address can correspond to a single human user, or a single service user. Not both.

Communication Protocol

TPS (Third Party Service) to Rogerthat

Request

The TPS makes a JSON-RPC HTTPS call to Rogerthat

• The API entry point URL is: https://rogerth.at/api/1
• The TPS authenticates itself to Rogerthat by sending the API key in the header
  X-Nuntiuz-API-Key
• Content-type is application/json-rpc; charset=utf-8
• Encoding of the body must be UTF-8

In the following example a TPS calls the method echo with arguments arg1 = “Hello” and arg2 = “World”. Note: do not try out this example; it only serves to explain the concepts of Rogerthat communication.

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "echo",
    "params": {
        "arg1": "Hello",
        "arg2": "World"
    },
    "id": "x122abcd"
}

Note: In this document we use a green background color for HTTPS requests initiated by the TPS (Third Party Service) to Rogerthat, and the corresponding HTTPS response sent back by Rogerthat to the TPS.

The fields “method”, “params” and “id” are mandatory

• method field is mandatory, and the value must be a string
• params field is mandatory
  • for a method with arguments, the value is a JSON object. Arguments are passed as name/value pairs. There cannot be two arguments with the same name. Arguments are not ordered, i.e. so-called positional parameters are not supported
  • for a method without arguments, the value of the params field must be an empty object {}. It is NOT allowed to pass null as a value
• id is the JSON-RPC id. This is a string generated by the client, which can be used to correlate the response to the request. Max length is 256 characters. A JSON-RPC id must be generated on a per call invocation basis. The Rogerthat platform uses the id of the call to store the call result for a certain amount of time so that if something fails during the communication, the same call (having the same JSON-RPC id) can be resent to the Rogerthat service, allowing to fetch the result, without actually executing the call again. This avoids annoying problems such as duplicate delivery of messages.

You should use a different JSON-RPC id for every call you make.

In case of an intermittent failure such as a network connectivity problem, you can retry the same call using the same JSON-RPC id, without running the risk of duplicate execution of your call (e.g. duplicate message delivery).

Encoding happens according to the rules specified in RFC 4627. You should use UTF-8

Response

The HTTP response status code of a Rogerthat JSON-RPC must always be checked by code making requests. The rules are simple. The HTTP response status code is:

• 200: The call was processed correctly by the business logic on the Rogerthat server. You should check the error field to find out if there were errors in the business logic.
• anything else: An error happened. This could be an authentication error, server overload, internal server error, … The call was not processed by the business logic on the Rogerthat server.

A response body always contains a JSON-RPC object, which is UTF-8 encoded. It contains the following fields:

• id: The same JSON-RPC id as present in the request
• result: A JSON-RPC result object or null if the method does not return a result. In case of error, this field is also null
• error: null in case there is no error; otherwise an object containing an error code and message

A typical successful response is:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": {
        "value": "Hello World"
    },
    "error": null,
    "id": "x122abcd"
}

Another example of a successful response, which does not return a result:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": null,
    "id": "x122abcd"
}

In case of error, the “error” value is not null:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": {
        "code": 1000,
        "message": "I do not want to echo"
    },
    "id": "x122abcd"
}

Rogerthat to TPS (Third Party Service)

Two possible communication paths exist for callbacks:

• HTTP(S) callbacks. For details see the Getting Started – HTTP(S) callbacks
• XMPP callbacks For details see the Getting Started – XMPP callbacks

The TPS must respond to callback requests quickly.

It is possible to piggyback actions on the HTTPS response to a callback. This roughly doubles Rogerthat performance. Check the Rogerthat High-performance API.

If the callback request from Rogerthat to the TPS fails, due to invalid configuration or failure of the TPS, Rogerthat will retry 6 times to send the callback request. Subsequent retry requests are: 30 seconds, 60 seconds, 120 seconds, 240 seconds, 480 seconds, 960 seconds.

If the callback does not succeed for 6 consecutive times, the TPS will be disabled, and you will be notified on the TPS email address about this event. You will need to visit the Service Control Panel to re-enable the service.

To catch simple misconfigurations early, the Service Control panel provides a test callback method. The test method sends a random string, and the the TPS is expected to echo the random string back to the service. The TPS has to respond within 10 seconds.

For details on this see the Getting Started – How to test your service.

Restrictions

The following restrictions apply to API calls

• Tag length is max 255 characters
• Callback URL length is max 1023 characters
• Message length is max 999 characters

Messaging API

Regular messages

TPS sends message to Rogerthat user

Request to https://rogerth.at/api/1

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send",
    "params": {
        "parent_message_key": null,
        "message": "Our yearly Christmas party starts tonight at 7.",
        "answers": [
            {
                "id": "yes",
                "caption": "I will attend",
                "action": null,
                "type": "button",
                "ui_flags": 1
            },
            {
                "id": "no",
                "caption": "I will not attend",
                "action": null,
                "type": "button",
                "ui_flags": 0
            },
            {
                "id": "maybe",
                "caption": "Not sure yet",
                "action": null,
                "type": "button",
                "ui_flags": 0
            },
        ],
        "flags": 16,
        "dismiss_button_ui_flags": 0,
        "alert_flags": 0,
        "members": [
            "john@example.com",
            "pete@example.com",
            { "member": "silent@example.com", "alert_flags":1 }
        ],
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "tag": "37AAF801-CE21-4AC5-9F43-E8E403E1EB5F",
        "context": null
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}

• parent_message_key: nullable field
  • in case of a new message thread (= conversation), this field is null
  • in case this message is part of a message thread (= conversation), it is the id of the first message of the thread
  • Note: in case a TPS sends a message in response to a user “poke” action, do not confuse parent_message_key with the poke tag. The parent_message_key should typically be null since you probably want to start a new conversation when the user pokes.
• message: message text (max 500 characters)
• answers: array of answer definitions
  • id: id of the answer definition, which will be used when the answer is posted back to the service when the users answers the message via the predefined answer controls
  • caption: the text associated with the predefined answer control
  • action: associated action with the predefined answer control. The action is executed when the Rogerthat user presses the button. The following URI types are possible:
    • tel://+123456789 will start a phone call to the phone number specified in the URI
    • http(s)://www.example.com will open a browser loading the URI
    • geo://37.882832,-122.265283 will open Google maps at the specified GPS coordinates. You can easily find GPS coordinates of a location of your choice as follows:
      • Browse with your laptop or desktop to maps.google.com
      • Choose or search a location in the world
      • Once found, press right mouse button and choose menu option “What’s here?”
      • The GPS coordinates of your location appear in the Google search box
    • mailto://info@mobicage.com?cc=support@mobicage.com&subject=Email%20title&body=This%20is%20the%20body will open your email client with a preformatted email that you can complete and submit. In this example, the following fields are populated:
      • To is info@mobicage.com – this is the email address between mailto:// and ?
      • Cc is support@mobicage.com
      • Subject is “Email title” – note the %20 which represents a space
      • Body is “This is the body”
    • confirm://Please confirm that you will purchase the goods for $199 allows the user to confirm his choice with a customizable confirmation dialog text.
  • type: the type of widget used to display the predefined answer. The only supported type is button
  • ui_flags: indicates how the mobile device will visualize the transition between this message and the next, requiring less clicks from the user.
    • FLAG_WAIT_FOR_NEXT_MESSAGE = 1 commands the phone UI to wait a few seconds for a follow up message. If that message comes, phone UI will show a smooth transition between this message and the next. If the message does not come in time, the phone will show a popup indicating that the user has to be patient and wait for this next message. Meanwhile, the phone UI will jump back to the service home screen.
    • In case the value is 0 or ui_flags are omitted, the phone will not wait for the next message and the UI will jump back to the service home screen
• dismiss_button_ui_flags is the ui_flags for the dismiss (Roger that) button. See documentation of ui_flags semantics
• flags: bitwise combination of the following list of flags. In case of a reply, this field is ignored, and the flags are copied from the parent message (i.e. from the message to which this message is a reply)
  • FLAG_ALLOW_DISMISS = 1
    Defines whether the members of the message can dismiss the message without choosing one of the predefined answers.
  • FLAG_SHARED_MEMBERS = 16
    Defines whether the members of the message can see each other as members of the message. This also changes the behavior of replies. If a message does not have the FLAG_SHARED_MEMBERS flag, replies are sent to the sender of the message only; otherwise all message participants (i.e. the sender and the original recipients) will receive replies and one-click-responses from all other participants.
  • FLAG_AUTO_SEAL = 64
    If a message has the flag FLAG_AUTO_SEALED, then members will only have the ability to answer once.
• alert_flags: bitwise OR of the following values
  • By default no flags are set (alert_flags = 0). A short beep is played when a message arrives an the device of the user.
  • ALERT_FLAG_SILENT = 1
    Regardless of other alert flag combinations, the receiving Rogerthat device will not make any sound.
  • ALERT_FLAG_VIBRATE = 2
    Defines whether capable receiving devices should vibrate or not.
  • ALERT_FLAG_RING_5 = 4
    Defines that the receiving device should ring for 5 seconds unless the message is acknowledged or locked.
  • ALERT_FLAG_RING_15 = 8
    Defines that the receiving device should ring for 15 seconds unless the message is acknowledged or locked.
  • ALERT_FLAG_RING_30 = 16
    Defines that the receiving device should ring for 30 seconds unless the message is acknowledged or locked.
  • ALERT_FLAG_RING_60 = 32
    Defines that the receiving device should ring for 60 seconds unless the message is acknowledged or locked.
  • ALERT_FLAG_INTERVAL_5 = 64
    Defines that the receiving device should repeat the alert with a 5 seconds pause interval until the message is acknowledged or locked. This flag is only applicable if flag ALERT_FLAG_SILENT is not set.
  • ALERT_FLAG_INTERVAL_15 = 128
    Defines that the receiving device should repeat the alert with a 15 seconds pause interval until the message is acknowledged or locked. This flag is only applicable if flag ALERT_FLAG_SILENT is not set.
  • ALERT_FLAG_INTERVAL_30 = 256
    Defines that the receiving device should repeat the alert with a 30 seconds pause interval until the message is acknowledged or locked. This flag is only applicable if flag ALERT_FLAG_SILENT is not set.
  • ALERT_FLAG_INTERVAL_60 = 512
    Defines that the receiving device should repeat the alert with a 1 minute pause interval until the message is acknowledged or locked. This flag is only applicable if flag ALERT_FLAG_SILENT is not set.
  • ALERT_FLAG_INTERVAL_300 = 1024
    Defines that the receiving device should repeat the alert with a 5 minute pause interval until the message is acknowledged or locked. This flag is only applicable if flag ALERT_FLAG_SILENT is not set.
  • ALERT_FLAG_INTERVAL_900 = 2048
    Defines that the receiving device should repeat the alert with a 15 minute pause interval until the message is acknowledged or locked. This flag is only applicable if flag ALERT_FLAG_SILENT is not set.
  • ALERT_FLAG_INTERVAL_3600 = 4096
    Defines that the receiving device should repeat the alert with a 1 hour pause interval until the message is acknowledged or locked. This flag is only applicable if flag ALERT_FLAG_SILENT is not set.
• members: array of members. A member can be a string containing the member email address, or can be a JSON object containing the member email address and specific alert flags: members: ["john@example.com", { "member":"pete@example.com", alert_flags:1 } ]
• branding: branding key of a branding zip that was submitted in the branding control panel. For more information check out how to customize message look and feel
• tag: an optional string which is sent back together with each update of the message.
• context: an optional string which should be used in case this message is sent as a response to a user poke action. This way the user experience is smoother. The context must be identical to the one received in the messaging.poke incoming API call.

Response in case of success:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": "145ca7eb-eb46-474b-bad8-d27dd6a38a49",
    "error": null,
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}

result: The key which is assigned to this new message

Response in case of error:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{"error": {
            "member": "user@example.com",
            "message": "Member is not in your friends list.",
            "code": 30000
          },
 "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869",
 "result": null}

TPS receives message update

After the service has sent a message to some of its friends, Rogerthat is going to notify the service about member updates throughout the lifetime of the message.

Possible member status updates:

• Member has received the message. If the member does not have a mobile phone registered, it means that the member has received the message in its web browser. Otherwise, it means that the message has been delivered to the mobile phone of the member.
• Member has answered the message via one of the supplied predefined answers.

Example request:

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "messaging.update",
    "params": {
        "status": 3,
        "answer_id": null,
        "received_timestamp": 1301396903,
        "member": "john@example.com",
        "message_key": "7bcc1b94-c193-47bf-ae85-157565ac0e78",
        "parent_message_key": null,
        "tag": "37AAF801-CE21-4AC5-9F43-E8E403E1EB5F",
        "acked_timestamp": 1301397124
    },
    "id": "xxx123abc"
}

• status: bitwise combination of the following statuses:
  • STATUS_RECEIVED = 1
    Received by the supplied member
  • STATUS_ACKED = 2
    Answered by the supplied member
• answer_id: id of the supplied predefined answers in the messaging.send API call. null means “dismissed” i.e. the user clicked on the “Roger That” button
• received_timestamp: UTC epoch when the message was received
• member: Message member email address
• message_key: The Rogerthat key of the message, returned by the messaging.send API call
• parent_message_key: The Rogerthat key of the parent message, or null if there is no parent message
• tag: The tag which was send with the message by the service in the messaging.send API call
• acked_timestamp: UTC epoch when the message was answered

Response in case of success:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": null,
    "id": "xxx123abc"
}

Form messages

Sending a form

The JSON-RPC method is messaging.send_form

The parameters are:

• member: user to whom the form is sent
• parent_message_key: refer to messaging.send
• flags: currently not used
• alert_flags: refer to messaging.send
• branding: refer to messaging.send
• message: refer to messaging.send
• tag: refer to messaging.send
• context: refer to messaging.send
• form: JSON object containing the form details
  • type: string indicating form type
  • positive_button: string caption of the green (Submit) button
  • positive_confirmation: optional string containing green button confirmation dialog text
  • positive_button_ui_flags: ui behaviour when user clicks green button. See documentation of ui_flags semantics
  • negative_button: string caption of the red (Abort) button
  • negative_confirmation: optional string containing red button confirmation dialog text
  • negative_button_ui_flags: ui behaviour when user clicks red button. See documentation of ui_flags semantics
  • widget object containing specific form settings for this form type

Forms can only be sent to one recipient, always have one interactive widget plus a green and red button. Users can submit the form only once, i.e. forms are always autolocked.

Here is an example how to send a text input form:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send_form",
    "id": "jsonrpc id 19347819",
    "params": {
        "member": "john@example.com",
        "parent_message_key": null,
        "flags": 0,
        "alert_flags": 0,
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "message": "Welcome to\nPete's Readers Circle.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "text_line",
            "positive_button": "Next question",
            "positive_button_ui_flags": 1,
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "negative_button_ui_flags": 0,
            "widget": {
                "max_chars": 30,
                "place_holder": "Enter member ID",
                "value": null
            }
        }
    }
}

The response in case of success:

Response:
HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": "4d2e8c4b-b23a-4b5b-86b3-368158aa64fe",
    "id": "jsonrpc id 19347819",
    "error": null
}

• result: The message key to this form
• error: error object or null in case of success

Form received callback

When the form arrives at the device of the user, a first callback is generated. This is identical to the update of a message with buttons. The status is 1, which indicates STATUS_RECEIVED:

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "params": {
        "status": 1,
        "received_timestamp": 1324658438,
        "message_key": "4d2e8c4b-b23a-4b5b-86b3-368158aa64fe",
        "parent_message_key": null,
        "member": "john@example.com",
        "tag": "my message tag19347819",
        "acked_timestamp": 0,
        "answer_id": null
    },
    "method": "messaging.update",
    "id": "ddc8d4e1-2d84-11e1-a8b3-1d3db0dd1263"
}

Form updated callback

When a user pushes the green or red button of a form, the TPS receives a messaging.form_update callback:

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "params": {
        "status": 3,
        "received_timestamp": 1324658438,
        "message_key": "4d2e8c4b-b23a-4b5b-86b3-368158aa64fe",
        "parent_message_key": null,
        "member": "carl.dhalluin@gmail.com",
        "tag": "my message tag19347819",
        "form_result": {
            "type": "unicode_result",
            "result": {
                "value": "member id 1234"
            }
        },
        "acked_timestamp": 1324659262,
        "answer_id": "positive"
    },
    "method": "messaging.form_update",
    "id": "cad40007-2d86-11e1-87a6-1d3db0dd1263"
}

• method: is messaging.form_update
• member: the email address of the Rogerthat user who received or answered this form
• status: is 3 (flags STATUS_RECEIVED and STATUS_ACKED are both set)
• received_timestamp: UTC timestamp when the user received the form
• acked_timestamp: UTC timestamp when the user submitted the form
• message_key: message key of this form
• parent_message_key: key of the parent message of this form, or null if there is no parent message
• tag: tag that was included when the form was sent
• answer_id: is positive for the green button, negative for the red button
• form_result: is an object containing the results of this form. This object is set if the user pressed the green (positive) button. It is null in case the user pressed the red (negative) button. Its content is:
  • type is the type of form result. The following types are possible:
    • type unicode_result refers to a single unicode string (e.g. for text_line, text_block, auto_complete or single_select)
    • type unicode_list_result refers to a list of unicode strings (e.g. for multi_select)
    • type float_result refers to a single float (e.g. for single_slider)
    • type float_list_result refers to a list of floats (e.g. for range_slider)
  • result contains the result
    • value contains the string or float result for types unicode_result or float_result
    • values contains the string list or float list for types unicode_result or float_result

Warning: do not confuse the keys for float or string result “value” and float list or string list result “values”

Form widget: Range slider

A slider which allows the user to select a range or an interval.

• form type is range_slider
• widget min: leftmost value of slider (integer or float)
• widget max: rightmost value of slider (integer or float)
• widget step: interval between valid slider values (integer or float)
• widget low_value: initial low value of slider (integer or float)
• widget high_value: initial high value of slider (integer or float)
• widget precision: number of decimal digits (default 0)
• widget unit: format string in which <low_value/> and <high_value> are substituted

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send_form",
    "id": "jsonrpc id 19347819",
    "params": {
        "member": "john@example.com",
        "parent_message_key": null,
        "flags": 0,
        "alert_flags": 0,
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "message": "What time can we deliver your order?",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "range_slider",
            "positive_button": "Submit",
            "negative_button": "Abort",
            "negative_confirmation": "Do you really want to abort?",
            "widget": {
                "min": 1,
                "max": 6,
                "step": 1,
                "low_value": 1,
                "high_value": 6,
                "precision": 2,
                "unit": "Between <low_value/>pm - <high_value/>pm"
            }
        }
    }
}

The TPS receives a HTTP response which contains the message key in the result field:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "error": null,
    "result": "fc7be1e2-14f0-4b29-8f04-6b3d9cb6b056",
    "id": "jsonrpc id 19347819"
}

When the message arrives on the phone of the user, the services receives a first callback method messaging.update. Relevant fields are:

• received_timestamp: timestamp (millis since 1 Jan 1970) at which the form arrived on the user phone
• message_key: message key of the form
• member: Rogerthat user to which this form was sent
• tag: form tag

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "messaging.update",
    "id": "3e3a558c-2be7-11e1-9a5d-e9db33d7dba9"
    "params": {
        "status": 1,
        "received_timestamp": 1324480774,
        "message_key": "fc7be1e2-14f0-4b29-8f04-6b3d9cb6b056",
        "parent_message_key": null,
        "member": "john@example.com",
        "tag": "my message tag19347819",
        "acked_timestamp": 0,
        "answer_id": null
    }
}

When the user selects a value for the range slider, this value is sent in a second callback method message.form_update – relevant fields are:

• acked_timestamp: timestamp (millis since 1 Jan 1970) at which the user sent an answer
• message_key: message key of the form
• member: Rogerthat user to which this form was sent
• tag: form tag
• form_result
  • type: is float_list_result
  • result: object containing values which is a list of 2 floats

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "params": {
        "status": 3,
        "received_timestamp": 1324480774,
        "acked_timestamp": 1324480788,
        "message_key": "fc7be1e2-14f0-4b29-8f04-6b3d9cb6b056"
        "parent_message_key": null,
        "member": "carl.dhalluin@gmail.com",
        "tag": "my message tag19347819",
        "answer_id": "positive",
        "form_result": {
            "type": "float_list_result",
            "result": {
                "values": [
                    2.0,
                    3.0
                ]
            }
        },
    },
    "method": "messaging.form_update",
    "id": "623a0099-2be7-11e1-b111-e9db33d7dba9"
}

Form widget: Single line text input

A single line of text input.

• form type is text_line
• widget max_chars: maximum number of characters in input field
• widget place_holder: hint shown in input field
• widget value: initial text

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send_form",
    "id": "jsonrpc id 19347819",
    "params": {
        "member": "john@example.com",
        "parent_message_key": null,
        "flags": 0,
        "alert_flags": 0,
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "message": "Welcome to\nPete's Readers Circle.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "text_line",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "max_chars": 30,
                "place_holder": "Enter member ID",
                "value": null
            }
        }
    }
}

Form widget: Text block

A multi-line text input box.

• form type is text_block
• widget max_chars: maximum number of characters in input field
• widget place_holder: hint shown in input field
• widget value: initial text

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send_form",
    "id": "jsonrpc id 19347819",
    "params": {
        "member": "john@example.com",
        "parent_message_key": null,
        "flags": 0,
        "alert_flags": 0,
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "message": "Do you have remarks on our customer service?",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "text_block",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "max_chars": 100,
                "place_holder": "Enter remarks",
                "value": null
            }
        }
    }
}

Form widget: Text autocomplete

A text autocomplete widget allows users to enter one line of text.

• form type is auto_complete
• widget max_chars: maximum number of characters in input field
• widget place_holder: hint shown in input field
• widget value: initial text
• widget suggestions: list of strings that will create the autocomplete suggestion

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send_form",
    "id": "jsonrpc id 19347819",
    "params": {
        "member": "john@example.com",
        "parent_message_key": null,
        "flags": 0,
        "alert_flags": 0,
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "message": "Who is your favourite author?",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "auto_complete",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "max_chars": 30,
                "place_holder": "Enter author",
                "value": null,
                "suggestions": ["Shakespeare", "Steve Jobs", "Suzanne Collins"]
            }
        }
    }
}

Form widget: Slider

A slider.

• form type is single_slider
• widget min: leftmost value of slider (integer or float)
• widget max: rightmost value of slider (integer or float)
• widget step: interval between valid slider values (integer or float)
• widget value: initial value of slider (integer or float)
• widget precision: number of decimal digits (default 0)
• widget unit: format string in which <value/> is substituted with the slider value

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send_form",
    "id": "jsonrpc id 19347819",
    "params": {
        "member": "john@example.com",
        "parent_message_key": null,
        "flags": 0,
        "alert_flags": 0,
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "message": "How much would you pay for this service?",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "single_slider",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "min": 0,
                "max": 10,
                "step": 0.5,
                "value": 5,
                "precision": 2,
                "unit": "$<value/> per month"
            }
        }
    }
}

Form widget: Select single item

A list of items from which the user can select a single item (also called “radio button”).

• form type is single_select
• widget choices is a list of at least 2 objects having a value and a label
• widget value is the initial selected value which can be null

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send_form",
    "id": "jsonrpc id 19347819",
    "params": {
        "member": "john@example.com",
        "parent_message_key": null,
        "flags": 0,
        "alert_flags": 0,
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "message": "What is your favourite literary genre?",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "single_select",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "value": "1",
                "choices": [
                    {"value": "1", "label": "Fiction"},
                    {"value": "2", "label": "Non-fiction"}
                ]
            }
        }
    }
}

Form widget: Select multiple items

A list of items from which the user can select multiple items (also called “checkboxes”).

• form type is multi_select
• widget choices is a list of objects having a value and a label
• widget values is a list containing the initially selected values

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.send_form",
    "id": "jsonrpc id 19347819",
    "params": {
        "member": "john@example.com",
        "parent_message_key": null,
        "flags": 0,
        "alert_flags": 0,
        "branding":
            "A68EBEAB5C962B271BD236AAE6595E5C353B56A650F98B760026CAFA094DB8D1",
        "message": "Which fiction do you like?",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "multi_select",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "values": ["1", "2"],
                "choices": [
                    {"value": "1", "label": "Romance"},
                    {"value": "2", "label": "Horror"},
                    {"value": "3", "label": "Whodunit"}
                ]
            }
        }
    }
}

TPS seals message or form

When Rogerthat users receive a message they can be presented a number of predefined answers. Rogerthat users can change their answer until the message is sealed. Only the sender can seal the message.

Example request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.seal",
    "params": {
        "message_key": "b50d2ea1-3d43-47ab-8d1b-0ea94f5cfa77",
        "parent_message_key": null,
        "dirty_behavior": 1
    },
    "id": "AB6E5F53-9DE4-4357-8FFE-37BEDF2D4FC3"
}

• message_key: Rogerthat message key
• parent_message_key: Rogerthat message parent key. This is null for a new message. In case of a reply, this is the message key of the parent message.
• dirty_behavior: enumeration
  • NORMAL = 1
    Clients will not change the dirty flag of the message except when the message was not viewed yet by the user. In this case the message will be flagged as dirty.
  • MAKE_DIRTY = 2
    Clients will flag the message as dirty after the message is locked.
  • CLEAR_DIRTY = 3
    Clients will flag the message as not dirty after the message is locked.

Response in case of success:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": null,
    "id": "AB6E5F53-9DE4-4357-8FFE-37BEDF2D4FC3"
}

Response in case of error:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": {
        "code": 30009,
        "message": "Message not found!",
        "member": "john@example.com"
    },
    "id": "AB6E5F53-9DE4-4357-8FFE-37BEDF2D4FC3"
}

TPS receives user poke

Users can take the initiative to start a communication with a service. There are several possibilities:

• User taps on an item on the service menu
• User scans an action QR produced by a service

The service will be informed using a callback:

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "messaging.poke",
    "params": {
        "email": "john@example.com",
        "tag": "buy_coffee_brazilian_22",
        "context": "MENU_68efb3bd-8470-4b06-92bf-3feaab457ae6"
    },
    "id": "xxx123abc"
}

Parameters:

• email account of the user who started the interaction
• tag that the service “baked” into the a QR code or service menu item
• context identifier must be returned in a follow-up message or message flow. The user UI will show a spinner and wait for such a follow-up.

Check the PHP example code to see how a messaging.poke callback can be used to launch a message flow.

Message flows

Check the Message Flow Designer guide to find out how to graphically design and manage your message flows.

Launch message flow

We will work with the following example message flow:

In the service panel you can retrieve the list of message flow definitions. The Id column identifies a message flow definition. Use the call messaging.start_flow can launch such a message flow to one or more users.

This is the API call to launch a message flow:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "messaging.start_flow",
    "id": "ce74a4f6-23ef-4c8d-ad60-4b7d5114218b",
    "params": {
        "parent_message_key": null,
        "flow": "ahNkZXZ-bW9iaWNhZ2VjbG91ZGhycj0LEgptYy10cmFja2VyIgxjYXJsQGNhcmwuYmUMCxIRTWVzc2FnZUZsb3dEZXNpZ24iCnJlc3RhdXJhbnQM",
        "tag": "my flow tag 0001",
        "context": null,
        "members": [
            "john@example.com"
        ]
    }
}

• parent_message_key: optional parent message key for this message flow
• flow: id of the flow definition, which you can get in the message flow list in the service panel (see screenshot above)
• tag: tag associated with this flow run, will be reported in the callback
• context: an optional string which should be used in case this message flow is started as a response to a user poke action. This way the user experience is smoother. The context must be identical to the one received in the messaging.poke incoming API call.
• members: list of members to whom the message flow is launched

The result:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": "1516f2a4-aefc-490c-b1e7-76ae631391f4",
    "id": "ce74a4f6-23ef-4c8d-ad60-4b7d5114218b",
    "error": null
}

• result: flow run id, which will be used when the message flow result is posted

Get message flow result

Each time the entire message flow run of an individual member finishes, the Rogerthat platform will send a callback to your service. This means that for each launched message flow, you will receive up to one callback for each member of the launched flow. If the recipient never finishes the flow, you will never get a callback.

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "messaging.flow_member_result",
    "id": "f45b180c-691f-11e1-a23b-b981921903bf",
    "params": {
        "message_flow_run_id": "1516f2a4-aefc-490c-b1e7-76ae631391f4",
        "member": "john@example.com",
        "end_id": "end_join",
        "end_message_flow_id": "ahNkZXZ-bW9iaWNhZ2VjbG91ZGhycj0LEgptYy10cmFja2VyIgxjYXJsQGNhcmwuYmUMCxIRTWVzc2FnZUZsb3dEZXNpZ24iCnJlc3RhdXJhbnQM",
        "parent_message_key": "27f078da-7398-4cc4-be5b-4fc81f67c959",
        "tag": "my flow tag 0001",
        "steps": [
            {
                "received_timestamp": 1331212149,
                "message_flow_id": "ahNkZXZ-bW9iaWNhZ2VjbG91ZGhycj0LEgptYy10cmFja2VyIgxjYXJsQGNhcmwuYmUMCxIRTWVzc2FnZUZsb3dEZXNpZ24iCnJlc3RhdXJhbnQM",
                "step_type": "message_step",
                "step_id": "message_welcome",
                "acknowledged_timestamp": 1331212162,
                "answer_id": "button_yes"
            },
            {
                "received_timestamp": 1331212164,
                "message_flow_id": "ahNkZXZ-bW9iaWNhZ2VjbG91ZGhycj0LEgptYy10cmFja2VyIgxjYXJsQGNhcmwuYmUMCxIRTWVzc2FnZUZsb3dEZXNpZ24iCnJlc3RhdXJhbnQM",
                "step_type": "form_step",
                "step_id": "message_price",
                "answer_id": "positive",
                "form_result": {
                    "type": "float_list_result",
                    "result": {
                        "values": [
                            30.0,
                            50.0
                        ]
                    }
                },
                "acknowledged_timestamp": 1331212173
            }
        ]
    }
}

• message_flow_run_id: id that was returned in the result of the messaging.start_flow call
• member: email address of the user
• end_id: id of the end state of the message flow run of this user. In this case, the service administrator gave the end box the id “join”. It is reported as “end_join” i.e. the id is prepended with “end_”
• end_message_flow_id: id of the message flow that contains the end step. This is primarily useful in cases where your message flow includes subflows.
• parent_message_key: effective parent message key of this message flow. In case a parent_message_key was given during messaging.start_flow, this field contains the same value. If no such key was given during messaging.start_flow, this field will contain the message key of the first message of the flow run.
• tag: tag that was associated to this message flow run
• steps: ordered sequence of steps executed by the user. Each step has the following properties:
  • step_id: id of a step in your message flow definition, prepended with “message_”
  • message_flow_id: id of the message flow that contains this step. Primarily useful in cases where your message flow includes subflows.
  • step_type: will be message_step for messages with buttons, and form_step for forms such as sliders, text input boxes, single and multi select…
  • answer_id: the id of the button pressed by the user when answering this message.
    • If your button id is “yes” it will be reported as “button_yes” i.e. “button_” will be prepended to your chosen id
    • Will be null in case the user pressed the Roger That button
    • For forms: will be positive in case the user presses the green button
    • For forms: will be negative in case the user presses the red button
  • form_result: result of the form input. This is only available for step_type “form_step” and only in case the user pressed the green button i.e. answer_id is positive. Refer to the messaging.form_update documentation
  • received_timestamp: timestamp when the user received this message
  • acknowledged_timestamp: timestamp when the user responded to this message

Note that the ids of the steps, buttons, and end states that were designed in the Message Flow Designer, will be prepended respectively with message_, button_ and end_

List message flows

You can list all the message flows that you defined in the self-service panels.

Example request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "system.list_message_flows",
    "params": { },
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D"
}

Example response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "error": null,
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D",
    "result": "result": [
                          {"identifier"    : "ahFzfm1vYmljYWdlY2x",
                           "name"          : "make_appointment",
                           "last_modified" : 1347536542},
                          {"identifier"    : "ahFzfm1vYmljYWdlY45",
                           "name"          : "customer_service",
                           "last_modified" : 1341237253},
                        ]
}

The result is a list of message flows. For each message flow you get an identifier, name, and a timestamp when the message flow was last_modified. The identifier can be used to launch the message flow.

Friends API

TPS service invites Rogerthat user

TPS services can invite Rogerthat users to become friends. The invitee receives a system message explaining that the TPS wants to become friends. This invitation contains two buttons: Accept invitation and Decline invitation.

When the invitee clicks one of these buttons the service is notified via the service callback method receive invitation result.

In case the invitee is not yet a Rogerthat user, he receives an email in which he is invited to become a Rogerthat user on behalf of the service. Once he is registered, he is friends with the TPS.

Example request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "friend.invite",
    "params": {
        "email": "test@example.com",
        "name": "John Doe",
        "message": "This is the official message feed of ACME Corp",
        "tag": "725985B4-B805-4F02-9971-FE61A60F9D27",
        "language": "en"
    },
    "id": "86754A03-0531-49E3-96F6-76EEDC005274"
}

• email: Rogerthat user account of invitee
• name: name of the invitee. Can be null
• message: a personal message included in the invitation message
• language: language of the invitee. Currently only en is supported
• tag: an optional string which is sent back together with the result of the invitation. This is typically used to link the identity of the user in the TPS to the identity of the user in Rogerthat. It is up to the TPS to choose a tag value

Response in case of success:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": null,
    "id": "86754A03-0531-49E3-96F6-76EEDC005274"
}

Response in case of error:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": {
        "code": 20000,
        "message": "email address is not valid!"
    },
    "id": "86754A03-0531-49E3-96F6-76EEDC005274"
}

Restrictions:

• A service can not keep sending invitations to the same Rogerthat user.

TPS receives user friendship status update

This callback is invoked in two scenarios:

• A user responds to an invitation that was sent by a TPS. The service will receive friend.invite_result with result value accepted or declined
• A user has been connected to a service in another way. The service will receive friend.invite_result with result value established. Some typical scenarios
  • User scans a Rogerthat QR code of a TPS service to which he is not yet connected. The TPS will receive a friend invitation which he accepts. Quickly after, the TPS will receive the message that the user-to-service connection is established
  • User connects to service by explicitly connecting to the service email address. Again, the TPS will receive a friend invitation which he accepts. Quickly after, the TPS will receive the message that the user-to-service connection is established

Note: when a user decides to break his connection to a TPS, a separate friend.break_up callback is used.

Example callback:

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "friend.invite_result",
    "params": {
        "result": "accepted",
        "email": "john@example.com",
        "origin": "service_invite",
        "tag": "725985B4-B805-4F02-9971-FE61A60F9D27"
    },
    "id": "xxx0109"
}

• result: accepted or declined or established
• email: Rogerthat user account of friend. This email address will be used for all future communication with that user
• origin and tag: indicates how this invitation was realized:
  • origin = service_invite – the service invited a Rogerthat user using the friend.invite call. The tag in the friend.invite_result callback is the one that was included in the original friend.invite call
  • origin = user_poke – the user scanned a QR code of a service to which he was not yet connected. result = established. The tag contains the poke tag that was included in the QR code
  • origin = user_invite – this is the second step in the handshake when a user explicitly invites a service using the service e-mail address

Successful response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "result": null,
    "error": null,
    "id": "xxx0109"
}

It is important to understand in which cases a welcome message should be sent to the user. Check the sequence diagrams for more info. A rule of thumb:

• If the origin field in the friend.invite_result equals user_invite and the status is established then a welcome message should be sent to the user
• If the origin field in the friend.invite_result equals service_invite then a welcome message is probably appropriate (see below)
• If the origin field in the friend.invite_result equals user_poke then a welcome message is probably not appropriate, since very quickly after, the service will receive a messaging.poke callback (see below)

TPS breaks friendship

If the TPS service no longer wants to interact anymore with an existing friend, the TPS can break the friendship relation. Immediately after this call, messaging is no longer possible between the service and the friend in either direction.

Example request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "friend.break_up",
    "params": {
        "email": "john@example.com"
    },
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D"
}

email is the Rogerthat user account that will be unfriended

Response format in case of success:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": null,
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D"
}

Response format in case of error:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": {
        "code": 20000,
        "message": "Invalid email address"
    },
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D"
}

TPS receives friend invitation

When a Rogerthat user takes the initiative to become friend with a TPS, the TPS can accept or refuse this. Rogerthat will post a JSON-RPC request to the TPS callback URL.

Example request

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "friend.invited",
    "params": {
        "email": "john@example.com",
        "name": "John Doe",
        "language": "en",
        "message": null,
        "origin": "user_invite",
        "tag": null
    },
    "id": "7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}

• email: email address of the user that wants to become friends with the TPS
• name: name of the user
• language: language of the user (two letter ISO 639-1 code)
• message: freetext message entered by the user when he connects to the service e.g. by explicitly connecting to the service email address using his mobile or in browser
• origin and tag: indicates how this invitation was realized:
  • origin = user_invite: The user explicitly typed in the service e-mail address. tag is null
  • origin = user_poke: The user scanned a QR code of a service to which he was not yet connected. The tag is the one that is included in the QR code.
  • origin = user_recommended: The user accepted a recommendation of this service by one of his Rogerthat contacts.

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": "accepted",
    "error": null,
    "id": "7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}

result is “accepted” or “declined”

Warning: when the TPS has answered accepted, the Rogerthat user is not immediately connected to your service. You have to wait for the friend.invite_result callback to be sure that the relation between the user and the TPS has been established. Only after this moment, you can start sending messages to that user.

Warning: If a service explicitly invites a user, and the user accepts, the service will not receive a friend invitation. Instead, it will immediately receive the friend.invite_result callback.

TPS receives break friendship request

When a Rogerthat user wants to end communication with a service, the TPS will be notified of this fact.

Example request:

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-Service-Key: your_secret_service_key

{
    "method": "friend.broke_up",
    "params": {
        "email": "john@example.com"
    },
    "id": "7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}

email is the Rogerthat user account of the user that broke friendship

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": null,
    "error": null,
    "id": "7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}

TPS retrieves status of a user

The TPS can query the status of a user. The status information contains:

• Whether the user is connected to the service. If a user is not connected to a TPS, that TPS cannot communicate with the user.
• When the user was last online using Rogerthat Messenger.

Example request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "friend.get_status",
    "params": {
        "email": "john@example.com"
    },
    "id": "json rpc id 7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}

• email is the Rogerthat user account of the user

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "result": {
        "is_friend": true,
        "name": "John Smith",
        "language": "en",
        "avatar": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4023007",
        "last_heartbeat": 1327486564,
    },
    "error": null,
    "id": "json rpc id 7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}

• name: Full name of the Rogerthat user
• is_friend: boolean indicating if the user is connected to your service. Can be true or false
• language: two-letter ISO-639 language string
• avatar: URL pointing to the profile picture of this user
• last_heartbeat: timestamp of the last heartbeat between the user and the Rogerthat gateway. Timestamp is in seconds since 1 Jan 1970 UTC. For example, the timestamp of the example (1327486564) corresponds to Wed, 25 Jan 2012 10:16:04 GMT. Check this online conversion tool.

Caveats:

• For users who are not connected to your service, the value for last_heartbeat is 0.
• For email addresses that do not correspond to Rogerthat users, the values for name, language and avatar will be null

Warning: avoid TOCTOU bugs in your code! A user might disconnect from your service between the get_status call, and a follow-up call such as sending a message. You must be prepared to deal with error code 30000 (Member is not in your friends list) when sending a message.

Screen Branding API

Upload Screen Branding

A screen branding defines the look and feel of Rogerthat content offered by a Rogerthat service. For example messages sent by a service, the service home screen, the service about page, or static content behind a service home screen item.

Check the screen branding guide to find out how to create a screen branding archive file and upload it using the service control panels.

To upload a branding via the API, the content of the zip file must be base64-encoded and the following API request must be used:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "system.store_branding",
    "params": {
        "description": "My nice branding",
        "content": "UEsDBBQAAAAIAC56/0BVPSINsgAAAPwAAAANABwAYnJhbmRpbmcuaHRtbFVUCQAD59oXUOnaF1B1eAsAAQT1AQAABBQAAABVj8EOgyAQRO98BeFuiLdGwUt/wXuDshVSBAtLrf36QkwPTfaymXmzs8Lg6gZChAGlB0LFCqioQdwaeGb7kuwaPILHZjw2YHQ+N8kQ3sgr3NPZqJgAZcZ7c2F8IIKfaURMQR804eFAsknNjyWG7HUXQfesXjPtT52DC7HbjUUo0mhsomUURUhIp6i8tn4pwW3F0qb8P3iAc2EvpPDZo82f2wopqQX4IHi111a1TW3Fz6e/UEsBAh4DFAAAAAgALnr/QFU9Ig2yAAAA/AAAAA0AGAAAAAAAAQAAAKSBAAAAAGJyYW5kaW5nLmh0bWxVVAUAA+faF1B1eAsAAQT1AQAABBQAAABQSwUGAAAAAAEAAQBTAAAA+QAAAAAA",
    },
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D"
}

• description: description of your screen branding
• content: base64 encoding of the branding archive zip file

The result contains the id of your branding, which can for example be used for sending messages or forms.

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "error": null,
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D",
    "result": {
        "id": "BB049301E7283B6B691C9A6CE1E429D8FEA7F51684CFD19F205B47F5266D0D10"
    }
}

• id: the id of your branding. Note: take the “id” field inside the “result” object!

QR Code API

Create QR Code from QR Code Template

QR Code templates are configured in the Service Control Panel menu QR Code Branding. For more details refer to QR Code Management.

QR Codes can be generated from a QR Code template in 2 ways:

• In the Service Control Panel menu QR Code Branding by clicking create new QR Code from this template
• Using the API

Example request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key

{
    "method": "qr.create",
    "params": {
        "description": "Order Sandwich",
        "tag": "candy_001",
        "template_key": "qr138B"
    },
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D"
}

• description: the name of the action which the user can launch after scanning the QR Code. Example descriptions: “Get information on article Yellow Lego Castle”, “Order sandwich”, “Contact Hospital”, “Register for Discount”
• tag is a unique identification of a QR code. When the user launches an action using a QR Code, the TPS will receive the tag to identify which QR Code the user has scanned.
• template_key is the key of a QR Code template. The key is displayed in the Service Control Panel menu QR Code Branding

The result contains a HTTPS URL of the PNG image of the freshly created QR Code and the content of the QR Code. The content of the QR Code can also be used directly eg embedded in an SMS message to bootstrap an interaction. Opening the content link has the same effect as scanning the QR Code:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8

{
    "error": null,
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D",
    "result": {
        "image_uri": "https://rogerth.at/si/_khNOn7wAqEJooYq_crdcGCclPQ0m8X6ahXC8IP2.1o-/102003",
        "content_uri": "HTTPS://ROGERTH.AT/S/XY/Q1",
        "email_uri": "https://rogerth.at/M/XY/Q1?email",
        "sms_uri": "https://rogerth.at/M/XY/Q1"
    }
}

Result:

• image_uri: URI pointing to the PNG image of the QR code
• content_uri: Content URI. Use this if you want to create your own QR code using a graphical QR code designer tool. Keep this in capitals, it will make your QR code smaller and easier to scan.
• email_uri: URI to embed in an invitation email to your users
• sms_uri: URI to embed in an invitation SMS to your users

Sequence Diagrams

Service Sends Message To User

First the service sends the message to one or more users.

For each recipient user, the service is notified as soon as the message arrives on his mobile device or in his web browser. If the message arrives both in-browser and on a mobile device, the service is only notified of the first event.

Every time a recipient user clicks a response button, or dismisses the message (by clicking “Roger That”), the Service is notified. It is perfectly to receive multiple callbacks for one fixed recipient, e.g. in case he clicks a response button and subsequently clicks another response button.

Finally, the service can seal the message to avoid recipients to answer or change their answer.

Error codes