A (chat)bot can be deployed on a messaging service. The bot can consist of multiple so called agents. An agent is a coherent entity, usually tasked to process certain queries (e.g. an agent to process smalltalk and another agent with additional functionality that provides utility like information regarding a service). Usually, a query is first sent to one agent, and then to another agent if thedetection certainty (the score) has not been high enough.

An Agent has:

1. executionIndex: signals when an agent will be asked. The higher the executionIndex, the faster the agent will be asked. Example: You have three agents with executionIndices [2,3,1]. The third agent (with the executionIndex 1) will be contacted first.
2. minScore: minimal score to mark a response from an agent as certain. If the NLP service returns a score lower than minScore, the next agent will be contacted.
3. token: authentication token of the NLP service.
4. project_id: an identifier for e.g. Google Cloud Projects. Not relevant for all platforms, take a look at the respective adapters.
5. url: url pointing to the NLP service. Especially relevant if the service does not have a fixed endpoint (e.g. when using open source services)
6. languageCode: signaling the language of your agent.

Includes all Agents relevant to your service.

A basic configuration for your chat adapter. Your own implementation of a chat adapter should implement this type, containing:

1. constructor: Implements the ChatAdapter interface.
2. name: The name of your messaging platform. Used for logging purposes.
3. url: The url of the messaging API with which you communicate.
4. webhook: The framework internal webhook path to which a messaging API sends its requests

Payload is an Attachment.

Can be used when first connecting a user with the framework (e.g. sending a ping upon loading a website for the first time). Relevant if you implement a chatAdapter for your own messaging service and have to distribute a messagingUserId. The messagingUserId can be generated by the server and sent back to the client.

ChatAdapterRequests are user messages that are transformed from a messaging specific format into a generalized format. Currently, only text messages and attachments are supported. If a message does not belong into one of these categories it counts as an undefined/invalid request, which can be handled in the first interceptor (chatToCore) if desired. If it is not handled by yourself, the framework will return an error message to the user.

Requests always include:

1. Their type: string
2. isFromAdmin: boolean: A flag that indicates whether the message is sent from another person that administers

                        the page and is NOT the user.

3. message: Some payload. Its content depends on the type of the message.

Standard text request. Payload is a string.

Requests that do not correspond to a supported ChatAdapterRequest type. The original payload is stored in the message-field. You can specify how to further handle the message in the first interceptor (chatToCore). If you do not wish to change the payload or handle the message, the interceptor can simply return a ChatAdapterUndefinedRequest, which will trigger a message to the user stating that the type of message is not supported.

An IdAttachment uses an identifier assigned to some attachment saved on the messaging platform's server. The id is used for referencing, and points to the file that shall be sent to the user. Useful if the same file is sent repeatedly.

UrlAttachments require a URL from which the data will be downloaded and sent to the user. Limitations regarding the size might apply and depend on the platform. Example: Files larger than 25MB cannot be sent using Facebook.

Possible message types that are expected during the communication with the interceptors. Each interceptor expects and returns a BotFrameworkInterfaceMessage.

Developer-defined JSON. It is processed without modifications. Make sure to convert it at the third interceptor (nlpToChat) and/or handle it there and return a NoResponse.

Images and buttons are the only attachments currently supported. Please submit an issue if you think that another type needs to be supported.

Some platforms support different types of buttons. Some commonly used button types are defined below, the different usages are documented in the respective chatAdapter.

A simple image which can be retrieved using an url. Locally stored images are currently not supported.

Quick replies are suggested replies that can be used to visualize different options a user can choose as a reply. The suggestions are often clickable and disappear after selection.

Example: https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies/)

Generic response format for messages that are queued to be sent to the user. Includes an identifier as well as the response. Each message includes its type, the payload (which depends on the type) and the (depseudonymized) messengerUserId.

Used if the user shall receive a standard text response.

From https://developers.facebook.com/docs/messenger-platform/reference/send-api/#recipient: A successful Send API request returns a JSON string containing identifiers for the message and its recipient. Note: Effective February 20, 2018, the Send API no longer includes recipient_id in the response for messages that use recipient.user_ref or recipient.phone_number to identify the message recipient.

If NoResponse is returned from an interceptor the user does not receive a visible message.

Generic response type that will be returned from our interceptors. A Response either returns a payload and additional information that can be used in the next processing steps or it returns a NoResponse.