Skip to main content
  1. Botium Support
  2. Technical Reference
  3. Developer Section

Supported Capabilities for HTTP(S)/JSON Based APIs

This article details configuring SIMPLEREST capabilities in Botium, including URL construction, HTTP methods, headers setup, and the role of Mustache templates in creating custom chatbot connections. It also explains the use of JSONPath expressions, unique conversation IDs, and scripting memory functions.

Mustache Variables

For building up URLs, HTTP Headers, and HTTP Body, Mustache templates are used. Several Mustache variables are available; this is the Mustache view object constructed:
{
  "container": <current-container>,
  "context": <session-context>,
  "msg": <botium-message>,
  "botium": {
    "conversationId": <uniq-id-for-conversation>,
    "stepId": <uniq-id-for-conversation-step>
  },
  "fnc": {
    <scripting-memory-functions>,
    "jsonify": <json-escape string>
  }
}

Explanation

  • context: This is the current session context, as initialized with the capability SIMPLEREST_INIT_CONTEXT and updated on each conversation step from the HTTP response with the capability SIMPLEREST_CONTEXT_JSONPATH (see below for details).

    For example, if the session context holds something like a sessionId to be part of the message body, this can be done by initializing the session context with:
    {
  "SIMPLEREST_INIT_CONTEXT": { "sessionId": "" },
  "SIMPLEREST_CONTEXT_JSONPATH": "$.session",
  "SIMPLEREST_BODY_TEMPLATE": {
    "text": "{{msg.messageText}}",
    "sessionId": "{{context.sessionId}}"
  }
}
  • msg: This is the Botium message in its internal representation. You can use the full structure of the message. Here are some details:
    • Message Text
    • Test Project Name
    • Test Session Name
    • Convo Name

  • botium: In this scope, for convenience, there are unique IDs for the conversation and for each conversation step available. A possible use case is chatbot endpoints where the session identifier is to be generated by the client, not by the server.

    You can use them in this way:
    {
  "SIMPLEREST_BODY_TEMPLATE": {
    "text": "{{msg.messageText}}",
    "stepId": "{{botium.stepId}}",
    "conversationId": "{{botium.conversationId}}"
  }
}
    In case there are special formatting requirements for those, you can use the capabilities SIMPLEREST_CONVERSATION_ID_TEMPLATE and SIMPLEREST_STEP_ID_TEMPLATE (see below) as templates for generating those values.
  • fnc: Scripting memory functions are available under this scope. You can use all Scripting Memory features of Botium in the Mustache templates.
    Note:
    Some Mustache examples
    Tip: In case you don’t want Mustache to do URL/HTML encoding with your texts (which you typically don’t want for HTTP POST endpoints), use triple braces {{{ … }}} as placeholders instead of double.

    • Using length scripting memory variable: {{msg.scriptingMemory.length}}

    • Using year function: {{fnc.year}}

    • Using random function with parameter: {{#fnc.random}}5{{/fnc.random}}

    • Using random function with parameter from scripting memory: {{#fnc.random}}{{msg.scriptingMemory.length}}{{/fnc.random}}

    • Using environment variable: {{#fnc.env}}MY_PERSONAL_TOKEN{{/fnc.env}}

      • Useful for handing over secrets like authentication headers

SIMPLEREST_URL

This points to the URL of your endpoint. On each request, the URL can be adapted to the current context and message by using Mustache rendering.

Example: Constructing the URL from context and message content:
https://my-api-website/api/{{context.conversation_id}}/{{msg.messageText}}

The URL is constructed by a base URL (https://my-api-website/api/) and extended by a context variable (conversation_id) which has been retrieved previously and by the text of the current message to send to the chatbot.

SIMPLEREST_METHOD

Default: GET

Either GET or POST.

SIMPLEREST_TIMEOUT

HTTP Timeout (default 10 seconds).

SIMPLEREST_HEADERS_TEMPLATE

If you require HTTP headers to be sent to the endpoint (for example, for authorization), this is the capability to configure. The headers are constructed as a Mustache template and can be extended with current context or message variables. It is a JSON structure that contains key/value pairs for HTTP headers and values.

Example: Sending an API Token:
{ "apiToken": "testapitoken" }

SIMPLEREST_BODY_TEMPLATE

For POST endpoints, the HTTP body to be sent to the endpoint. Again, Mustache rendering is applied.

Example: Sending the message text and the current conversation id in the HTTP body:
{ "text": "{{msg.messageText}}", "conversation_id": "{{context.conversation_id}}" }

SIMPLEREST_BODY_RAW

By default, a JSON structure is sent to the HTTP endpoint. If you want to send raw data (for example: x-www-form-urlencoded), set this capability to prevent JSON formatting.

SIMPLEREST_BODY_JSONPATH

Available since Botium Core 1.6.2

If your endpoint is delivering multiple independent responses to be shown to the user, this JSONPath Expression can be used to split the HTTP response body into multiple chunks to be handled by the other JSONPath Expressions below individually.

Example: This response contains multiple text messages:
{
  "responses": [
    {
      "text": "text 1",
      "media": "http://botium.at/1.jpg"
    },
    {
      "text": "text 2",
      "media": "http://botium.at/2.jpg"
    },
    {
      "text": "text 3",
      "media": "http://botium.at/3.jpg"
    }
  ]
}
Example: Set of capabilities to handle this response:
{
  "SIMPLEREST_BODY_JSONPATH": "$.responses[*]",
  "SIMPLEREST_RESPONSE_JSONPATH": "$.text",
  "SIMPLEREST_MEDIA_JSONPATH": "$.media"
}

You can see in this example that the SIMPLEREST_BODY_JSONPATH capability splits the response into multiple chunks, and the other JSONPath expressions are evaluated relative to them, three times.

SIMPLEREST_CONTEXT_IGNORE_JSONPATH / SIMPLEREST_CONTEXT_IGNORE_MATCH

Evaluate a JSONPath expression against the context (by default, the response body, see below). If the path exists (and if it matches, if a match is given), then the full response is ignored by Botium.

Example: This response contains multiple text messages and an “ignore” flag:
{
  "response": {
    "text": "text 1",
    "ignore": "y"
  }
}

{
  "response": {
    "text": "text 1",
    "ignore": "n"
  }
}

Example:

{
  "SIMPLEREST_CONTEXT_IGNORE_JSONPATH": "$.ignore",
  "SIMPLEREST_CONTEXT_IGNORE_MATCH": "y"
}
Note: The first response is ignored, the second one is not.

SIMPLEREST_CONTEXT_SKIP_JSONPATH / SIMPLEREST_CONTEXT_SKIP_MATCH

Similar to above, the current response is ignored, but an additional empty message is sent to continue the conversation.

SIMPLEREST_CONTEXT_CONTINUE_JSONPATH / SIMPLEREST_CONTEXT_CONTINUE_MATCH

Similar to above, the current response is processed, and an additional empty message is sent to continue the conversation.

SIMPLEREST_RESPONSE_JSONPATH

This capability is for extracting the actual response texts from the HTTP response body of the endpoint. This is given as a JSONPath Expression (JSONPath online evaluator), and in case your endpoint returns more than one response, there can be additional capabilities starting with the SIMPLEREST_RESPONSE_JSONPATH prefix. Every single capability is evaluated against the HTTP response body of the endpoint, yielding one chatbot response message per expression.

Example: The “text” attribute of the JSON response contains the message content:
{
  "SIMPLEREST_RESPONSE_JSONPATH": "$.text.*"
}
Example: There are additional “quick response” elements to be extracted as text:
{
  "SIMPLEREST_BUTTONS_JSONPATH": "$.quick_response.*"
}
Example: Add multiple JSONPath expressions as array: The two examples from above can be combined like this:
{
  "SIMPLEREST_RESPONSE_JSONPATH": ["$.text.*", "$.quick_response.*"]
}
Example: Add multiple JSONPath expressions with separator: Or like this:
{
  "SIMPLEREST_RESPONSE_JSONPATH_SOMETHING_COMPLETELY_DIFFERENT": "$.text.*,$.quick_response.*"
}

SIMPLEREST_IGNORE_EMPTY

Make Botium skip empty messages from processing (no text, no attachments, no buttons, no nlp …).

Default empty content is ignored.

SIMPLEREST_CONTEXT_JSONPATH

The session variables you have to store in the current session context are extracted from the HTTP response body of the endpoint. This is a JSONPath Expression, just use “$” to use the full HTTP response body as session context (default: use full body). Can be specified multiple times, all found sections will be merged.

SIMPLEREST_MEDIA_JSONPATH

JSONPath Expression(s) for retrieving media attachments from the response body.

See SIMPLEREST_RESPONSE_JSONPATH for how to use it with multiple JSONPath expressions.

SIMPLEREST_BUTTONS_JSONPATH

JSONPath Expression(s) for retrieving buttons from the response body.

See SIMPLEREST_RESPONSE_JSONPATH for how to use it with multiple JSONPath expressions.

SIMPLEREST_INIT_TEXT

Some chatbots require an introductory “trigger” text from the user to start working (and maybe present a welcome message). To get the conversation rolling, the text in this capability is sent to the endpoint before actually starting the conversation. The context is evaluated (see SIMPLEREST_CONTEXT_JSONPATH), but the text response is ignored.

SIMPLEREST_INIT_CONTEXT

The initial value for the session context.

Example: Init context variable conversation_id:

jsonCopy code{"conversation_id":"none"}

SIMPLEREST_CONVERSATION_ID_TEMPLATE

Optional Mustache template. If it is not set, then a UUID will be generated.

Example: Generating a 13-digit long timestamp:
{{fnc.timestamp}}

SIMPLEREST_STEP_ID_TEMPLATE

Optional Mustache template. If it is not set, then a UUID will be generated.

Example: Generating an 8-digit long random number:
{{#fnc.random}}8{{/fnc.random}}

Was this article helpful?

0 out of 0 found this helpful