Contents

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:

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 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,
        "service_identity": "+default+",
        "attachments": [
            {
                "content_type": "image/png",
                "download_url": "http://www.rogerthat.net/wp-content/uploads/2012/09/rogerthat-logo.png",
                "name": "Rogerthat logo",
                "size": 17458
            }
        ]
    },
    "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.
  • service_identity: an optional string which defines service identity. If not provided the message will be sent with the “+default+” identity.
  • attachments: an optional array of attachment definitions refer to data structure

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,
        "service_identity": "+default+",
        "user_details": [
            {
              "email": "john@example.com",
              "name": "John Doe",
              "language": "en",
              "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ]
    },
    "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 sent with the message by the service in the messaging.send API call
  • acked_timestamp: UTC epoch when the message was answered
  • service_identity: The service identity which was sent by the service in the messaging.send API call
  • user_details: array with user information refer to data structure

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
  • service_identity: refer to messaging.send
  • attachments: refer to data structure
  • 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
    • javascript_validation: string with javascript code to validate the result of the form at the moment the user presses the positive button. This code block must contain the method run with one argument, the form result. See messaging.form_update for the possible result types. If the user’s input was not valid the method must return a string containing the error message which will be shown to the user. If the user’s input is valid then the method should return true.
      Here is an example to check if a user has entered something in a text line/block.

              var run = function(result) {
                  if (!result.value) {
                      return "This input field is required";
                  }
                  return true;
              };
              

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,
        "service_identity": "+default+",
        "attachments": [
            {
            "content_type": "image/png",
            "download_url": "http://www.rogerthat.net/wp-content/uploads/2012/09/rogerthat-logo.png",
            "name": "Rogerthat logo",
            "size": 17458
            }
        ],
        "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
            },
            "javascript_validation": "var run = function(result) { return result.value ? true : "Member ID is required"; };"
        }
    }
}

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,
        "service_identity": "+default+",
        "user_details": [
            {
              "email": "john@example.com",
              "name": "John Doe",
              "language": "en",
              "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ]
    },
    "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": "john@example.com",
        "tag": "my message tag19347819",
        "form_result": {
            "type": "unicode_result",
            "result": {
                "value": "member id 1234"
            }
        },
        "acked_timestamp": 1324659262,
        "answer_id": "positive",
        "result_key": "69975c1f-9e97-4e7c-acc7-01ff011753ee",
        "service_identity": "+default+",
        "user_details": [
            {
              "email": "john@example.com",
              "name": "John Doe",
              "language": "en",
              "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ]

    },
    "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
  • result_key: the key of the resulting message when using the High Performance API whith type message
  • service_identity: refer to messaging.update
  • user_details: refer to data structure
  • 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 widget)
      • type unicode_list_result refers to a list of unicode strings (e.g. for multi_select widget)
      • type long_result refers to a single long (e.g. for date_select widget)
      • type float_result refers to a single float (e.g. for single_slider widget)
      • type float_list_result refers to a list of floats (e.g. for range_slider widget)
      • type location_result refers to a location (e.g. for gps_location widget)
      • type mydigipass_result refers to a MYDIGIPASS user (e.g. for mydigipass widget)
    • result contains the result
      • unicode_result, long_result or float_result : value contains the string, long or float result
      • unicode_list_result or float_list_result: values contains the string list or float list
      • location_result contains:

        • latitude: The latitude in degrees.
        • longitude: The longitude in degrees.
        • altitude: The altitude measured in meters.
        • horizontal_accuracy: The radius of uncertainty for the location, measured in meters.
        • vertical_accuracy: The accuracy of the altitude value in meters. -1 if not supported on the user’s device.
        • timestamp: The time at which this location was determined, in seconds since 1 Jan 1970 UTC.
      • mydigipass_result contains:

        • eid_profile: The personality information stored in the user’s eID card. This object is null if the “eid_profile” scope was not requested.

          • first_name (string)
          • first_name_3 (string)
          • last_name (string)
          • gender (string)
          • nationality (string)
          • date_of_birth (string)
          • location_of_birth (string)
          • noble_condition (string)
          • issuing_municipality (string)
          • card_number (string)
          • chip_number (string)
          • validity_begins_at (string)
          • validity_ends_at (string)
          • created_at (string)
        • eid_address: The address information stored in the user’s eID card. This object is null if the “eid_address” scope was not requested.

          • street_and_number (string)
          • zip_code (string)
          • municipality (string)
        • eid_photo: The base64 encoded string containing the eID photo. This object is null if the “eid_photo” scope was not requested.
        • email: The email address stored in the user’s MYDIGIPASS account. This object is null if the “email” scope was not requested.
        • phone: The phone number stored in the user’s MYDIGIPASS account. This object is null if the “phone” scope was not requested.
        • profile: The personality information stored in the user’s MYDIGIPASS account. This object is null if the “profile” scope was not requested.

          • updated_at (string)
          • first_name (string)
          • last_name (string)
          • born_on (string)
          • preferred_locale (string)
          • uuid (string)
        • address: The address information stored in the user’s MYDIGIPASS account. This object is null if the “address” scope was not requested.

          • address_1 (string)
          • address_2 (string)
          • city (string)
          • zip (string)
          • country (string)
          • state (string)

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

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,
        "service_identity": "+default+",
        "user_details": [
            {
              "email": "john@example.com",
              "name": "John Doe",
              "language": "en",
              "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ]
    }
}

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": "john@example.com",
        "tag": "my message tag19347819",
        "answer_id": "positive",
        "form_result": {
            "type": "float_list_result",
            "result": {
                "values": [
                    2.0,
                    3.0
                ]
            }
        },
        "service_identity": "+default+",
        "result_key": "69975c1f-9e97-4e7c-acc7-01ff011753ee",
        "user_details": [
            {
              "email": "john@example.com",
              "name": "John Doe",
              "language": "en",
              "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
         ]
    },
    "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 Pete'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
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type unicode_result.

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
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type unicode_result.

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"]
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type unicode_result.

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.0,
                "max": 10.0,
                "step": 0.5,
                "value": 5.0,
                "precision": 2,
                "unit": "$<value/> per month"
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type float_result.

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.0,
                "max": 6.0,
                "step": 1.0,
                "low_value": 1.0,
                "high_value": 6.0,
                "precision": 2,
                "unit": "Between <low_value/>pm - <high_value/>pm"
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type float_list_result.

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"}
                ]
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type unicode_result.

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"}
                ]
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type unicode_list_result.

Form widget: Select a date

A date picker widget.

  • form type is date_select
  • widget mode is a required string, determining whether dates, times or both are displayed. Possible values:

    • time: The widget display hours and minutes. The result will contain the seconds since midnight.
    • date: The widget displays months, days of the month, and years. The result will contain the seconds between 1 Jan 1970 UTC and midnight of the selected date.
    • date_time: The widget displays dates (as unified day of the week, month, and day of the month values) plus hours and minutes. The result will contain the seconds between 1 Jan 1970 UTC and the selected date.
  • widget max_date is an optional maximum timestamp that the widget can show.
  • widget has_max_date is a boolean determining if max_date must be used.
  • widget min_date is an optional minimal timestamp that the widget can show.
  • widget has_min_date is a boolean determining if min_date must be used.
  • widget minute_interval is an optional interval at which the widget should display minutes. You can use this property to set the interval displayed by the minutes wheel (for example, 15 minutes). The interval value must be evenly divided into 60. The default value is 15; the minimum value is 1; the maximum value is 30.
  • widget unit is the format string in which <value/> is substituted with the selected date.
  • widget date is the initially shown date (in seconds since midnight for mode “time”, otherwise in seconds since 1 Jan 1970 UTC)
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": "Select your date of birth.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "date_select",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "mode": "date",
                "has_max_date": true,
                "max_date": 4102358400,
                "has_min_date": true,
                "min_date": -2208988800,
                "unit": "Date of birth: <value/>",
                "minute_interval": 30,
                "date": 1407715200
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type long_result and contains the seconds between the selected timestamp and midnight, or 1 Jan 1970 UTC, depending on the mode of the widget.

Form widget: Select a friend

A friend picker widget.

  • form type is friend_select
  • widget multi_select is an optional boolean, determining whether one or more friends can be selected. The default value is false.
  • widget selection_required is an optional boolean, determining whether or not the user has to select at least one friend. The default value is true.
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": "Select your family members.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "friend_select",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "multi_select": true,
                "selection_required": true
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type unicode_list_result and contains the email addresses of the selected friends.

Form widget: Uploading a photo

Let the user take a picture or select a photo from his gallery.

  • form type is photo_upload
  • widget gallery is an optional boolean defining if the photo can be choosen from the user’s photo gallery. The default value is false.
  • widget camera is an optional boolean defining if the photo can be taken with the camera. The default value is false.
  • widget quality is an optional string defining the photo’s quality. Possible values are “best”, “user” or a string defining the maximum file size in bytes. The default value is “user”.
  • widget ratio is an optional string defining the width and height ratio. The format is “x“. Set to null to define no ratio. The default value is 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": "Upload a photo of your member card.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "photo_upload",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "camera": true,
                "gallery": false,
                "quality": "1000000",
                "ratio": "800x600"
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type unicode_result and contains the download URL of the selected image.

Form widget: Get location

