Event API

The Events API allows developers and 3rd parties to interact with their bots by publishing and subscribing to events.

Publishing Events

Send events to our chatbot system by sending a POST request to the following URL:

The supported topics are ExternalTrigger and ReloadSession.

ExternalTrigger

This topic will trigger one of the triggers defined in AEI Studio. The body of the request should be as follows:

{
  "userId": "abcdef",
  "botId": 1,
  "triggerId": "qwerty"
}
  • userId is the ID of the user targeted by the trigger.
  • botId is the ID of the bot targeted by the trigger. It is optional: if not provided, the system will find among the user’s bots one that supports this kind of trigger.
  • triggerId is the ID of the trigger. It can be obtained from AEI Studio.

The bot will process the trigger and execute any subsequent actions according to the stories (e.g. send a message to an open WebSocket, call some webhook, send a push notification, etc).

ReloadSession

This topic will reload the given session, using the latest model. This is useful if you just published a skill and want to force a session that is in progress to use the new model. The body of the request should be as follows:

{
  "userId": "abcdef",
  "botId": 1
}
  • userId is the ID of the user targeted by the trigger. If null, it will reload the session for all users.
  • botId is the ID of the bot targeted by the trigger.

Subscribing to Events

Subscribe to events by registering a webhook that will be called whenever the event happens.

To subscribe to an event, send a POST request to the following URL:

with the following body:

{
  "topic": "BotMessage",
  "userId": "abcdef",
  "botId": 1,
  "webhook": {
    "method": "POST",
    "url": "https://maker.ifttt.com/trigger/call_nurse/with/key/abcdef",
    "queryParams": {},
    "body": "{\n\"value1\": \"some value\",\n\"value2\": \"\",\n\"value3\": \"\"\n}"
  },
  "sendEventAsBody": false
}
  • topic is the type of messages you want to listen too.

    • BotMessage will listen to any message sent by the bot.
  • userId is the ID of the user targeted by the trigger. It is optional. If not provided, the webhook will be called for all users.

  • botId is the ID of the bot targeted by the trigger. It is optional. If not provided, the webhook will be called for all bots.

  • webhook defines the request to be called by AEI Studio when an event happens.

    • method can be GET, POST, PUT or DELETE,
    • url should be a valid URL,
    • queryParams is a JSON object with a list of key/values that will be passed back as query parameters,
    • body is a string, written in JSON format, that will be passed as the body of the request.

    To get the list of subscriptions, send a GET request to the following URL:

    To delete a subscription, send a DELETE request to the following URL:

    • id is the ID of the subscription to delete. It is returned as a result from the /subscribe endpoint.
  • sendEventAsBody can be used to receive our own body instead of the one defined in the webhook. This body will be a JSON object containing the user ID, the bot ID and the bot message. This flag is false by default.