Integrations are special elements that are configured to send/receive HTTP requests to/from external systems. Once enabled an integration always listens for incoming requests and any outgoing events.

An integration is configured by creating a YAML file in your app's repo that contains the integration's configuration parameters.

Here is an example of a Front integration config file:

type: meya.front.integration
api_token: (@ vault.front.api_token )
bot_teammate_email: (@ vault.front.bot_teammate_email )
channel_id: (@ vault.front.channel_id )
unassign_mode:
integration_mode: (@ vault.front.mode )
agent:
  name: first_last_initial
  avatar:
    image: https://meya-website.cdn.prismic.io/meya-website/add2c3f0-c3f8-4bd9-b04e-9ece561aa6d2_headphones-customer-support-question.svg
client_token: (@ vault.front.client_token )
filter:
  tx: >-
    (
      meya.event.entry.interactive
      OR meya.csp.event
      OR meya.button.event.click
      OR meya.form.event.submit
    )
    AND NOT meya.text.event.status

From the above config file you will notice that the integration requires a number of configuration fields such as api_token, channel_id etc., and that these fields reference the vault data scope. Meya comes with the ability for you to securely store and reference secrets that are often required by external systems to authenticate HTTP requests.

In addition to the vault data scope guide, you can also check out the Vault guide to learn how to manage secrets in the Meya Console.

🚧

Warning

Do not store your integration secrets directly in your BFML code. Always use the vault data scope to store and reference your app secrets.

Integration reference paths

An integration's reference path is simply the integration's file path where the slashes / are replaced with dots ., and the file extension is dropped.

(If you're familiar with Python, an integration reference path is similar to a Python file's module path.)

Here are some example reference paths:

• integration/whatsapp.yaml becomes: integration.whatsapp
• integration/zendesk/support.yaml becomes: integration.zendesk.support

To use the integration reference path in a component spec, you need to set the integration field of the component spec. Here is an example:

- type: meya.zendesk.support.component.user.search
  integration: integration.zendesk.support
  query:
    - email:(@ flow.result )

Reference documentation

The Meya SDK provides many different types of integrations to external systems. You can check the reference documentation which contain details about all the configuration fields:

• Integration reference documentation

Or you can check the integration guides that give step-by-step instructions for setting up integrations as well as documentation on integration specific triggers and components:

• Integration guides

Processing incoming requests (rx)

Once you have configured an integration it will start listening for any incoming requests to process and convert them to canonical events.

Here is the basic sequence of how a request if processed by an integration element:

1. The external system sends a HTTP request to your integration's webhook.
2. The Meya gateway receives the request, validates this request against your app and stores the request on your apps http_ledger.
3. The integration element that's listening to the http_ledger, receives the request (rx).
4. The integration element authenticates, validates, signature checks the request payload.
5. The integration creates/updates the Meya user and Meya thread to track the user and conversation thread. Creation only happens on the first request.
6. The integration converts the payload into a canonical event e.g. text.say or image, mapping all the required data for the canonical event.
7. The integration stores the canonical event on you app's event_ledger.
8. The integration will generate an HTTP response, and store it on the http_ledger.
9. The Meya gateway will relay the response back to the external system.
10. The app will then evaluate any active triggers to process the new canonical event.

Processing outgoing events (tx)

When a component in a BFML flow executes and generates events, these events might need to be relayed to external systems, for example, the bot's response might need to be sent to WhatsApp.

Here is the basic sequence of how an event is sent to an external system:

1. A component element generates a new canonical event e.g. text.say or image, and stores it on the app's event_ledger.
2. The integration elements will receive the new event and check if the event needs to be sent to the external system.
3. If the event needs to be sent, the integration will create a new outgoing HTTP request (tx) to the external system, and store the request to the http_ledger for logging purposes.
4. The external system will return with a response, and the integration will store the response in the http_ledger. (Check the integration specific guides for more information errors, timeouts and retries.)

Filtering requests & events

Each integration will, by default, filter relevant requests and events depending on which payloads it supports. For example, an external system might send a device status request, but this type of request is not relevant to your Meya app, and therefore can be ignored. In this case the integration will automatically filter out these requests. Each integration has its own specific implementation rules of which types of request are supported and how these are filtered.

However, there are use-cases where you would like to add additional filtering criteria to the integration. This is especially useful if you would like to filter out certain requests/events that are not applicable, and that you do not want to appear in the external system or in your app e.g. typing indicators or images.

You can specify additional filtering criteria by setting the filter field on and integration. The filter field specifies a number of filter criteria expressed using the GridQL query syntax, where GridQL allows you to apply complex boolean logic to the requests/events as they are being processed by the integration.

Here is an example:

...
filter:
  tx: >-
    (
      meya.event.entry.interactive
      OR meya.csp.event
      OR meya.button.event.click
      OR meya.form.event.submit
    )
    AND NOT meya.text.event.status

The above filter criteria will block all status events but allow interactive, csp, button click and form submit events.

Filter fields

• rx_sub: Filter any incoming HTTP/WS requests before they are processed by the integration.
• rx: Filter any resulting entries from processing the incoming HTTP/WS request before they are stored in their relevant ledgers.
• tx: Filter any outgoing event before it is processed by the integration.
• tx_pub: Filter any resulting entries from processing the outgoing event before they are stored in their relevant ledgers.