Get the user’s current location.

  • form type is gps_location
  • widget gps is a boolean to force the use of the user’s GPS.
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": "Submit your current location.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "gps_location",
            "positive_button": "Next question",
            "negative_button": "Stop poll",
            "negative_confirmation": "Do you really want to stop the poll?",
            "widget": {
                "gps": false
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type location_result.

Form widget: Shopping cart

Add items to a shopping cart.

  • form type is advanced_order
  • widget currency is a string containing the currency symbol.
  • widget categories: is an array of categories.

    • id: is a string identifying this category.
    • name: is a string containing the name of this category.
    • items: is an array of items which belong to this category.

      • id: is a string identifying this item.
      • name: is a string with the name of this item.
      • description: is a string with the description of this item.
      • value: is an integer defining how many of this item that are already added to the shopping cart.
      • unit: is a string with the unit in which this item can be ordered (example: kg, l, h, persons…).
      • unit_price: is on optional integer with the price of 1 unit (in cents).
      • step: is an integer defining how much units that are added when the user presses the plus button.
      • step_unit: is an optional unit in case the unit of the steps are different than the unit (Eg. unit = kg, step_unit = g).
      • step_unit_conversion: is an optional integer defining the relation between unit an step_unit (Eg. unit = kg, step_unit = g, step_unit_conversion = 1000).
      • image_url: is an optional string with the link to the picture of this item.
      • has_price: is an optional boolean defining whether or not the price is visible in the app.
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": "Select the books you wish to order.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "advanced_order",
            "positive_button": "Order",
            "negative_button": "Cancel",
            "negative_confirmation": "Are you sure you wish to cancel?",
            "widget": {
                "currency": "$",
                "categories": [{
                    "id": "romance",
                    "name": "Romance",
                    "items": [{
                        "id": "1",
                        "name": "Fifty Shades of Grey",
                        "description": "by E.L. James",
                        "value": 0,
                        "unit": "pc.",
                        "unit_price": 999,
                        "step": 1,
                        "step_unit": "pc.",
                        "step_unit_conversion": 1,
                        "image_url": "https://d2arxad8u2l0g7.cloudfront.net/books/1385207843l/10818853.jpg",
                        "has_price": true
                    }]
                }, {
                    "id": "horror",
                    "name": "Horror",
                    "items": [{
                        "id": "2",
                        "name": "'Salem's Lot",
                        "description": "by Stephen King",
                        "value": 0,
                        "unit": "pc.",
                        "unit_price": 799,
                        "step": 1,
                        "step_unit": "pc.",
                        "step_unit_conversion": 1,
                        "image_url": "https://d2arxad8u2l0g7.cloudfront.net/books/1327891565l/11590.jpg",
                        "has_price": true
                    }]
                }, {
                    "id": "whodunit",
                    "name": "Whodunit",
                    "items": [{
                        "id": "3",
                        "name": "Mirror Deep",
                        "description": "by Joss Landry",
                        "value": 0,
                        "unit": "pc.",
                        "unit_price": 899,
                        "step": 1,
                        "step_unit": "pc.",
                        "step_unit_conversion": 1,
                        "image_url": "https://d2arxad8u2l0g7.cloudfront.net/books/1368021554l/17901969.jpg",
                        "has_price": true
                    }]
                }]
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type advanced_order_result which contains the currency and the categories with the selected items.

Form widget: MYDIGIPASS

Let the user authenticate using the “MYDIGIPASS Authenticator for Mobile” app. See https://www.mydigipass.com/ for more information.

  • form type is mydigipass
  • widget scope is a space-separated string. The supported scopes are email, phone, profile, address, eid_profile, eid_address and eid_photo
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": "Authenticate via MYDIGIPASS.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "mydigipass",
            "positive_button": "Submit",
            "negative_button": "Cancel",
            "negative_confirmation": "Are you sure you wish to cancel?",
            "widget": {
                "scope": "eid_profile eid_address eid_photo profile email phone address"
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": []
    }
}

The result is of type mydigipass_result.

Example:

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": 7,
        "received_timestamp": 1324658438,
        "acked_timestamp": 1324659262,
        "message_key": "4d2e8c4b-b23a-4b5b-86b3-368158aa64fe",
        "parent_message_key": null,
        "member": "john@example.com",
        "tag": "my message tag19347819",
        "answer_id": "positive",
        "form_result": {
            "type": "mydigipass_result",
            "result": {
                "eid_photo": "<base64 data>",
                "eid_profile": {
                    "first_name": "John",
                    "last_name": "Doe",
                    "issuing_municipality": "Lochristi",
                    "gender": "M",
                    "created_at": null,
                    "card_number": "411472487062",
                    "chip_number": "971375383610410795861984910107410331089",
                    "noble_condition": "",
                    "date_of_birth": "1970-01-01",
                    "location_of_birth": "Gent",
                    "validity_begins_at": "2015-07-14",
                    "validity_ends_at": "2025-07-14",
                    "nationality": "Belg",
                    "first_name_3": "J"
                },
                "eid_address": {
                    "municipality": "Lochristi",
                    "street_and_number": "Antwerpsesteenweg 19",
                    "zip_code": "9080"
                },
                "profile":  {
                    "preferred_locale": "en",
                    "first_name": "John",
                    "last_name": "Doe",
                    "born_on": "1970-01-01",
                    "uuid": "fa7a20f5-b59a-4635-98ed-1cabca8ed86f",
                    "updated_at": "2016-08-04T08:02:07.336Z"
                },
                "email": "john@example.com",
                "phone": "+3293242564",
                "address": {
                    "city": "Lochristi",
                    "zip": "9080",
                    "country": "BE",
                    "state": "Oost-Vlaanderen",
                    "address_1": "Antwerpsesteenweg 19",
                    "address_2": ""
                }
            }
        },
        "service_identity": "+default+",
        "result_key": "69975c1f-9e97-4e7c-acc7-01ff011753ee",
        "user_details": [
            {
              "email": "john@example.com",
              "name": "John Doe",
              "language": "en",
              "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
         ]
    },
    "method": "messaging.form_update",
    "id": "623a0099-2be7-11e1-b111-e9db33d7dba9"
}

Form widget: Sign

Let the user sign one or more documents attached to this message. It is also possible to let the user sign a provided payload.
This is only supported on apps with security enabled. These apps will ask the user to configure a security PIN code at the end of the account creation procedure.

  • form type is sign
  • widget caption is an optional string containing the message which is shown at the moment the user is asked to enter his PIN code.
  • widget payload is an optional base64 encoded string that needs to be signed.
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": "Sign the attached documents.",
        "tag": "my message tag19347819",
        "context": null,
        "form": {
            "type": "sign",
            "positive_button": "Sign",
            "negative_button": "Cancel",
            "negative_confirmation": "Are you sure you wish to cancel?",
            "widget": {
                "payload": "VGhpcyBpcyB0aGUgcGF5bG9hZA==",
                "caption": "Enter your security PIN code the sign the attached documents."
            },
            "javascript_validation": null
        },
        "service_identity": "+default+",
        "attachments": [{
            "name": "New contract",
            "download_url": "http://www.rogerthat.net/wp-content/uploads/2016/08/contract.pdf",
            "content_type": "application/pdf"
        }]
    }
}

The result is of type unicode_list_result.

  • This array will always contain two elements:

    • The first element contains the signed payload. This is the signature of the sha256 hash of the base64 decoded payload. If the payload was null, the first element will be null as well.
    • The second element contains a signature of the sha256 hash of the complete message. This is the signature of the sha256 hash of the message itself, the sha256 hash of the payload and the sha256 hash of all attachments.
      This is a python example how this hash is calculated:

          import hashlib
      
          def sha256(val):
              digester = hashlib.sha256()
              digester.update(val)
              return digester.digest()
      
          digester = hashlib.sha256()
          digester.update(sha256(message))
          digester.update(sha256(payload))
          for attachment_filename in attachments:
              with open(attachment_filename, 'r+') as f:
                  digester.update(sha256(f.read()))
          final_hash = digester.digest()  # this is the hash that will be signed
              

Example messaging.form_update request:

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": 7,
    "received_timestamp": 1324658438,
    "message_key": "4d2e8c4b-b23a-4b5b-86b3-368158aa64fe",
    "service_identity": "+default+",
    "member": "john@example.com",
    "parent_message_key": null,
    "tag": "my message tag19347819",
    "user_details": [
      {
        "public_key": "BN24IEgq4gVb9EAYG2Z5VxMwCKziqYlIGiLmU8QF5gFXMPNqPr6+jFXBvH3LBnluA1/siZeKx8/crpMGK5txzHY=",
        "name": "John Doe",
        "language": "en",
        "app_id": "rogerthat",
        "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
        "email": "john@example.com"
      }
    ],
    "form_result": {
      "type": "unicode_list_result",
      "result": {
        "values": [
          "MEQCIEVsoiubOpxpMa6fPv01r0ECMaNchtP0PUTYTOOLovI+AiA347/fmFrrjvzeukobfJu1co3unGCL6gEGrlzcNYYKFQ==",
          "MEUCIQC3lgzbmfYoZF9BGzHFzRWd+W35PhVEk/rU6lSaJ4TreAIgXsN7tbMDJpf9LhfV8OBgfqN+U4qUNLYYlWpV2ENJ0PM="
        ]
      }
    },
    "acked_timestamp": 1324659262,
    "answer_id":"positive"
  },
  "method":"messaging.form_update",
  "id":"81ca439c-7012-11e6-b029-51bdb36be3d1"
}

The result can be verified using the user’s public key. See user_details.public_key.

TPS broadcasts a message to Rogerthat users

The JSON-RPC method is messaging.broadcast

The parameters are:

  • broadcast_type: string with the broadcast type. Check the Broadcast center to find how to create a broadcast type
  • message: refer to messaging.send
  • answers: refer to messaging.send
  • flags: refer to messaging.send
  • branding: refer to messaging.send
  • tag: refer to messaging.send
  • service_identity: refer to messaging.send
  • alert_flags: refer to messaging.send
  • dismiss_button_ui_flags: refer to messaging.send
  • target_audience: an object with audience configuration:
    • min_age: optional integer which defines the minimum age a member should have to receive your broadcast message
    • max_age: optional integer which defines the maximum age a member should have to receive your broadcast message
    • gender: optional string which defines the gender
      • MALE
      • FEMALE
      • UNKNOWN
  • attachments: refer to data structure

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.broadcast",
    "params": {
        "broadcast_type": "Events",
        "message": "the greatest event of the world",
        "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": 0,
        "branding": null,
        "tag": "tag_big_event",
        "service_identity": "+default+",
        "alert_flags": 0,
        "dismiss_button_ui_flags": 0,
        "target_audience": {
            "min_age": 7,
            "max_age": 77,
            "gender": "MALE"
        },
        "attachments":[
            {
                "content_type": "image/png",
                "download_url": "http://www.rogerthat.net/wp-content/uploads/2012/09/rogerthat-logo.png",
                "name": "Rogerthat logo",
                "size": 17458
            }
        ]
    },
    "id": "x122abcd"
}

Response:

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

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

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": {
        "user_details":[
            {
                "email": "john@example.com",
                "name": "John Doe",
                "language": "en",
                "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ],
        "email": "john@example.com",
        "tag": "buy_coffee_brazilian_22",
        "context": "MENU_68efb3bd-8470-4b06-92bf-3feaab457ae6",
        "result_key": "69975c1f-9e97-4e7c-acc7-01ff011753ee",
        "service_identity": "+default+"
    },
    "id": "xxx123abc"
}

Parameters:

  • user_details refer to data structure
  • 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.
  • result_key the key of the resulting message when using the High Performance API with type message
  • service_identity the service identity that was used to start the interaction

