Sending a message

Sending a message to the chatbot requires you to execute an HTTP POST requests to this endpoint:

/chats/{id}/message

The id of the chatbot can be found in the URL of Oswald when configuring the chatbot.

The payload of the POST request should look like this:

{
    "message": "<THE MESSAGE OF THE USER>",
    "environment": "<ENVIRONMENT OF THE CHATBOT>",
    "session": "<SESSION IDENTIFIER>",
    "locale": "<LOCALE OF THE CHATBOT>"
}

In the following table you can find a detailed description of every value in the payload:

Name	Type	Possible values	Description
message	String	Can be any text value	The message from the user that needs to be sent to the chatbot.
environment	String	"production" or "test"	The environment of the chatbot, which can be either "production" of "test". The default value expected here is "production" in which case the published version of the chatbot will be contacted. In special cases the value "test" can be given to test the development version of your chatbot.
session	String	Can be any value	The session identifier. The value of this parameter can be of your own choosing, but must be unique per user session. When two session identifiers match, Oswald will assume a single conversation.
locale	String	Any valid locale	The locale of the chatbot you want to contact. If the chatbot has that locale configured (e.g. en-gb) , the correct chatbot will answer your request. If you set this variable to be an unconfigured value, the default locale will be used as a fallback.

Triggering the startup message

If you want to receive the configured startup message from the chatbot, you can send the folowing payload:

{
    "environment": "production",
    "session": "<SESSION IDENTIFIER>",
    "locale": "<LOCALE OF THE CHATBOT>"
}

Sending metadata

In Oswald it's possible to send a metadata payload alongside you main user input. This JSON object can be anythong you want. In an Oswald advanced code response it's possible to read out this object through the sentence-object: sentence.metadata. This enables sending more information about the user to the chatbot, such as short lived acces tokens, name, etc.

{
    "environment": "production",
    "session": "12345",
    "message": "Hallo!",
    "locale": "nl-BE",
    "metadata:" {
        "firstname": "Michiel",
        "lastname": "Vandendriessche"
    }
}

Receiving a message

As a response on your POST requests, you will receive a JSON-object in the following form:

{
  "data": [
    {
      "type": "text",
      "message": "hello, this shows all types of messages",
      "url": null,
      "image": null
    },
    {
      "type": "image",
      "message": "an image with a caption",
      "url": null,
      "image": "http://example.com/image.png"
    },
    {
      "type": "url",
      "message": "have a look at this url",
      "url": "https://docs.oswald.ai",
      "image": null
    },
    {
      "type": "location",
      "message": "message",
      "url": null,
      "image": null,
      "elements": {
        "latitude": "50.8650119",
        "longitude": "4.6691501"
      }
    },
    {
      "type": "video",
      "message": "have a look at this oswald video",
      "url": "https://www.youtube.com/watch?v=WgZ6XeeP_Cg",
      "image": null
    },
    {
      "type": "carrousel",
      "message": "",
      "url": null,
      "image": null,
      "elements": {
        "items": [
          {
            "buttons": [
              {
                "action": "Tell me more",
                "title": "Tell me more about Oswald"
              }
            ],
            "image_url": "https://example.com/test",
            "subtitle": "just one item though",
            "title": "carousel"
          }
        ]
      }
    }
  ],
  "id": "5e550a6656c845835299d216",
  "session": "493690",
  "environment": "test",
  "type": "out",
  "takeover": null,
  "quickReplies": null,
  "locale": "nl-BE",
  "metadata": {
    "state": "start",
    "junk": false,
    "error": false,
    "label": "show-all-message-types",
    "sentence": "toon me alle soorten berichten",
    "tokens": [
      "toon",
      "me",
      "alle",
      "soorten",
      "berichten"
    ],
    "enriched_tokens": [
      "toon",
      "me",
      "alle",
      "soorten",
      "berichten"
    ],
    "entities": [],
    "context": {
      "session": "493690",
      "label": "show-all-message-types",
      "entities": [],
      "sessionInfo": "{\"identifier\": \"493690\", \"platform\": \"API\", \"takeover\": {\"state\": \"3SUGGESTED\", \"changedAt\": {\"$date\": 1582631499214}}, \"metadata\": {\"ips\": [\"::ffff:10.44.207.2\"]}, \"updatedAt\": {\"$date\": 1582631526932}, \"createdAt\": {\"$date\": 1582631499166}, \"archived\": \"unarchived\", \"environment\": \"test\", \"tags\": [\"not_understood\"], \"lastSeen\": {\"$date\": 1582631507295}, \"locale\": \"nl-BE\", \"terminated\": null, \"userLocale\": \"nl-BE\"}",
      "dialogStack": [],
      "environment_variables": {
        "API base URI": "api.oslkqjsdhflkjqsdhflqksjdfh.be."
      },
      "state": "start",
      "chatbotId": "5cebe4d686046f0005f4e7a0",
      "contextVariables": {},
      "previous_quickreplies": []
    },
    "new_context": {
      "session": "493690",
      "label": "show-all-message-types",
      "entities": [],
      "sessionInfo": {},
      "dialogStack": [],
      "environment_variables": {},
      "state": "start",
      "chatbotId": "5cebe4d686046f0005f4e7a0",
      "contextVariables": {},
      "previous_quickreplies": []
    },
    "firedRules": [
      {
        "id": "5e54fc87c10187eebf993176",
        "dialog": "5e54fc87c10187300c993175",
        "score": 100,
        "label": "any => 'None'  => any"
      }
    ],
    "responseId": "5e54fc87c10187eebf993176",
    "dialogId": "5e54fc87c10187300c993175",
    "responseTrack": [
      {
        "type": "response",
        "number": 1,
        "responseId": "5e54fc87c10187eebf993176",
        "dialogId": "5e54fc87c10187300c993175",
        "skipReturn": false
      }
    ],
    "times": {
      "preprocessing": 1.36,
      "labeling": 0.01,
      "context": 3.76,
      "response_time": 40.28,
      "error_time": 0
    },
    "currentTags": [
      "not_understood"
    ],
    "estimates": [
      {
        "label": "show-all-message-types",
        "probability": 1
      }
    ],
    "variables": null
  },
  "processed": "45.67 milliseconds",
  "time": 53,
  "queue": "oswald-out-14ab6f00-06d6-46ae-aebe-acbb3ed8c595",
  "chatbotId": "5cebe4d686046f0005f4e7a0",
  "chatbotName": "Demo chatbot"
}

In this object you can find a lot of information about the sent request and the NLP estimations. The most important property is data. This is an array of message objects where eacht object can have a different type and properties. These are the objects that will have to be visualized in your frontend. The types can be text, images, urls, carroussels, locations, Youtube links, etc.