Sending a message
Sending a message to the chatbot requires you to execute an HTTP
POST requests to this endpoint:/chats/{id}/messageThe
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. |
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>"
}
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"
}
}
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.