Response:

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

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

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"
        ],
        "service_identity": "+default+",
        "force_language": null,
        "flow_params": null
    }
}
  • 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
  • service_identity: refer to messaging.send
  • force_language: optional string to launch a flow in a certain language, regardless of the language of the recipient.
  • flow_params: optional string which will be passed to the flowcode blocks in the message flow (if any). This can be used to set default values in the flow, for example.

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",
        "service_identity": "+default+",
        "result_key": "69975c1f-9e97-4e7c-acc7-01ff011753ee",
        "flush_id": "flush_join",
        "flush_message_flow_id": "ahNkZXZ-bW9iaWNhZ2VjbG91ZGhycj0LEgptYy10cmFja2VyIgxjYXJsQGNhcmwuYmUMCxIRTWVzc2FnZUZsb3dEZXNpZ24iCnJlc3RhdXJhbnQM",
        "user_details": [
            {
                "email": "john@example.com",
                "name": "John Doe",
                "language": "en",
                "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ],
        "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
  • service_identity: The service identity which was sent by the service in the messaging.start_flow call
  • result_key: the key of the resulting message when using the High Performance API whith type message
  • flush_id: id of the results flush.
  • flush_message_flow_id: id of the message flow that contains the flush.
  • users_details: refer to data structure
  • 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": [
                  {"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.

Chat messages

Starting a chat

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.start_chat",
    "params": {
        "alert_flags": 2,
        "service_identity": "+default+",
        "topic": "Alarm situation in sector 5",
        "description": "Fire alarm triggered in sector 5",
        "tag": "37AAF801-CE21-4AC5-9F43-E8E403E1EB5F",
        "context": null,
        "flags": 0,
        "members": [
            "john@example.com",
            "pete@example.com",
            { "member": "silent@example.com", "alert_flags":1 }
        ],
        "reader_members": [
            "frank@example.com",
            { "member": "rosa@example.com", "alert_flags":1 }
        ],
        "metadata": [{"key": "Sector", "value": "5"}],
        "avatar": null,
        "background_color": null,
        "text_color": null,
        "default_priority": 1,
        "default_sticky": false
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • members: The users that need to receive this message and can reply to it.
  • reader_members: The users that need to receive this message but can’t reply to it.
  • topic: The topic of the chat
  • description: The description of the chat
  • alert_flags: refer to messaging.send
  • service_identity: refer to messaging.send
  • tag: refer to messaging.send
  • context: refer to messaging.send
  • 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.
    • NOT_REMOVABLE = 1 Whether or not the chat can be removed by a user.
    • ALLOW_ANSWER_BUTTONS = 2 Whether or not messages can have buttons.
    • ALLOW_PICTURE = 4 Whether or not messages can have pictures.
    • ALLOW_VIDEO = 8 Whether or not messages can have videos.
    • ALLOW_PRIORITY = 16 Wheter or not messages can have a custom priority.
    • ALLOW_STICKY = 32 Whether or not messages can be sticky or not.
  • metadata: Extra info that will be shown in the chat details.
  • avatar: A base64 encoded picture of the chat picture.
  • background_color: The background color of the message in the thread of messages.
  • text_color: The text color of the message in the thread of messages.
  • default_priority: The default priority of every message in the chat.
    • By default no priority is set (default_priority = 1).
    • PRIORITY_NORMAL = 1 The text baloon of the message will have no special color or sound.
    • PRIORITY_HIGH = 2 The text baloon of the message will have a blue color and no sound.
    • PRIORITY_URGENT = 3 The text baloon of the message will have a red color and no sound.
    • PRIORITY_URGENT_WITH_ALARM = 4 The text baloon of the message will have a red color and a sound will be played (ALERT_FLAG_INTERVAL_5) refer to messaging.send.
  • default_sticky: Whether or not sticky is enabled by default for every message in the chat.
    • By default sticky messages are disabled.
    • true Messages will stay visible forever.
    • false Messages will be removed after 12 hours.

The response in case of success:

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

{
    "result": "b2488800-938b-485c-b80b-c30f0126ee91",
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869",
    "error": null
}
  • result: The parent message key to this chat
  • error: error object or null in case of success

Updating a chat

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.update_chat",
    "params": {
        "parent_message_key": "b2488800-938b-485c-b80b-c30f0126ee91",
        "topic": "Alarm situation in sector 5b",
        "description": "Fire alarm triggered in sector 5b",
        "flags": 0,
        "metadata": [{"key": "Sector", "value": "5b"}],
        "avatar": null,
        "background_color": null,
        "text_color": null
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}

Delete chat

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.delete_chat",
    "params": {
        "parent_message_key": "b2488800-938b-485c-b80b-c30f0126ee91"
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • parent_message_key: The parent message key of the chat message

Sending a chat 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.send_chat_message",
    "params": {
        "parent_key": "b2488800-938b-485c-b80b-c30f0126ee91",
        "message": "The new chat message content.",
        "answers": [],
        "attachments": [],
        "sender": {
            "email": "john@example.com",
            "name": "John Doe",
            "language": "en",
            "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096",
            "app_id": "rogerthat"
        },
        "priority": 1,
        "sticky": true,
        "tag": null
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • parent_key: The parent message key of the chat message
  • message: The message of the chat message
  • answers: refer to messaging.send
  • attachments: refer to data structure
  • sender: The sender of the chat message
  • priority: The priority of the chat message
  • sticky: Whether or not the chat message is sticky
  • tag: The tag of the chat message

The response in case of success:

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

{
    "result": "86367035-4336-4d55-bf4a-15260c7dbb32",
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869",
    "error": null
}
  • result: The message key to this chat message
  • error: error object or null in case of success

Receiving a chat message

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.new_chat_message",
    "params": {
        "parent_message_key": "b2488800-938b-485c-b80b-c30f0126ee91",
        "message_key": "94abd0d5-52e9-4d24-8856-fd607c1d82d6",
        "sender": {
            "email": "john@example.com",
            "name": "John Doe",
            "language": "en",
            "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096",
            "app_id": "rogerthat"
        },
        "message": "The newly created chat message content.",
        "answers": [],
        "timestamp": 1301397124,
        "tag": null,
        "service_identity": "+default+",
        "attachments": []
    },
    "id": "xxx123abc"
}
  • parent_message_key: The parent message key of the chat message
  • message_key: The message key of the chat message
  • sender: The sender of the chat message
  • message: The message of the chat message
  • answers: refer to messaging.send
  • timestamp: UTC epoch when message was sent
  • tag: The tag of this chat message
  • service_identity: The service identity which was given in the messaging.start_chat call
  • attachments: refer to data structure

Adding members to a chat

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.add_chat_members",
    "params": {
        "parent_message_key": "b2488800-938b-485c-b80b-c30f0126ee91",
        "members": [],
        "reader_members": [
            "johny@example.com"
        ]
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • parent_message_key: The parent message key of the chat message
  • members: The users that need to receive this message and can reply to it.
  • reader_members: The users that need to receive this message but can’t reply to it.

Updating current members in a chat

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.update_chat_members",
    "params": {
        "parent_message_key": "b2488800-938b-485c-b80b-c30f0126ee91",
        "members": [
            "johny@example.com"
        ],
        "status": "WRITER"
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • parent_message_key: The parent message key of the chat message
  • members: The users status needs to be updated.
  • status:
    • WRITER
    • READER

Delete members from a chat

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.delete_chat_members",
    "params": {
        "parent_message_key": "b2488800-938b-485c-b80b-c30f0126ee91",
        "members": [
            "johny@example.com"
        ],
        "soft": false
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • parent_message_key: The parent message key of the chat message
  • members: The users status needs to be updated.
  • soft:
    • true: The chat remains visible on the users phone but he will not receive any updates
    • false: The chat will be removed from the users phone and he will not receive any updates

A member removed a chat

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.chat_deleted",
    "params": {
        "parent_message_key": "b2488800-938b-485c-b80b-c30f0126ee91",
        "timestamp": 1301397124,
        "service_identity": "+default+",
        "member": {
            "email": "john@example.com",
            "name": "John Doe",
            "language": "en",
            "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096",
            "app_id": "rogerthat"
        }
    },
    "id": "xxx123abc"
}
  • parent_message_key: The parent message key of the chat message
  • timestamp: UTC epoch when the chat was deleted
  • service_identity: The service identity which was given in the messaging.start_chat call
  • member: The member who removed the chat

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",
        "service_identity": "+default+"
    },
    "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
  • service identity: service identity which invites an user

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",
        "service_identity": "+default+",
        "user_details": [
            {
                "email": "john@example.com",
                "name": "John Doe",
                "language": "en",
                "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ]
    },
    "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
  • service_identity: The service identity which was sent by the service in the friend.invite API call
  • user_details: refer to data structure

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",
        "service_identity": "+default+"
    },
    "id": "EA11224D-85BC-4961-96AE-42CDA8D3D81D"
}
  • email is the Rogerthat user account that will be unfriended
  • service_identity service identity which break up with a user

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,
        "service_identity": "+default+",
        "user_details":[
            {
                "email": "john@example.com",
                "name": "John Doe",
                "language": "en",
                "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ]
    },
    "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.
  • service_identity: The service identity which the user wants to connect to.
  • users_details: refer to data structure

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” or a JSON string. When it is a JSON string, then the invite will be accepted, and the JSON string will be set as user_data. Refer to system.put_user_data.

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",
        "service_identity": "+default+",
        "user_details": [
            {
                "email": "john@example.com",
                "name": "John Doe",
                "language": "en",
                "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ]
    },
    "id": "7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}
  • email is the Rogerthat user account of the user that broke friendship
  • service_identity the service identity which the user disconnected with
  • user_details refer to data structure

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",
        "service_identity": "+default+"
    },
    "id": "json rpc id 7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}
  • email is the Rogerthat user account of the user
  • service_identity the service identity

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.

TPS retrieves friend list

Get the friends of a service identity, one page at a time. The result contains the updated cursor and the next page of friends. If the number of returned friends is zero, the iteration should be considered finished.

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.list",
    "params": {
        "service_identity": "+default+",
        "cursor": null
    },
    "id": "7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}
  • service_identity: the service identity of which we want to list the friends
  • cursor: the cursor

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "result":{
        "cursor": "123",
        "friends": [
            {
                "email": "john@example.com",
                "name": "John Doe",
                "language": "en",
                "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/5337821896245248"
            },
            {
                "email": "peter@example.com",
                "name": "Peter Johnson",
                "language": "en",
                "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/5337821896245248"
            }
        ]
    },
    "id":"7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}

  • cursor: the cursor for this friend.list result. This String is opaque and should not be interpreted. It should be given to the next invocation the friend.list call.
  • friends: an array with user details for each friend

TPS retrieves users of a broadcast

Get the number of friends who are following a certain broadcast type

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_broadcast_audience",
    "params": {
        "broadcast_type": "Event",
        "service_identity": "+default+"
    },
    "id": "7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}
  • broadcast_type: string with the broadcast type. Check the Broadcast center to find how to create a broadcast type
  • service_identity: the service identity

response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "result": {
        "connected_users":[
            {
                "name": "John Doe",
                "avatar": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4023007",
                "age": 40,
                "gender": "MALE"
            },
            {
                "name": "Jane Roberts",
                "avatar": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4023007",
                "age": 29,
                "gender": "FEMALE"
            }
        ],
        "not_connected_users":59
    },
    "id":"7FF8C82E-19DF-46AE-B525-5C37F8E053B6"
}
  • connected_users: an array containing the connected users:
    • name: string with the user name
    • avatar: string with the link to the user avatar
    • age: integer with the user age
    • gender: string with the user gender:
      • MALE
      • FEMALE
      • UNKNOWN
  • not_connected_users: integer with the amount of users which disabled the specified broadcast type

TPS receives beacon notifications

Friends enter the range of a beacon

This callback is generated when a connected user enters the range of a beacon configured in one of the service identities.

Request:

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key
{
    "method": "friend.in_reach",
    "params": {
        "service_identity": "+default+",
        "user_details": {
            "email": "john@example.com",
            "name": "John Doe",
            "language": "en",
            "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
        },
        "beacon": {
            "uuid": "110E8400-E29B-11D4-A716-446655440000",
            "major": "123",
            "minor": "987",
            "tag": "Meeting room 1"
        },
        "proximity": "NEAR",
        "timestamp": 1301397124
    },
    "id": "g46141708m"
}
  • service_identity: the service identity which owns the beacon
  • user_details: refer to data structure
  • beacon: refer to data structure
  • proximity: string defining the proximity, can be:
    • IMMEDIATE
    • NEAR
    • FAR
  • timestamp: UTC epoch when a friend become in reach.

Response:

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

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

Friends exit the range of a beacon

This callback is generated when a connected user exits the range of a beacon configured in one of the service identities.

Request:

POST /configurable/service/callback HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key
{
    "method": "friend.out_of_reach",
    "params": {
        "service_identity": "+default+",
        "user_details": {
            "email": "john@example.com",
            "name": "John Doe",
            "language": "en",
            "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
        },
        "beacon": {
            "uuid": "110E8400-E29B-11D4-A716-446655440000",
            "major": "123",
            "minor": "987",
            "tag": "Meeting room 1"
        },
        "timestamp": 1301397124
    },
    "id": "g46141708m"
}
  • service_identity: the service identity which owns the beacon
  • user_details: refer to data structure
  • beacon: refer to data structure
  • timestamp: UTC epoch when a friend exits the range of a beacon

Response:

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

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

Location tracking

Start tracking users location

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.track_location",
    "params": {
        "email": "john@example.com",
        "until": 1457604274,
        "distance_filter": 10,
        "service_identity": "+default+",
        "app_id": "rogerthat"
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • email: The user that needs to be tracked
  • until: UTC epoch when we need to stop tracking the users location
  • distance_filter: The distance between the previous location (in meters)
  • service_identity: refer to messaging.send
  • app_id: The app id

The response in case of success:

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

{
    "result": "a9b2a36d-541a-4d68-ad2b-d84437be3df9",
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869",
    "error": null
}
  • result: The tracking key to this form
  • error: error object or null in case of success

Cancel location tracker

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.cancel_location_tracker",
    "params": {
        "tracker_key": "a9b2a36d-541a-4d68-ad2b-d84437be3df9"
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • tracker_key: The tracking key

Location update of a user

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.location_fix",
    "params": {
        "service_identity": "+default+",
        "user_details": [{
            "email": "john@example.com",
            "name": "John Doe",
            "language": "en",
            "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096",
            "app_id": "rogerthat"
        }],
        "location" : {
          "latitude": 510925168,
          "longitude": 38196285,
          "accuracy": 2,
          "timestamp": 1457604274
        },
        "tracker_key": "a9b2a36d-541a-4d68-ad2b-d84437be3df9"
    },
    "id": "xxx123abc"
}
  • service_identity: refer to messaging.send
  • user_details: refer to data structure
  • location:
    • latitude: The latitude in degrees * 10000000
    • longitude: The longitude in degrees * 10000000
    • accuracy: The accuracy in meters
    • timestamp: UTC epoch from the location update
  • tracker_key: The tracking key

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!

List Branding

Get all your brandings.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key
{
    "params": {},
    "method": "system.list_brandings",
    "id": "4032dad0-7473-4d93-9672-3760d6163d8a"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "result":[
        {
            "timestamp": 1401974651,
            "description": "my cool branding",
            "type": 1,
            "id": "D5A7CAFCC3D0430FD2BD9EE9B5B47AD0B9024F267C67180F0498E7DA546F5C41",
            "created_by_editor": false
        }
    ],
    "id": "4032dad0-7473-4d93-9672-3760d6163d8a",
    "error": null
}
  • timestamp: an epoch defining the creation time.
  • description: the description
  • type: the branding type:
    • 1: This branding can be used for messages, the TPS “About” screen, the TPS “Home” screen and static content of a menu item.
    • 2: This branding is a HTML5 app and can only be used as static content of a menu item.
  • id: the branding key.
  • created_by_editor: if true, then the branding was created using the branding designer in the service panels.

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",
        "service_identity": "+default+",
        "flow": "Sample message flow"
    },
    "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
  • service_identity: the service identity which the new QR code will belong to
  • flow: optional string defining the message flow id or a message flow name which will be attached to the QR code

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

Create multiple QR codes at once

If you need to create multiple QR codes with the same template (or without template), then qr.bulk_create is the recommended way to do this. It is much faster than calling qr.create multiple times sequentially.
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.bulk_create",
    "params": {
        "description": "Order Sandwich",
        "tags": ["candy_001", "candy_002", "candy_003", "candy_004"],
        "template_key": "qr138B",
        "service_identity": "+default+",
        "flow": "Sample message flow"
    },
    "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”. Can be either a string, or an array of strings. If the description is a string, then all the QR codes will have the same description. If each QR code must have a different description, then provide an array with the same length as the tags array. The descriptions and tags will be zipped when the QR codes are being created.
  • tags: unique identifiers of the QR codes. 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
  • service_identity: the service identity which the new QR codes will belong to
  • flow: optional string defining the message flow id or a message flow name which will be attached to the QR codes

The result contains a HTTPS URL of the PNG image of the freshly created QR Codes and the content of each 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/wOtF_7b3zLzX5IAQ3TEJLxRjTpi2TvQ4SIhz7vcOVdk-/212005",
        "content_uri": "https://rogerth.at/S/93CC8",
        "email_uri": "https://rogerth.at/M/93CC8?email",
        "sms_uri": "https://rogerth.at/M/93CC8"
    }, {
        "image_uri": "https://rogerth.at/si/wOtF_7b3zLzX5IAQ3TEJLxRjTpi2TvQ4SIhz7vcOVdk-/212006",
        "content_uri": "https://rogerth.at/S/-29F6",
        "email_uri": "https://rogerth.at/M/-29F6?email",
        "sms_uri": "https://rogerth.at/M/-29F6"
    }, {
        "image_uri": "https://rogerth.at/si/wOtF_7b3zLzX5IAQ3TEJLxRjTpi2TvQ4SIhz7vcOVdk-/212007",
        "content_uri": "https://rogerth.at/S/CWAZ6",
        "email_uri": "https://rogerth.at/M/CWAZ6?email",
        "sms_uri": "https://rogerth.at/M/CWAZ6"
    }, {
        "image_uri": "https://rogerth.at/si/wOtF_7b3zLzX5IAQ3TEJLxRjTpi2TvQ4SIhz7vcOVdk-/212008",
        "content_uri": "https://rogerth.at/S/23SX5",
        "email_uri": "https://rogerth.at/M/23SX5?email",
        "sms_uri": "https://rogerth.at/M/23SX5"
    }]
}

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

List QR templates

Get the QR templates of a service identity, one page at a time. The result contains the updated cursor and the next page of templates. If the number of returned templates is zero, the iteration should be considered finished.

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.list_templates",
    "params": {
        "cursor": null
    },
    "id": "g4614928m"
}
  • cursor: the cursor

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "g4614928m",
    "result": {
        "cursor": "123",
        "templates": [
            {
                "id": "qr1411C800000000",
                "description": "Get help",
                "color": "000",
                "timestamp": 1401868064
            }
        ]
    }
}
  • cursor: the cursor for this qr.list_templates result. This String is opaque and should not be interpreted. It should be given to the next invocation the qr.list_templates call.
  • templates: array with template definition:
    • id: string with the id of the template
    • description: string with the template description
    • color: string with the template color
    • timestamp: integer with Timestamp, is in seconds since 1 Jan 1970 UTC. For example, the timestamp of the example (1401868064) corresponds to Wed, 04 Jun 2014 07:47:44 GMT. Check this online conversion tool.

