Overview

To simplify the development of your Rogerthat service, and to speed up the user experience, it is possible to use the Rogerthat API in the so-called “fast mode”.

  1. Rogerthat notifies your service that a user has pressed a button “Yes” on the question “Do you want more information?”. This happens by an HTTPS call from Rogerthat to your web service.
  2. Your service responds to this first HTTPS call with a 200 OK.
  3. Your service now makes an HTTPS call to Rogerthat to send a follow-up message containing the requested information.
  4. Rogerthat responds to HTTPS call with a 200 OK containing the message key for this last message.
  1. Rogerthat notifies your service that a user has pressed a button “Yes” on the question “Do you want more information?”. This happens by an HTTPS call to your web service.
  2. Your service responds to this HTTPS call with a 200 OK, but immediately embeds the next message in this HTTPS response, saving one round trip.

Which operations are available in the fast path?

The following actions are supported:

  • Start a new message flow
  • Send a new message
  • Send a new form

When to use the fast path?

The fast path can be used by piggybacking the action on the HTTPS response of the following callbacks:

  • TPS (third party service, i.e. your web service) receives a messaging.poke callback.
  • TPS receives a messaging.update callback with flag STATUS_ACKED set. This update indicates the button on which the user has pressed.
  • TPS receives a messaging.form_update callback. This update contains the content of a form submitted by the user.
  • TPS receives a messaging.flow_member_result callback. This update contains the full set of responses of a user to a message flow.

Starting a message flow in the fast path

The following fields must be included in the fast HTTPS response (see API messaging.start_flow):

  • type is “flow”
  • value is an object with fields:
    • (string) flow – the id of the flow
    • (optional string) tag – tag for the flow. This tag will be included when you receive the flow result
    • (optional string) force_language – force flow in a certain language

The following fields cannot be modified and are automatically set based on the context:

  • service_identity: the same service_identity is used as the one of the original HTTPS callback request
  • member: the same member is used as the one of the original HTTPS callback request
  • parent_message_key: the same parent_message_key is used as the one of the original HTTPS callback request
  • flow_key: is identical to the result_key field that was included in the original HTTPS callback request

Example request from Rogerthat to your TPS – user John Doe has pressed the button with id “fine”. A callback is sent to the TPS:

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": 1358842575, 
        "message_key": "a2fcb56a-e302-4ab2-8266-0fcbe93252f6", 
        "service_identity": "+default+", 
        "member": "john@example.com", 
        "parent_message_key": "a2fcb56a-e302-4ab2-8266-0fcbe93252f6", 
        "tag": "37AAF801-CE21-4AC5-9F43-E8E403E1EB5F", 
        "result_key": "ee6dc5a4-9937-4fed-ab2d-c55ea18b5676", 
        "user_details": [
            {
                "email": "john@example.com", 
                "language": "en", 
                "name": "John Doe"
            }
        ], 
        "acked_timestamp": 1358842590, 
        "answer_id": "fine"
    }, 
    "method": "messaging.update", 
    "id": "07621068-646c-11e2-bbe5-932f1968aa23"
}

Example response which immediately starts a flow to same member, using same parent_message_key, same service_identity:

{ "id": "07621068-646c-11e2-bbe5-932f1968aa23"
  "error": null,
  "result": { "type":"flow",
              "value": {"flow": "myflowid",
                        "tag": "mytag",
                        "force_language": null
                        }
            }
}

By responding with this HTTPS request, the TPS will

  • start a flow with id “myflowid”
  • using service_identity “+default+” (same as original request)
  • for user John Doe (same as original request)
  • with parent message key “a2fcb56a-e302-4ab2-8266-0fcbe93252f6” (same as original request)
  • with tag “mytag”
  • with force_language null (i.e. use the default language of John Doe i.e. English)

The flow run id is “ee6dc5a4-9937-4fed-ab2d-c55ea18b5676” which was the result_key field in the original HTTPS request.

Sending a new message in the fast path

The following fields must be included in the fast HTTPS response (see API messaging.send):

  • type is “message”
  • value is an object with fields:
    • message: string containing message text
    • answers: array containing predefined buttons (see messaging.send API)
    • branding: string identifying branding
    • tag: string tag
    • flags: flags for this message
    • alert_flags: alert_flags for this message
    • dismiss_button_ui_flags: UI flags

The following fields cannot be modified and are automatically set based on the context:

  • service_identity: the same service_identity is used as the one of the original HTTPS callback request
  • member: the same member is used as the one of the original HTTPS callback request
  • parent_message_key: the same parent_message_key is used as the one of the original HTTPS callback request
  • message_key: is identical to the result_key field that was included in the original HTTPS callback request

Example response which immediately sends a message to same member, using same parent_message_key, same service_identity:

{ "id": "07621068-646c-11e2-bbe5-932f1968aa23"
  "error": null,
  "result": { "type":"message",
              "value": {"message": "msg text",
                        "answers": [],
                        "branding": "mybranding",
                        "tag": "mytag",
                        "flags": 0,
                        "alert_flags": 0,
                        "dismiss_button_ui_flags": 1
                        }
            }
}

Sending a new form in the fast path

The following fields must be included in the fast HTTPS response (see API messaging.send_form):

  • type is “form”
  • value is an object with fields:
    • message: string containing message text
    • branding: string identifying branding
    • tag: string tag
    • alert_flags: alert_flags for this message
    • form: form information

The fields that cannot be modified are the same as for sending a message.

Example response which immediately sends a form to same member, using same parent_message_key, same service_identity:

{ "id": "07621068-646c-11e2-bbe5-932f1968aa23"
  "error": null,
  "result": { "type":"form",
              "value": { "alert_flags": 0,
                         "branding": null,
                         "message": "What time can we deliver your order?",
                         "tag": "my message tag19347819",
                         "form": { "type": "range_slider",
                                   "positive_button": "Submit",
                                   "positive_button_ui_flags": 1,
                                   "negative_button": "Abort",
                                   "positive_button_ui_flags": 0,
                                   "negative_confirmation": "Really abort?",
                                   "widget": { "min": 1,
                                               "max": 6,
                                               "step": 1,
                                               "low_value": 1,
                                               "high_value": 6,
                                               "precision": 2,
                                               "unit": "Between <low_value/>pm - <high_value/>pm"
                                             }
                                 }
                       }
            }
}