Sending a message

Documentatie Advanced code responses Integration API Launch Oswald
Search…
Integration documentation
English documentation
What is the integration API
Authentication
Sending a message
Accessing message history
Forget session data
Widget integration
Nederlandstalige documentatie
Wat is de integratie API?
Authenticatie
Bericht versturen
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:
1
{
2
    "message": "<THE MESSAGE OF THE USER>",
3
    "environment": "<ENVIRONMENT OF THE CHATBOT>",
4
    "session": "<SESSION IDENTIFIER>",
5
    "locale": "<LOCALE OF THE CHATBOT>"
6
}
Copied!
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:
1
{
2
    "environment": "production",
3
    "session": "<SESSION IDENTIFIER>",
4
    "locale": "<LOCALE OF THE CHATBOT>"
5
}
Copied!
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.
1
{
2
    "environment": "production",
3
    "session": "12345",
4
    "message": "Hallo!",
5
    "locale": "nl-BE",
6
    "metadata:" {
7
        "firstname": "Michiel",
8
        "lastname": "Vandendriessche"
9
    }
10
}
Copied!
Receiving a message
As a response on your POST requests, you will receive a JSON-object in the following form:
1
{
2
  "data": [
3
    {
4
      "type": "text",
5
      "message": "hello, this shows all types of messages",
6
      "url": null,
7
      "image": null
8
    },
9
    {
10
      "type": "image",
11
      "message": "an image with a caption",
12
      "url": null,
13
      "image": "http://example.com/image.png"
14
    },
15
    {
16
      "type": "url",
17
      "message": "have a look at this url",
18
      "url": "https://docs.oswald.ai",
19
      "image": null
20
    },
21
    {
22
      "type": "location",
23
      "message": "message",
24
      "url": null,
25
      "image": null,
26
      "elements": {
27
        "latitude": "50.8650119",
28
        "longitude": "4.6691501"
29
      }
30
    },
31
    {
32
      "type": "video",
33
      "message": "have a look at this oswald video",
34
      "url": "https://www.youtube.com/watch?v=WgZ6XeeP_Cg",
35
      "image": null
36
    },
37
    {
38
      "type": "carrousel",
39
      "message": "",
40
      "url": null,
41
      "image": null,
42
      "elements": {
43
        "items": [
44
          {
45
            "buttons": [
46
              {
47
                "action": "Tell me more",
48
                "title": "Tell me more about Oswald"
49
              }
50
            ],
51
            "image_url": "https://example.com/test",
52
            "subtitle": "just one item though",
53
            "title": "carousel"
54
          }
55
        ]
56
      }
57
    }
58
  ],
59
  "id": "5e550a6656c845835299d216",
60
  "session": "493690",
61
  "environment": "test",
62
  "type": "out",
63
  "takeover": null,
64
  "quickReplies": null,
65
  "locale": "nl-BE",
66
  "metadata": {
67
    "state": "start",
68
    "junk": false,
69
    "error": false,
70
    "label": "show-all-message-types",
71
    "sentence": "toon me alle soorten berichten",
72
    "tokens": [
73
      "toon",
74
      "me",
75
      "alle",
76
      "soorten",
77
      "berichten"
78
    ],
79
    "enriched_tokens": [
80
      "toon",
81
      "me",
82
      "alle",
83
      "soorten",
84
      "berichten"
85
    ],
86
    "entities": [],
87
    "context": {
88
      "session": "493690",
89
      "label": "show-all-message-types",
90
      "entities": [],
91
      "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\"}",
92
      "dialogStack": [],
93
      "environment_variables": {
94
        "API base URI": "api.oslkqjsdhflkjqsdhflqksjdfh.be."
95
      },
96
      "state": "start",
97
      "chatbotId": "5cebe4d686046f0005f4e7a0",
98
      "contextVariables": {},
99
      "previous_quickreplies": []
100
    },
101
    "new_context": {
102
      "session": "493690",
103
      "label": "show-all-message-types",
104
      "entities": [],
105
      "sessionInfo": {},
106
      "dialogStack": [],
107
      "environment_variables": {},
108
      "state": "start",
109
      "chatbotId": "5cebe4d686046f0005f4e7a0",
110
      "contextVariables": {},
111
      "previous_quickreplies": []
112
    },
113
    "firedRules": [
114
      {
115
        "id": "5e54fc87c10187eebf993176",
116
        "dialog": "5e54fc87c10187300c993175",
117
        "score": 100,
118
        "label": "any => 'None'  => any"
119
      }
120
    ],
121
    "responseId": "5e54fc87c10187eebf993176",
122
    "dialogId": "5e54fc87c10187300c993175",
123
    "responseTrack": [
124
      {
125
        "type": "response",
126
        "number": 1,
127
        "responseId": "5e54fc87c10187eebf993176",
128
        "dialogId": "5e54fc87c10187300c993175",
129
        "skipReturn": false
130
      }
131
    ],
132
    "times": {
133
      "preprocessing": 1.36,
134
      "labeling": 0.01,
135
      "context": 3.76,
136
      "response_time": 40.28,
137
      "error_time": 0
138
    },
139
    "currentTags": [
140
      "not_understood"
141
    ],
142
    "estimates": [
143
      {
144
        "label": "show-all-message-types",
145
        "probability": 1
146
      }
147
    ],
148
    "variables": null
149
  },
150
  "processed": "45.67 milliseconds",
151
  "time": 53,
152
  "queue": "oswald-out-14ab6f00-06d6-46ae-aebe-acbb3ed8c595",
153
  "chatbotId": "5cebe4d686046f0005f4e7a0",
154
  "chatbotName": "Demo chatbot"
155
}
Copied!
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.
English documentation - Previous
Authentication
Next - English documentation
Accessing message history
Last modified 2yr ago
Copy link
Contents
Triggering the startup message
Sending metadata
Receiving a message