System API

Get service information

Get a summary of a service identity.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "system.get_info",
    "params": {
        "service_identity": "+default+"
    },
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0"
}
  • service_identity the service identity

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0",
    "result": {
        "name": "My cool service",
        "email": "my.cool.service@example.com",
        "avatar": "https://rogerth.at/unauthenticated/mobi/cached/avatar/5211944894070784",
        "admin_emails": ["john.doe@example.com", "jane.doe@example.com"],
        "description": "my first Rogerthat service"
    }
}
  • name: the service name
  • email: the service email
  • avatar: the link to the service avatar
  • admin_emails: a list containing the email addresses of administrators
  • description: the service description

Service configuration

Validate callback configuration

In order to enable service, you have to validate and test your callback configuration.

Request:

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

{
    "params": {
        "enable_on_success": true
    },
    "method": "system.validate_callback_configuration",
    "id": "87f9b217-2a63-4f77-be3f-0d6791973c8d"
}
  • enable_on_success: If true, your service will be enabled after the callback configuration is verified.

Response:

HTTP/14.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "result": null,
    "id": "87f9b217-2a63-4f77-be3f-0d6791973c8d",
    "error": null
}

Get service status

Get the status of your service

Request:

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

{
    "params": {},
    "method": "system.get_status",
    "id": "87f9b217-2a63-4f77-be3f-0d6791973c8d"
}

Response:

HTTP/14.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "result": {
        "updates_pending": false,
        "test_callback_needed": false,
        "auto_updating": false,
        "enabled": true
    },
    "id": "87f9b217-2a63-4f77-be3f-0d6791973c8d",
    "error": null
}
  • updates_pending: if true, then there are changes which can be published to the users.
  • test_callback_needed: if true, then the callback configuration has not yet been verified.
  • auto_updating: if true, then all changes made will be directly publish to the users.
  • enabled: if true, then the service is enabled.

Enable or disable callbacks

To enable or disable a callback for the service you can:

  • do it in service panels, at the “Configuration” page
  • do it with the following call

Request:

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

{
    "params": {
        "function": "friend.invite_result",
        "enabled": false
    },
    "method": "system.put_callback",
    "id": "87f9b217-2a63-4f77-be3f-0d6791973c8d"
}
  • function: the function name of the callback you want to enable or disable:
    • friend.invite_result
    • friend.invited
    • friend.broke_up
    • friend.in_reach
    • friend.out_of_reach
    • messaging.update
    • messaging.form_update
    • messaging.poke
    • messaging.flow_member_result
    • system.api_call
  • enabled: boolean to enable or disable the callback

Response:

HTTP/14.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "result": null,
    "id": "87f9b217-2a63-4f77-be3f-0d6791973c8d",
    "error": null
}

Publish changes

Every time you update your service in the service panels, or using the API, your changes will be stashed. This means that the won’t be pushed to the devices of your connected users yet. If you are finished with updating your service and you want to make the changes visible to your connected users, then you will have to publish.

You can publish in two ways:

    • Click the publish button in the service panels shown in the picture
  • Use the system.publish_changes API call, as shown below

Request:

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

{
    "params": {},
    "method": "system.publish_changes",
    "id": "6b3bda00-a59b-420f-ac25-2276de2829a7"
}

Response:

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

{
    "result": null,
    "id": "6b3bda00-a59b-420f-ac25-2276de2829a7",
    "error": null
}

Update the avatar

Set the avatar of your service. Note that all service identities have the same avatar.

Request:

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

