> For the complete documentation index, see [llms.txt](https://oswaldai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oswaldai.gitbook.io/docs/integration-api/sending-a-message.md). # 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. ![](https://4289899849-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L_SGK8BUbabvzNaUQiP%2F-L_SIxH8WLqJZ1NzZYTB%2F-L_SJbvdiQbmYD2z1Xiy%2Fid.png?alt=media\&token=28a3a1f5-7d93-4545-8ae7-dc0d9945a541) The payload of the `POST` request should look like this: ```javascript { "message": "", "environment": "", "session": "", "locale": "" } ``` 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: ```javascript { "environment": "production", "session": "", "locale": "" } ``` ### **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*](https://code.oswald.ai/) 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. ```javascript { "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: ```javascript { "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.