Bericht versturen

Om een bericht te versturen naar de chatbot, doe je een HTTP POST request naar de volgende endpoint:

/chats/{id}/message

De id van de chatbot vind je in de URL van Oswald als je de chatbot configureert.

De payload van deze request moet er zo uitzien:

{
    "message": "<HET BERICHT VAN DE GEBRUIKER>",
    "environment": "<ENVIRONMENT VAN DE CHATBOT>",
    "session": "<SESSION IDENTIFIER>",
    "locale": "<LOCALE VAN DE CHATBOT>"
}

In de tabel hieronder wordt elke property van deze payload beschreven:

Naam	Type	Mogelijke waarden	Beschrijving
message	String	Mag alles zijn	Het bericht dat de gebruiker naar de chatbot verstuurt.
environment	String	"production" of "test"	De environment van de chatbot. In principe geef je hier altijd "production" mee. Dan zal je de gepubliceerde versie van de chatbot aanspreken. In uitzonderlijke gevallen kan je eventueel ook "test" meegeven om de development versie van de chatbot te testen.
session	String	Mag alles zijn	De identifier van de sessie. Dit mag je zelf kiezen, maar houd deze uniek per sessie! Wanneer je dezelfde sessie identifier meegeeft, zal Oswald ervanuit gaan dat het over hetzelfde gesprek gaat.
locale	String	Eender welke locale	De locale van de chatbot die je wil aanspreken. Als je chatbot geconfigureerd is in "nl-BE", kan je deze meegeven. Indien je een locale meegeeft die niet geconfigureerd is in de chatbot, zal de chatbot terugvallen op zijn default locale.

Startbericht versturen

Wanneer je wil dat de chatbot zijn startbericht verstuurt om de conversatie te starten, geef je de volgende payload mee:

{
    "environment": "production",
    "session": "<SESSION IDENTIFIER>",
    "locale": "<LOCALE VAN DE CHATBOT>"
}

Metadata versturen

Het is in Oswald mogelijk om metadata mee te geven aan de chatbot. Dit is een object waar je alles kan inzetten wat je wil. Een developer van Oswald kan deze via het sentence-object in een advanced code response lezen: sentence.metadata. Zo kan je bijvoorbeeld extra informatie over de gebruiker meesturen naar de chatbot:

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

Een bericht ontvangen

Als reply op je POST request, krijg je een JSON-object in de volgende vorm:

{
  "data": [
    {
      "type": "text",
      "message": "Hey! Wat is jouw naam?",
      "url": null,
      "image": null
    }
  ],
  "id": "5b964f67d98c420500a507c6",
  "session": "12345",
  "environment": "production",
  "type": "out",
  "takeover": null,
  "quickReplies": null,
  "locale": "nl-BE",
  "metadata": {
    "state": "start",
    "label": "junk",
    "sentence": "hallo",
    "tokens": [
      "smalltalk"
    ],
    "entities": [
      {
        "label": "smalltalk",
        "value": "hallo"
      }
    ],
    "context": {
      "contextVariables": null,
      "entities": [],
      "label": null,
      "dialogStack": []
    },
    "firedRules": [
      {
        "id": "5aa13e5910dacb0005283089",
        "dialog": "5aa13e5910dacb0005283088",
        "score": 20,
        "label": "any => 'None': [{'_id': ObjectId('5aa13dcd10dacb0005283081'), 'label': 'smalltalk', 'useForCorrections': None, 'id': ObjectId('5aa13dcd10dacb0005283081'), 'chatbotId': ObjectId('5aa1258c10dacb0005283005')}] [{'_id': ObjectId('5aa13de310dacb0005283082'), 'value': {'nl-BE': 'hallo', 'en': 'hello'}, 'synonyms': [{'lang': 'nl-BE', 'text': 'hey'}, {'lang': 'nl-BE', 'text': 'jo'}, {'lang': 'nl-BE', 'text': 'yu'}, {'lang': 'nl-BE', 'text': 'ju'}, {'lang': 'nl-BE', 'text': 'goeiedag'}, {'lang': 'nl-BE', 'text': 'goededag'}, {'lang': 'nl-BE', 'text': 'goeiemorgen'}, {'lang': 'nl-BE', 'text': 'goedemorgen'}, {'lang': 'nl-BE', 'text': 'goeiemiddag'}, {'lang': 'nl-BE', 'text': 'goedemiddag'}, {'lang': 'nl-BE', 'text': 'goeieavond'}, {'lang': 'nl-BE', 'text': 'goedeavond'}, {'lang': 'nl-BE', 'text': 'juw'}, {'lang': 'nl-BE', 'text': 'juuw'}, {'lang': 'nl-BE', 'text': 'hello'}, {'lang': 'nl-BE', 'text': 'hi'}, {'text': 'hi', 'lang': 'en'}, {'text': 'hi there', 'lang': 'en'}, {'text': 'good morning', 'lang': 'en'}, {'text': 'good afternoon', 'lang': 'en'}, {'text': 'good evening', 'lang': 'en'}, {'text': 'hey', 'lang': 'en'}, {'text': 'yow', 'lang': 'en'}, {'text': 'yo', 'lang': 'en'}, {'text': 'jow', 'lang': 'en'}, {'text': 'jo', 'lang': 'en'}], 'useForCorrections': True, 'id': ObjectId('5aa13de310dacb0005283082'), 'chatbotId': ObjectId('5aa1258c10dacb0005283005'), 'labelId': ObjectId('5aa13dcd10dacb0005283081')}]  => any"
      }
    ],
    "responseId": "5aa13e5910dacb0005283089",
    "dialogId": "5aa13e5910dacb0005283088",
    "times": {
      "preprocessing": 0.39,
      "labeling": 3.74,
      "context": 1.66,
      "response_time": 52.45,
      "error_time": 0
    },
    "estimates": [
      {
        "label": "delivery",
        "probability": 0.03134429808020906
      },
      {
        "label": "takeover",
        "probability": 0.030097189565634896
      },
      {
        "label": "forget",
        "probability": 0.027379667383734985
      },
      {
        "label": "joke",
        "probability": 0.0234291049512257
      },
      {
        "label": "login",
        "probability": 0.015157726679018692
      },
      {
        "label": "documents",
        "probability": 0.013203320682452972
      }
    ],
    "variables": null
  },
  "processed": "58.48 milliseconds",
  "time": 64,
  "queue": "oswald-out-df1fc523-1492-4ba0-9f30-81518bcda343",
  "chatbotId": "5aa1258c10dacb0005283005",
  "chatbotName": "Demo chatbot"
}

Hier vind je vele informatie over de gestuurde request. De belangrijkste property is data. Dit is een array van objecten. Elk object heeft een type en andere properties. Deze objecten moeten gevisualiseerd worden in de frontend. Dit kunnen tekstballonnen, afbeeldingen, url's, carousels... zijn.