{
    "params": {
        "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBggRBQkIBxQKCQkKDRYOGQwMDRodIBwfHxwmLCUoHiUdMzkqIyUvJR4oIjssLz4wLDMwISU9QTMvNy01OCkBCQoKDgsNGQ4OFiwdHiQ1MjU1NCovNjQrNSs1NCw2MzUpNTUuNjEpNjY1KS8uLDUsLCksKS8pNCwsKSkpNikpKf/AABEIADIAMgMBIgACEQEDEQH/xAAbAAEBAAMBAQEAAAAAAAAAAAAABwQFBggDAv/EADYQAAEDAwEGBAIIBwAAAAAAAAECAwQABREGEiEiMUFhBxNRcRSBFUJTkaHB0fEWIzNUgrGy/8QAFwEBAQEBAAAAAAAAAAAAAAAAAAIDAf/EABkRAQEBAQEBAAAAAAAAAAAAAAABAhIRA//aAAwDAQACEQMRAD8Asl0vVvjRw9cnG4zajsgrPOvvFmR3WA9EW2+2frtqBH4VDdUfSiru+i9lQljd/MTkAdNkDds+1YNsk3GPsusOuodHN1o4/wBUF9uLLy7bIZiqLD621JS6OhxuP31wfhXfLi5PucG7rkPvICXE+eskjCiFYz3xWBaPFSejZRdEImI+0Rwq/Q/hWda7vblazh3W3ktsPuORXA4MEeYnbTn3cQr76w+ks3nTbFnOsqNSlK3YlKUoNTqLTcObBLMobLqQdh4Dek/mO1RS5W+TGuj0ORwPMq2SUnn6EdiN9egaj/ifs/xivZ5+SjPv+1By4dQf6qQe6dx/SsyN5Bhy4yV5MholLak4O0jjGOnJJT/lWur8CShLzUoEYiuBzPTdms/pOsWLxfNR3GhtdKjNt2668cUqKvieLKMjcMb+HoPfNVCFcIrzAehLakNn6zagf2qM2Kz3xUZ76Jb+JioeU3klPMe5zywa31s0pqX4pLzbTFuc+1S/s/8ABOfnVZ11mVzU5tioUrRItmofLSFS2trH9ok0qkt7US1FoK/vaxnz3m5MoOuFSeIFOznhxj0G7FW2lB53udtmNFyPLQ7GeKDgOJI+YrHhacmTr0xb4qcsoAOBy+fokVd9T6XizoKGZBU040raS6kDI7dx27CuQuWjb1GgojacSJJVslbofDZJ6k7xuHQcvnQfLRN5jQb7drVcHEJZCkhLnQqQNk+2QkH3GK3zPiPEVcGWlNOMR3VBPnPOJB38uHnXEzPDXUvnBDCWHS4Ml8vjCSfXPEcdga3rHgxHN6bnz5MmUWlIUElIG9OOo7j0qc55nkVrXV9UilKVSSlKUClKUClKUClKUH//2Q=="
    },
    "method": "system.put_avatar",
    "id": "g116141615m"
}
  • image: string with base64 encoded bytes of a 50×50 .png file.

Response:

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

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

Identity manipulation

Create or update a service identity

Add a new identity to your service, or update an existing one. Note that when updating a service identity, you do not have to specify the properties that you don’t want to update. Only the properties which are present in the request will be updated.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "system.put_identity",
    "params": {
        "app_data": "{\"xmpp_room\": \"chatroom1\"}",
        "beacons": [
            {
                "uuid": "110E8400-E29B-11D4-A716-446655440000",
                "major": "123",
                "minor": "987",
                "tag": "Meeting room 1"
            }
        ],
        "description": "This is your personal fully customizable Rogerthat service identity.",
        "description_branding": null,
        "description_branding_use_default": false,
        "description_use_default": false,
        "email_statistics": false,
        "email_statistics_use_default": false,
        "identifier": "i1",
        "menu_branding": null,
        "menu_branding_use_default": false,
        "admin_emails": ["john.doe@example.com", "jane.doe@example.com"],
        "name": "My cool service identity",
        "phone_call_popup": null,
        "phone_call_popup_use_default": false,
        "phone_number": "+32 9 324 25 64",
        "phone_number_use_default": false,
        "qualified_identifier": "my.cool.service.identity@example.com",
        "recommend_enabled": true,
        "search_config": {
            "enabled": true,
            "keywords": "test example cool new",
            "locations": [
                {
                    "address": "Antwerpsesteenweg 19, 9080 Lochristi",
                    "lat": 51.092,
                    "lon": 3.820
                }
            ]
        },
        "search_use_default": false
    },
    "id": "2767c2bc-6e83-4cba-9b60-5b874dbadb2a"
}


Service Identity Detail:

  • app_data: an optional JSON string. It will be available as rogerthat.service.data in the Rogerthat Javascript API.
  • beacons: an optional array with beacons. Refer to data structure.
  • description: the service description.
  • description_use_default: if true, then the description of the default service identity will used.
  • description_branding: the branding which will be used for the TPS “About” screen.
  • description_branding_use_default: if true, then the description_branding of the default service identity will used.
  • email_statistics: if true, admins wil receive the weekly statistics email
  • email_statistics_use_default: if true, then the email_statistics of the default service identity will used.
  • identifier: the identifier of the service identity
  • menu_branding: the branding which will be used for the TPS “Home” screen.
  • menu_branding_use_default: if true, then the menu_branding of the default service identity will used.
  • admin_emails: a list containing the email addresses of administrators
  • name: the service identity name
  • phone_call_popup: an optional custom message to be shown when a user pressed the “Call” button on the TPS “Home” screen.
  • phone_call_popup_use_default: if true, then the phone_call_popup of the default service identity will used.
  • phone_number: the phone number. If null, then no “Call” button will be shown on the TPS “Home” screen.
  • phone_number_use_default: if true, then the phone_number of the default service identity will used.
  • qualified_identifier: a custom email address which will be shown on the “TPS” about page. If null, then the service account will be shown, appended with a slash and the identifier of the service identity.
  • recommend_enabled: If true, then users can recommend this service to other users.
  • search_config: search configuration, refer to data structure.
  • search_use_default: if true, then the search_config of the default service identity will used.

Response:

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

{
    "result": null,
    "id": "2767c2bc-6e83-4cba-9b60-5b874dbadb2a",
    "error": null
}

Get service identity

Get the details of a service identity

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "system.get_identity",
    "params": {
        "service_identity": "+default+"
    },
    "id": "no id ea"
}
  • service_identity: the service identity

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "no id ea",
    "result": {
        "app_data": "{\"xmpp_room\": \"chatroom1\"}",
        "beacons": [
            {
                "uuid": "110E8400-E29B-11D4-A716-446655440000",
                "major": "123",
                "minor": "987",
                "tag": "Meeting room 1"
            }
        ],
        "created": 1401788062,
        "description": "This is your personal fully customizable Rogerthat service identity.",
        "description_branding": null,
        "description_branding_use_default": false,
        "description_use_default": false,
        "email_statistics": false,
        "email_statistics_use_default": false,
        "identifier": "i1",
        "menu_branding": null,
        "menu_branding_use_default": false,
        "admin_emails": ["john.doe@example.com", "jane.doe@example.com"],
        "name": "My cool service identity",
        "phone_call_popup": null,
        "phone_call_popup_use_default": false,
        "phone_number": "+32 9 324 25 64",
        "phone_number_use_default": false,
        "qualified_identifier": "my.cool.service.identity@example.com",
        "recommend_enabled": true,
        "search_config": {
            "enabled": true,
            "keywords": "test example cool new",
            "locations": [
                {
                    "address": "Antwerpsesteenweg 19, 9080 Lochristi",
                    "lat": 51.092,
                    "lon": 3.820
                }
            ]
        },
        "search_use_default": false
    }
}

The result is a Service Identity Detail object. Refer to Create service identity for an explanation of the properties.

Delete service identity

Remove a service identity

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_ke
{
    "method": "system.delete_identity",
    "params": {
        "identifier": "i1"
    },
    "id": "92d0c915-36df-4fd4-ac3a-36316e411c0c"
}
  • identifier: the service identity you want to delete

Response:

HTTP/14.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "92d0c915-36df-4fd4-ac3a-36316e411c0c",
    "result": null
}

List service identities

Get the service identities, one page at a time. The result contains the updated cursor and the next page of identities. If the number of returned identities is zero, the iteration should be considered finished.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_ke
{
    "method": "system.list_identities",
    "params": {
        "cursor": null
    },
    "id": "92d0c915-36df-4fd4-ac3a-36316e411c0c"
}
  • cursor: the cursor.

Response:

HTTP/14.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "92d0c915-36df-4fd4-ac3a-36316e411c0c",
    "result": {
        "cursor": "123",
        "identities": [
            {
                "app_data": null,
                "beacons": [],
                "created": 1401788062,
                "description": "This is your personal fully customizable Rogerthat service.",
                "description_branding": null,
                "description_branding_use_default": false,
                "description_use_default": false,
                "email_statistics": false,
                "email_statistics_use_default": false,
                "identifier": "+default+",
                "menu_branding": null,
                "menu_branding_use_default": false,
                "meta_data": null,
                "name": "test",
                "phone_call_popup": null,
                "phone_call_popup_use_default": false,
                "phone_number": null,
                "phone_number_use_default": false,
                "qualified_identifier": null,
                "recommend_enabled": false,
                "search_config": {
                    "enabled": false,
                    "keywords": null,
                    "locations": []
                },
                "search_use_default": false
            }
        ]
    }
}
    • cursor: the cursor for this system.list_identities result. This String is opaque and should not be interpreted. It should be given to the next invocation the system.list_identities call.
    • identities: an array of service identity details. Refer to Create service identity for an explanation of the properties.

Menu

Create or update a menu item

Create or update a menu item.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: your_secret_api_key
{
    "params": {
        "icon_name": "audio knob",
        "tag": "audio_knob_tag",
        "coords": [1, 1, 2],
        "icon_color": "ED721A",
        "label": "my menu item"
    },
    "method": "system.put_menu_item",
    "id": "95d0ac43-6ee1-4883-891b-a9ca52d6af51"
}
  • icon_name: the name of the menu icon as shown in the service panels.
  • tag: the tag associated with this menu item, will be reported in the messaging.poke callback.
  • coords: an array containing:
    • an integer with the x coordinate (between 0 and 3)
    • an integer with the y coordinate (between 0 and 3)
    • an integer with the page
  • icon_color: string with the hexadecimal color code, refer to colorpicker
  • label: the label of the menu item

Without defining any of the following optional properties the user’s device will wait on a response of the messaging.poke callback for maximum 10 seconds.

  • screen_branding: the key of a branding with static content or a HTML5 app which needs to be shown.
    • run_in_background: define whether the HTML5 app needs to be closed on the user’s device when the Rogerthat app is not in the foreground anymore.
    • requires_wifi: define whether the HTML5 app can only be started if the user’s device is connected to WiFi
  • static_flow: the id of the message flow which needs to be started on the user’s device.
  • is_broadcast_settings: If true, then this item will be used to enable or disable broadcasts by type.
    • broadcast_branding: the branding which will be on the user’s device when showing the broadcast settings.

Response:

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

{
    "result": null,
    "id": "95d0ac43-6ee1-4883-891b-a9ca52d6af51",
    "error": null
}

Delete a menu item

Remove an item from the service menu.

Request:

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

{
    "params": {
        "coords": [0, 1, 0]
    },
    "method": "system.delete_menu_item",
    "id": "e13b91b7-0e5e-4b74-8c70-868c8ec71281"
}

Response:

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

{
    "result": true,
    "id": "e13b91b7-0e5e-4b74-8c70-868c8ec71281",
    "error": null
}

The result will be true if the item was deleted. It will be false if there was no item at the provided coordinates.

Update the label of a reserved menu item

Items displayed at the first row of the first page can not be moved. However, you can overrule the standard labels with a custom one.

Request:

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

{
    "params": {
        "column": 0,
        "label": "Information"
    },
    "method": "system.put_reserved_menu_item_label",
    "id": "a1d9ff94-fe45-4cef-8ce3-0fb85ded4162"
}
  • column: the column of the menu item you want to rename (between 0 and 3)
  • label: the new label

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "result": null,
    "id": "a1d9ff94-fe45-4cef-8ce3-0fb85ded4162",
    "error": null
}

