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:

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.

Last updated