API Overview

AEI Studio exposes 2 APIs to interact with your bots:

  • the WebSocket API allows users to send messages to and receive messages from a bot. It is typically used for building a chat client.
  • the Event API allows external systems to trigger events that bots will process (e.g. a bot will start speaking when receiving some kind of event). It can also be used to register a webhook that will be called for every bot message.

API Keys

In order to use those 2 APIs, you need to get an API Key. This can be done easily from AEI Studio by clicking on API Keys in the left sidebar. The API Key must be provided as a query parameter called api_key.

Example of API call:

https://api.studio.aei.dev/api/events/subscriptions?api_key=5501C4791D85F927E0A456BC06C1

Restrictions

By default, API Keys have no restrictions, which means the API will only verify that the key is valid but not where the request comes from. For production usage, it is recommended to add restrictions so that the API Key can only be used from an authorized origin (website, IP or app). This will prevent someone else from stealing your API Key.

There are 4 kinds of restrictions:

  • HTTP referrers: will ensure API Requests come from a given URL.
  • IP addresses: will ensure API requests come from a given IP address or range.
  • Android apps: will ensure API requests come from a given Android app.
  • iOS apps: will ensure API requests come from a given iOS app.

HTTP Referrers

You can use one of the following:

  • A specific URL with an exact path: www.example.com/path
  • Any URL in a single subdomain, using a wildcard asterisk (*): sub.example.com/*
  • Any subdomain or path URLs in a single domain, using wildcard asterisks (*): *.example.com/*

IP Addresses

Specify an IPv4 or a subnet using CIDR notation (e.g. 192.168.0.0/22).

Android Apps

To use this API key in an Android app, you should also provide the following HTTP headers:

  • X-Android-Package: your app package name as value, e.g. com.example
  • X-Android-Cert: the fingerprint of the certificate used to sign your app, e.g. 12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:AA:BB:CC:DD

To retrieve the debug certificate fingerprint on Linux or macOS:

$ keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

To retrieve the debug certificate fingerprint on Windows:

$ keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

To retrieve the release certificate fingerprint (replace your_keystore_name and your_alias_name):

$ keytool -list -v -keystore your_keystore_name -alias your_alias_name

iOS Apps

To use this API key in an iOS app, you should also provide the following HTTP header:

  • X-Ios-Bundle-Identifier: your app bundle ID as value, e.g. com.example.MyApp