User Data

Set user data

Save data in the user_data key-value store. This data is available between the connected user and the service identity.

Request:

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

{
    "params": {
        "email": "john@example.com",
        "service_identity": "+default+",
        "user_data": "{\"xmpp_username\":\"john\",\"xmpp_password\":\"doe\"}"
    },
    "method": "system.put_user_data",
    "id": "46e5f6fa-82de-4e36-9e8f-8cb6b017075c"
}
  • service_identity: string which contains the service identity
  • user_data: a JSON string with keys and values to update the user_data key-value store. The data will be available as rogerthat.user.data in the Rogerthat Javascript API.
  • email: string which contains user email

Response:

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

{
    "result": null,
    "id": "46e5f6fa-82de-4e36-9e8f-8cb6b017075c",
    "error": null
}

Delete user data

Delete data from the user_data key-value store.

Request:

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

{
    "params": {
        "email":"john@example.com",
        "user_data_keys": ["xmpp_username", "xmpp_password"],
        "service_identity": "+default+"
    },
    "method": "system.del_user_data",
    "id": "46e5f6fa-82de-4e36-9e8f-8cb6b017075c"
}
  • email: string which contains user email
  • user_data_keys: an array which contains keys of user data that will be deleted
  • service_identity: string which contains the service identity

Response:

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

{
    "result": null,
    "id": "46e5f6fa-82de-4e36-9e8f-8cb6b017075c",
    "error": null
}

Get user data

Get data from the user_data key-value store.

Request:

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

{
    "params": {
        "email":"john@example.com",
        "user_data_keys": ["xmpp_username", "xmpp_password"],
        "service_identity": "+default+"
    },
    "method": "system.get_user_data",
    "id": "46e5f6fa-82de-4e36-9e8f-8cb6b017075c"
}
  • email: string which contains user email
  • user_data_keys: an array which contains keys of user data you want to get
  • service_identity: string which contains the service identity

Response:

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

{
    "result": "{\"xmpp_username\":\"john\",\"xmpp_password\":\"doe\"}",
    "id": "46e5f6fa-82de-4e36-9e8f-8cb6b017075c",
    "error": null
}
  • result: the values associated to the specified keys

Broadcast

List broadcast types

List all the broadcast types you defined in your service

Request:

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

{
    "params": {},
    "method": "system.list_broadcast_types",
    "id": "6b3bda00-a59b-420f-ac25-2276de2829a7"
}

Response:

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

{
    "result": ["Event", "News"],
    "id": "6b3bda00-a59b-420f-ac25-2276de2829a7",
    "error": null
}
  • result: a list of broadcast types

Update broadcast types

Configure the broadcast types of your service.

Request:

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

{
    "params": {
        "broadcast_types": [
            "Event",
            "News"
        ],
        "force": false
    },
    "method": "system.put_broadcast_types",
    "id": "17996ef1-0d88-4019-ba48-e9219e8060f8"
}
  • broadcast_types: an array containing the broadcast types
  • force: boolean to force the change

Response:

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

{
    "result": null,
    "id": "17996ef1-0d88-4019-ba48-e9219e8060f8",
    "error": null
}

Get languages

Return the default language and the supported languages of your service

Request:

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

{
    "params": {},
    "method": "system.get_languages",
    "id": "842d3ec4-2b88-4cb8-aaa4-3f8fa6a20151"
}

Response:

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

{
    "result": {
        "default_language": "en",
        "supported_languages": [
            "fr"
        ]
    },
    "id": "842d3ec4-2b88-4cb8-aaa4-3f8fa6a20151",
    "error": null
}
  • default_language: string with the service default language code
  • supported_languages: array with all supported languages code

Translations

Get translations

List all string that are used in your service, and their translation (if present).

Request:

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

{
    "params": {},
    "method": "system.get_translations",
    "id": "1ae838b5-4ad7-4d23-a07e-c3842e693d40"
}

Response:

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

{
    "error": null,
    "id": "1ae838b5-4ad7-4d23-a07e-c3842e693d40",
    "result" : {
        "export_id": 1402056547,
        "translations": [
            {
                "type": 101,
                "values": [],
                "key": "Call"
            },
            {
                "type": 201,
                "values": [],
                "key": "This is your personal fully customizable Rogerthat service."
            },
            {
                "type": 401,
                "values": [],
                "key": "News"
            }
        ],
        "email": "service-5052450746662912@trials.rogerth.at"
    }
}
  • export_id: the export identifier. If you want to update the translations, you will have to provide this export_id.
  • translations: an array with the translatable strings:
    • type an integer with item type you have to translate
    • values: an array with translations
      • language: string which contains the language
      • value: string with the translation
    • key: string in the default language of the service, which needs to be translated.
  • email: the service email.

Update translations

If you want to update the translations, you must execute system.get_translations and use that result to update the translations, because you can only update the translations if you provide the correct export_id.

Request:

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

{
    "method": "system.put_translations",
    "id": "f40d60a9-9d8a-4750-85da-367df2446b3c",
    "params": {
        "email": "service-5052450746662912@trials.rogerth.at",
        "export_id": 1402056547,
        "translations": [
            {
                "type": 101,
                "key": "Call",
                "values": [
                    {
                        "language": "fr",
                        "value": "Appel"
                    }
                ]
            }
        ]
    }
}

Response:

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

{
    "result": null,
    "id": "f40d60a9-9d8a-4750-85da-367df2446b3c",
    "error": null
}

Message flows

Create or update a message flow

Create or update a new message flow from an XML definition. The flow definition must follow the message flow XSD scheme. To have an example XML definition, you can export it from an existing message flow, using the message flow designer.

Request:

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

{
    "params": {
        "xml": "...",
        "multilanguage": true
    },
    "id": "d16f091e-525e-4316-9cb0-69424fa6100c",
    "method": "system.put_flow"
}
  • xml: the XML flow definition.
  • multilanguage: boolean to define whether the strings used in the message flow will be included when exporting the translations of your service. Refer to system.get_translations.

Response:

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

{
    "error": null,
    "id": "d16f091e-525e-4316-9cb0-69424fa6100c",
    "result": {
        "identifier": "ahFzfm1vYmljYWdlY2xvdWRocnJXCxIKbWMtdHJhY2tlciIqc2VydmljZS01MDUyNDUwNzQ2NjYyOTEyQHRyaWFscy5yb2dlcnRoLmF0DAsSEU1lc3NhZ2VGbG93RGVzaWduIgZzaW1wbGUM",
        "name": "simple",
        "last_modified": 1402473664
    }
}
  • identifier: string with the id of the message flow
  • name: string with the message flow name
  • last_modified: epoch defining the modification time

Delete a message flow

Remove a message flow.

Request:

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

{
    "params": {
        "flow": "name"
    },
    "method": "system.delete_flow",
    "id": "620b0d2d-7f4a-4332-833d-c413581c737a"
}
  • flow: a string with flow name or flow id which will be deleted

Response:

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

{
    "result": true,
    "id": "620b0d2d-7f4a-4332-833d-c413581c737a",
    "error": null
}

return true if the flow to delete exist.

TPS receives a API call

A TPS can send API calls from a HTML5 app branding on a user’s device to the backend of the TPS using the Rogerthat Javascript API. The TPS will receive the API call using a callback, and can respond with a result or an error. Finally the response will be delivered to the HTML5 app branding using the Rogerthat Javascript API.

Request:

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

{
    "params": {
        "email": "john.doe@foo.com",
        "method": "addtocalender",
        "params": "{\"eventId\": 5754903989321728}",
        "tag": "agenda",
        "service_identity": "+default+",
        "user_details": [
            {
                "email": "john.doe@foo.com",
                "name": "John Doe",
                "language": "en",
                "avatar_url": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096"
            }
        ]
    },
    "method": "system.api_call",
    "id": "g116141704m"
}
  • email: string with user email
  • method: string with the method that API call
  • params: json string with params of the method call
  • tag: string with the tag
  • service_identity: string with the service identity
  • user_details: array with user information, refer to data structure

Response:

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

{
    "error": null,
    "id": "g116141704m",
    "result": {
        "result": "{\"invitation_sent\": true}",
        "error": null
    }
}

The result is an object containing a result and an error property. This result will be delivered to the HTML5 app branding using the Rogerthat Javascript API.

  • result: null or a JSON string in case of success, or null in case of failure.
  • error: A JSON string, or null in case of success.

Get statistics

Get the statistics of a service since its creation, you can know the number of users, for each day the number of lost or gained users and the number of use for items of your service.

Request:

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

{
    "params": {
        "service_identity": "+default+"
    },
    "method": "system.get_statistics",
    "id": "140cec01-3adc-4761-8174-d574085fb7df"
}
  • service_identity: string which contains the service identity which you want have the statistics

Response:

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

{
    "result": {
        "users_gained": [
            {
                "count": 1,
                "month": 6,
                "day": 3,
                "year": 2014
            },
            {
                "count": 0,
                "month": 6,
                "day": 2,
                "year": 2014
            }
        ],
        "menu_item_press": [
            {
                "data": [
                    {
                        "count": 11,
                        "month": 6,
                        "day": 3,
                        "year": 2014
                    }
                ],
                "name": "button1"
            }
        ],
        "number_of_users": 1,
        "users_lost": [
            {
                "count": 0,
                "month": 6,
                "day": 3,
                "year": 2014
            },
            {
                "count": 0,
                "month": 6,
                "day": 2,
                "year": 2014
            }
        ]
    },
    "id": "140cec01-3adc-4761-8174-d574085fb7df",
    "error": null
}
    • number_of_users: integer with the service users number
    • users_gained: an array for each day statistics refer to data in menu_item_press
    • users_lost: an array for each day statistics refer to data in menu_item_press
    • menu_item_press: an array with :
      • Data: each day statistics:
        • count: integer with the count of pressed item or users gained or lost
        • month: integer with the month
        • day: integer with the day
        • year: integer with the year
      • name: name of the pressed item

TPS receives a Brandings updated call

In some circumstances Rogerthat will automatically update deployed HTML5 applications. When this happens, the service can be kept up to date about this using the system.brandings_updated api callback.

Request:

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

{
    "params": {
        "brandings": [
            {
                "old_id": "XYZ1",
                "new_id": "XYZ2"
            },
            {
                "old_id": "AAAA",
                "new_id": "BBBB"
            }
        ],
        "reason": "new_translations",
    },
    "method": "system.brandings_updated",
    "id": "g117141704m"
}
  • branding: A list of old_id , new_id key pairs that reveal which brandings got updated automatically.
  • reason: A reason code indicating why the brandings were updated.
    Possible values:

    • new_translations: New translations were added

Response:

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

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

Delete users

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.delete_users",
    "params": {
        "members": [
          {
              "member": "jane.doe@foo.com",
              "app_id": "rogerthat"
          }
        ]
    },
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
}
  • members: array of members. A member must be a JSON object containing the member email and app_id

The response in case of error:

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

{
    "result": null,
    "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869",
    "error": {
        "code": 60025,
        "app_id": "rogerthat",
        "message": "No permission to manage app"
    }
}
  • result: result will always be null
  • error: error object or null in case of success

App API

Only admin services can use these API’s.

Set app settings

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "app.put_settings",
    "params": {
        "settings": {
            "wifi_only_downloads": false,
            "background_fetch_timestamps": [25200, 64800],
            "oauth": {
                "url": "https://myoauthsite.com",
                "authorize_path": "/oauth/authorize",
                "token_path": "/oauth/token",
                "scopes": "read,write",
                "client_id": "dummy-client-id",
                "secret": "dummy-secret",
                "domain": "myoauthsite.com"
            }
        }
    },
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0"
}
  • wifi_only_downloads: message attachments should only be downloaded at the moment of arrival if there is WIFI connection.
  • background_fetch_timestamps: (iOS-only) a list with seconds from midnight on which the app needs to check for work.
  • oauth: settings for integration with oauth2 (during the registration process)
    • url: the base url of the oauth2 provider
    • authorize_path: the path for the authorization request
    • token_path: the path for the authorization grant
    • scopes: the level of access that the application is requesting
    • client_id: the application’s client ID (how the API identifies the application)
    • secret: the application’s client secret
    • domain: the domain name that will be used to construct the user’s primary email address when registering.

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0",
    "result": null
}

Look and feel

See here for more information about the parameters that you see in the examples.

Set a new look and feel for the app

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "app.put_look_and_feel",
    "params": {
        "look_and_feel": {
            "id": 12316549,
            "app_id": "rogerthat",
            "roles": [{
                "role_ids": [1239874, 9879846],
                "service_email": "service-6f962599-270c-49b0-8b30-b7575acf96d2@rogerth.at",
                "service_identity": "+default+"
            }],
            "colors": {
                "primary_color": "#FF0000",
                "primary_color_dark": "#AA0000",
                "primary_icon_color": "#FF0000",
                "tint_color": "#FF0000"
            },
            "homescreen": {
                "color": "#FF0000",
                "items": [{
                    "action_type": null,
                    "action": "messages",
                    "icon": "fa-inbox",
                    "text": "Messages",
                    "collapse": false,
                    "service_email": null
                }, {
                    "action_type": null,
                    "action": "news",
                    "icon": "fa-hacker-news",
                    "text": "News",
                    "collapse": false,
                    "service_email": null
                }, {
                    "action_type": null,
                    "action": "friends",
                    "icon": "fa-users",
                    "text": "Friends",
                    "collapse": false,
                    "service_email": null
                }, {
                    "action_type": null,
                    "action": "scan",
                    "icon": "fa-qrcode",
                    "text": "Scan",
                    "collapse": false,
                    "service_email": null
                }, {
                    "action_type": null,
                    "action": "settings",
                    "icon": "fa-wrench",
                    "text": "Settings",
                    "collapse": false,
                    "service_email": null
                }],
                "style": "news",
                "header_image_url": "https://www.google.be/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"
            },
            "toolbar": {
                "items": [{
                    "action_type": null,
                    "action": "messages",
                    "icon": "fa-inbox",
                    "text": "Messages",
                    "collapse": false,
                    "service_email": null
                }, {
                    "action_type": null,
                    "action": "friends",
                    "icon": "fa-users",
                    "text": "Friends",
                    "collapse": false,
                    "service_email": fnull
                }, {
                    "action_type": null,
                    "action": "scan",
                    "icon": "fa-qrcode",
                    "text": "Scan",
                    "collapse": false,
                    "service_email": null
                }, {
                    "action_type": null,
                    "action": "news",
                    "icon": "fa-newspaper-o",
                    "text": "News",
                    "collapse": false,
                    "service_email": null
                }]
            }
        }
    },
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0",
    "result": (result omitted)  // This is the same object you sent in the API call, but with empty values (in case you didn't supply all parameters) filled in with default values.
}

List all possible look and feel configurations in an app

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "app.list_look_and_feel",
    "params": {
        "app_id": "rogerthat"
    },
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0",
    "result": [result omitted]  // This is a list of AppLookAndFeel objects
}

Test a look and feel for a couple of users

In order to be able to test a new look and feel so only a couple of users receive the look and feel(and no other users using the app), use this API call. This look and feel won’t be saved in the database but will be sent to the specified users.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "app.test_look_and_feel",
    "params": {
        "look_and_feel": AppLookAndFeel // omitted to make this example less cluttered. See above for an example.
        "members": [
            {
                "member": "test@example.com",
                "app_id": "rogerthat"
            }
        ]
    },
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0",
    "result": null
}

Delete a look and feel

Use this API call to delete a look and feel.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "app.delete_look_and_feel",
    "params": {
        "look_and_feel_id": 12345649877
    },
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0",
    "result": null
}

Look and feel objects

Fields marked with an asterisk(*) are optional.

AppLookAndFeel

  • id*: The id of an existing look and feel that should be updated. Omit this parameter to create
    a new look and feel.
  • app_id: The app_id of the app on which this look and feel should be applied.
  • roles: The roles of the users who will make use of this look and feel.
    • role_ids: The id’s of all roles that will use this look and feel
    • service_email: The service email of the service that will use this look and feel.
    • service_identity*:Service identity that will use this look and feel
  • colors: Colors of the app that can be changed
    • primary_color: This is the color of most UI elements.
    • primary_color_dark*: This is the color that will be used to create the gradient used in the toolbar of the sidebar(the part at the bottom). When not supplied, a darkened version of the primary_color will be used.
    • tint_color: iOS only, The color of the icons and text on the navigation bar (at the top of the screen).
    • primary_icon_color: The color of all icons. Most of the time this is the same as the primary_color.
  • homescreen: Settings related to the homescreen and sidebar of the app.
    • color: The color of the icons in the sidebar
    • style: What style should be used. First option is ‘news’ which shows the newsfeed when the app starts, the other option is ‘messages’ which will show the messaging screen when the app starts.
    • header_image_url*: The image in the header of the sidebar
    • items: The items in the sidebar. This is a list of NavigationItems, see below for the structure of it.
  • toolbar: Settings related to the toolbar of the sidebar. This is the part on the bottom of the sidbar.
    • items: The items in the toolbar. This is a list of NavigationItems, see below for the structure of it.

NavigationItem

  • action_type*: null|action|click.
    null means opening an activity
    action means listing all services with that action and opening that action when clicked
    click means clicking on a service menu item (linked to service_email).
    If service_email is None -> the main service email is used
  • action: The screen that clicking this navigation item should open. When action_type is ‘action’ or ‘click’, the ‘action’ parameter should be the hashed tag of the service menu item). Otherwise, if the ‘action_type’ parameter is null, it should be one of the following: news, messages, scan, services, friends, directory, profile, more, settings, community_services, merchants, associations, emergency_services, stream, qrcode.
  • icon: The name of the icon. Currently only font-awesome icons are supported, so they should all start with ‘fa-‘. See http://fontawesome.io/icons/ for all the possible icons.
  • icon_color*: The color of the icon. This should only be used if you want a particular icon to have another color, else the primary_color is used.
  • text: The translation key of this navigation item. Currently only existing keys can be used but in the future you will be able to add custom translations.
  • collapse*: If there is only one service, jump directly to this service instead of showing a list with only one item in it. This is used for example when ‘action’ is ‘community_services’ and your app only contains one community service.
  • service_email*: Only used in combination with action_type ‘click’. This is used to execute the action behind a service menu item action of a service.

News API

Publish a news item

Use this API to publish a news item. It is also used to update an existing news item.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "news.publish",
    "params": {
        "sticky": false,
        "sticky_until": 0,
        "title": "This is an example news item",
        "message": "The message of your news item goes here, it can be very long if you wish.",
        "image": null,
        "news_type": 1,
        "broadcast_type": "news",
        "action_buttons": [
            {
                "id": "test_button",
                "caption": "Click me",
                "action": "https://example.com",
                "flow_params": null,
                "index": 1
            }
        ],
        "qr_code_content": null,
        "qr_code_caption": null,
        "scheduled_at": 0,
        "flags": 3,
        "news_id": null,
        "app_ids": [
            "rogerthat"
        ],
        "service_identity": "+default+"
    },
    "id": "498as4df-e4e2-42f9-8507-45c86a12c84f5"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "3a9d6e7e-e4e2-42f9-8507-71b74c4817e0",
    "result": {
        "title": "This is an example news item",
        "sticky_until": 0,
        "qr_code_content": null,
        "sticky": false,
        "image_url": null,
        "follow_count": -1,
        "flags": 3,
        "rogered": false,
        "app_ids": [
            "rogerthat"
        ],
        "reach": 0,
        "sender": {
            "name": "Example service",
            "email": "cab654ac1a3c84d78fe9e92fc1675f6b",
            "avatar_id": 6105437745184768
        },
        "buttons": [
            {
                "action": "https://example.com",
                "caption": "Click me",
                "id": "url",
                "flow_params": "{}"
            }
        ],
        "scheduled_at": 0,
        "id": 181001,
        "users_that_rogered": [],
        "message": "The message of your news item goes here, it can be very long if you wish.",
        "broadcast_type": "news",
        "version": 1,
        "published": true,
        "qr_code_caption": null,
        "statistics": [],
        "type": 1,
        "action_count": -1,
        "timestamp": 1486129800
    }
}

  • sticky: Wether or not this news item should be ‘sticky’. This means it will show up higher in the newsfeed.
  • sticky_until: timestamp until when the news item should no longer be sticky.
  • title: Title of the news item
  • message: Message of the news item
  • news_type: Type of the news item. Should be either 1 (normal) or 2 (qr code)
  • broadcast_type: Broadcast type of the news item, used so the user can filter by different kinds of news.
  • news_buttons: Additional buttons of the news item where users can interact with.
    Other buttons will be added by default depending on the flags of the news item, allthough only a maximum of 3 buttons are allowed.

    • id: Identifier of the button
    • caption: The caption of the button
    • action: The action linked to this button. possibilities are http, https, geo, tel, mailto, confirm, smi and poke
    • flow_params: in case action ‘poke’ was used to start a flow, these parameters will be supplied to the javascript code in the flow. This can be useful to prefill specific steps with some values that are related to the news item.
  • qr_code_content: Content of the QR code. Should only be used when news_type is 2 (qr code)
  • qr_code_caption: Caption of the QR code. Should only be used when news_type is 2 (qr code)
  • scheduled_at: Timestamp when this news item should be published
  • flags: Flags for this news item.
    1: enable ‘Roger that’ button
    2: enable ‘Follow’ button
    4: Silent news item, no push notifications will be created for this news item
    To set more than 1 flag, use logical ‘OR’. So for both the rogerthat and follow button, set ‘flags’ to 3.
    If you enable both rogerthat and follow buttons, you can only add 1 custom button.
  • news_id: The id of the news item you wish to edit. Leave empty to create a new news item.
  • app_ids: The ids of the apps in which this news item should be shown.
  • service_identity: Optional service identity. Used to display the sender of this news item.

List all news from a service

Get a list of all news items of a service.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "news.list",
    "params": {
        "cursor": null,
        "batch_count":10,
        "service_identity": "+default+"
    },
    "id": "498as4df-e4e2-42f9-8507-45c86a12c84f5"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "498as4df-e4e2-42f9-8507-45c86a12c84f5"
    "result": {
        "cursor": "CkgKGQoPb3JkZXJfdGltZXN0YW1wEgYI1tzLxAUSJ2oTZGV2fm1vYmljYWdlY2xvdWRocnIQCxIITmV3c0l0ZW0Yov4KDBgAIAE="
        "result":[] // Results omitted
    }
}

  • cursor: The cursor to retrieve the next set of news items.
  • batch_count: The amount of items you want to retrieve in this call. Maximum allowed is 100.
  • service_identity: Optional service identity

Delete news item

Delete a news item. Currently it is only possible to delete news items that would be published in the future (news items created with the scheduled_at parameter), and it’s not possible to delete news items that have already been pushed to the users yet.

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "news.delete",
    "params": {
        "news_id": 16549849846,
        "service_identity": "+default+"
    },
    "id": "498as4df-e4e2-42f9-8507-45c86a12c84f5"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "498as4df-e4e2-42f9-8507-45c86a12c84f5"
    "result": null
}

  • news_id: The id of the news item you wish to delete.
  • service_identity: Optional service identity

Disable news item

Greys out a news item. Useful for disabling a news item with a QR code which is no longer valid, for example

Request:

POST /api/1 HTTP/1.1
Content-type: application/json-rpc; charset=utf-8
X-Nuntiuz-API-Key: you_secret_api_key
{
    "method": "news.disable",
    "params": {
        "news_id": 16549849846,
        "members": [{
            "member": "testuser@example.com",
            "app_id": "rogerthat"
        }],
        "service_identity": "+default+"
    },
    "id": "b98b30da-102c-4a41-b423-868d2dee4dee"
}

Response:

HTTP/1.0 200 OK
Content-type: application/json-rpc; charset=utf-8
{
    "error": null,
    "id": "b98b30da-102c-4a41-b423-868d2dee4dee"
    "result": null
}

  • news_id: The id of the news item you wish to delete.
  • members: List of users for who this news item should be disabled.
  • service_identity: Optional service identity

Data structure

Details of data structures

    • attachment:
      • content_type: string with the content type, it can be:
        • image/png
        • image/jpeg
        • application/pdf
      • download_url: string with the url link to download the attachment
      • name: string with the attachment name
      • size: an optional integer which defines attachment size
    • user_details:
      • email: string with the member email
      • name: string with the member name
      • language: string with the member language code i.e. “en” for English
      • avatar_url: string with the link to the member avatar
      • app_id: string with the id of the app.
      • public_key: base64 encoded string representation of the user’s public key. Only provided in case of a Rogerthat-based app secured by a PIN code.
    • beacon:
      • uuid: string which contains beacon universal unique identifier
      • major: string which contains the major of the beacon
      • minor: string which contains the minor of the beacon
      • tag: string which contains beacon tag
    • search_config:
      • enabled: boolean to enable the search
      • keywords: string with keywords to search
      • locations: array with locations:
        • address: string with the address name
        • lon: float with the address longitude
        • lat: float with the address latitude

 


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.


User Invites Service

User directly invites a service using the service email address e.g. demo.service@rogerth.at

The service will receive a friend.invited request with

  • tag is null
  • origin is user_invite

The service can decide to accept or decline the request.

Once the service has accepted the request, the user is not immediately connected to the service. That is only the case once the service has received friend.invite_result with status “established”

  • tag is null
  • origin is user_invite

Service Invites User

The service sends a friend.invite call to Rogerthat. The service can optionally add a tag to this call. This tag can contain metadata which the service can later use to identify why the user was invited.

Some time later, the user will accept or decline the invitation. The service will be notified using the friend.invite_result call with status “accepted” or “declined”:

  • origin is service_invite
  • tag is the tag that the service included in the friend.invite call.

At this point the user is connected to the service, and the service can start sending messages to the user.


User Pokes Non-Connected Service

Typical scenarios:

  • User scans an action QR code of a service to which the user is not yet connected. User sees service detail screen including a poke button with the specific poke action e.g. “Get more info on article XXX”. User clicks that poke button
  • User clicks a web connect button of a service to which the user is not yet connected.

First the user will get connected to the service:

  • Service receives friend.invited with origin = user_poke and tag equals the poketag that was included in the action QR Code
  • Service decides to accept the invitation
  • Once the connection is really established in the Rogerthat platform, the Service receives friend.invite_result. Same origin and tag as in the previous call friend.invited. Now the service can assume that the user is connected. The service should not send an automatic welcome message on a friend.invite_result with a tag, since it will receive a messaging.poke call after this.

Next, the service will be poked with the poketag.


User Pokes Connected Service

Typical scenarios:

  • User scans an action QR code of a service to which the user is already connected. User sees service detail screen including a poke button with the specific poke action e.g. “Get more info on article XXX”. User clicks that poke button
  • User clicks a web connect button of a service to which the user is already connected.

The service receives messaging.poke with the appropriate poketag.


Error codes

System and JSON-RPC errors
1000 System error. An error ID is included in the message. Contact support@mobicage.com to request more information.
1001 Missing field. * field: name of the missing field
1002 Service not enabled!
1003 Incomplete call request. id, method, params are required fields!
1004 JSON-RPC id should be a string
1005 params is not valid JSON object
1006 Unkown JSON-RPC method
1007 Invalid JSON
1008 Invalid callback Error during processing request that was piggybacked on response
Test
2000 Incorrect test reponse See method test.test
Branding errors
10000 Branding could not be validated.
10001 Branding already exists.
10002 Branding is in use and can’t be deleted.
Friends and invitation errors
20000 Invalid email address.
20001 This person was already invited in the last week.
20002 This person was already invited three times.
20003 Can not invite yourself.
20004 This person is not a Rogerthat user and does not want to be invited to become a Rogerthat user via email.
20005 Cannot request location from service users.
20006 User not found via userCode * user_code: User code used in invitation
20007 This person is already your friend
20008 Cannot invite services.
Messaging errors
30000 Member is not in your friend list. * member: The member which is not in your friend list
30001 Parent message not found.
30002 Illegal sender answer.
30003 Invalid flags.
30004 Tag too large.
30005 Unknown answer widget type. * widget_type: Supplied unsupported widget type
30006 Unsupported answer action type. * scheme: Unsupported URI scheme
30007 Branding not found.
30008 Incomplete button.
30009 Message not found.
30010 Message is already locked.
30011 Autoseal flag implies maximum one member.
30012 Undismissable messages need at least one answer.
30013 Duplicate members.
30014 Duplicate button ids.
30015 Can not send to services. * member: Service member
30016 Invalid dirty_behavior.
30017 Invalid alert flags.
30018 You cannot combine multiple alert ring flags.
30019 You cannot combine multiple alert interval flags.
30020 Invalid value in widget. * property: the name of the property with the invalid value.
30021 Value too long.
30022 No choices specified.
30023 Duplicate label in choices. * label: the duplicate label
30024 Duplicate value in choices. * value: the duplicate value
30025 Duplicate value. * value: the duplicate value
30026 Value not in choices * value: value that is not in choices
30027 Value not within boundaries.
30028 Invalid boundaries.
30029 Invalid values for range.
30030 At least 2 choices needed.
30031 Invalid unit format. * missing_tag: the tag which is mandatory in the format.
30032 Suggestion too long. *index: the index of the suggestion whose length is too long.
30033 Members of a child message should be the same as members of the parent message.
30034 Non-dismissable messages can not have dismiss button ui flags.
30035 Invalid button ui flags. * button: the ID of the button with the invalid ui flag.
30036 Invalid dismiss button ui flags.
30037 Invalid mode for date_select widget.
30038 The minimum minute_interval value is 1; the maximum minute_interval value is 30.
30039 The minute_interval must be a divisor of 60.
30040 Step can not be greater than the slider range.
30041 Invalid value in date_select with mode ‘time’. The min_date, max_date and date values should be between 0
and 86400.
30042 Invalid value in date_select with mode ‘date’. The min_date, max_date and date values should be multiples of
86400.
30043 The min_date, max_date and date values should be multiples of minute_interval. * minute_interval: the provided minute interval
30044 Tag should not start with __rt__
30045 This branding can not be used for messages.
30046 Invalid Form
30047 Invalid quality in photo_upload.
30048 No source to select a picture has been provided.
30049 Invalid ratio in photo_upload.
30050 Not all attachment download URLs are reachable. * reason: the reason why an attachment was not reachable.
30051 Invalid attachment * reason: the reason why an attachment is invalid
Message flow errors
40001 Message flow not found.
40002 Cannot launch message flow for members who are not connected to your service. * non_members: provided members which are not connected to your service
40003 Cannot launch message flow since it is not in a valid state. * error: the error in your message flow
40004 Cannot launch message flow to multiple members if parent_message_key is not null.
40005 Cannot launch message flow. No members found.
40006 Message flow can not be deleted. * reason: the reason why the message flow cannot be deleted.
40007 The XML is not conform to the message flow design XML schema.
40008 Message flow design is not valid.
40009 Unexpected language specified in message flow design XML.
QR code errors
50001 Invalid QR code color specification.
50002 Invalid QR code description.
50003 Invalid QR code template size.
Service Identities
60000 Service Identity does not exist. * service_identity: service_identity that not exist
60001 Invalid value * property: the name of the property with the invalid value
* reason: the reason why the value is invalid
60002 A menu item has an x, y and page coordinate, with x and y smaller than 4.
60003 This menu item is reserved.
60004 There are still broadcast settings menu items.
60005 Invalid broadcast type * broadcast_type: the invalid broadcast type
60006 Duplicate broadcast type * broadcast_type: the duplicate broadcast type
60008 Invalid name
60009 Service with that e-mail address already exists
60010 This language is not supported
60011 User not in friends list
60012 Can not parse data as json object
60013 Expected a square input image
60014 Category not found
60015 Callback not defined
60016 Beacon already coupled * uuid: beacon uuid
* major: beacon major
* minor: beacon minor
60017 Invalid app_id * app_id
60018 Unsupported app_id * app_id
60019 Role does not exist * role_id
60020 Role with this name already exists * name
60021 Invalid role type * type
60022 Cannot delete role which is still granted to people. * role_id
60023 Cannot delete role which is still connected to a service menu item * role_id
60024 An account with this e-mail address already exists. * email
60025 No permission to manage app * app_id
60026 There is no service with this email * service_identity_email
60027 There is no beacon region for this beacon. Please contact Mobicage for support. * uuid
* major
* minor
60028 Not all supported apps of this service implement MYDIGIPASS. * unsupported_app_ids
60032 Failed to resolve url * url
60033 Failed to create user profile with the same email as a service account * email
60034 Invalid key * key
60035 Duplicate category id * category_id
60035 Duplicate item id * category_id
* item_id
News errors
90001 News item not found * news_id
90002 Cannot unstick news item * news_id
90003 Too many news buttons, only a maximum of 3 are allowed. * news_id
90004 Property cannot be changed after publishing a news item * news_id
* property_name
90005 Missing property. * property_name
90006 Invalid news type * news_type
90007 No permission to news item. You can only edit your own news items. * news_id
90008 Value too long * property_name
* max_length
90009 Demo service can only publish news in demo apps * app_id
90010 A trial service may not publish news
90011 Invalid scheduled timestamp, it must be in the future
90012 Cannot delete published news * news_id
Look and feel errors
100001 Look and feel not found * look_and_feel_id
100002 The specified ‘style’ must be present in either the homescreen items or toolbar items. * style