API integrations & secrets storage

Integrations come in two forms, OAuth-based integrations and static integrations.

OAuth-based integrations¶

Using OAuth-based integrations, you can create OAuth tokens for your bot to connect to external services like Google cloud. The bot can have a fixed set of tokens, but you can also use the integrations framework to let the bot ask the user to log in, for instance, when you write a bot that wants access to somebody's Google calendar.

The following OAuth providers are currently supported:

Google
Facebook
Linkedin
Microsoft
Operator (Enreach / Voiceworks)
Salesforce
Generic OAuth2

Please contact us if you need access to other OAuth providers.

Studio-specific integrations¶

Some API integrations are fixed connections to providers that require some kind of one-time credential configuration, in order to provide extra functionality in the DialoX studio or runtime. The following providers are currently built in:

Dialogflow, for connecting a custom Dialogflow Agent to your bot
Mailgun, for customizing the sender and domain of the mail() Bubblescript function
Twilio, for enabling the sms_notify() Bubblescript function
Pushwoosh, for enabling in-app push notifications

Setting up integrations¶

By defining an integrations YAML file in your bot, you specify which connections to other services can be made.

These connections always have a context: The bot context integrations are authenticated once, while you are building the bot, and are available to all users. The user integrations are authenticated on demand; e.g. the bot can ask the user to log in with Google to let the bot manage the user's calendars.

- provider: google
  alias: google
  scope: email profile
  context: user
- provider: facebook
  context: user
  scope: email,user_friends
  alias: facebook
- provider: linkedin
  context: user
  scope: r_liteprofile,r_emailaddress
  alias: linkedin
  description: Retrieve contact information
- provider: twilio
  context: bot
  description: Allow bot to send SMS notifications

This YAML list each contains a single entry which defines an integration to an external API.

context - either user or bot, see the next section.
provider - one of the supported platforms (google, facebook or salesforce), in lowercase. For bot-level providers, secret can be specified to indicate this is a user-editable secret, not connected to an OAuth flow.
alias - optionally a name which is used to distinguish the resulting token (in the case when you need multiple tokens to the same provider). Defaults to the provider name.
scope - the platform-specific scope string which is used to determine which permissions will be requested in the OAuth flow. Note - Facebook scopes are separated by a comma, Google scopes by spaces. Twitter does not use oauth scopes.
description - a descriptive string that is displayed in the studio user interface

The integrations file can also be part of a skill. All integrations for all skills are gathered and used collectively.

Bot-level integrations¶

All the integrations that have bot context will show up on the "connect" page of the studio. From there on, you can create connections to the requested APIs as a one-time configuration action.

Once the integrations are set up, the tokens are securely stored and in accessible from Bubblescript under the bot.tokens variable, by their alias, e.g. bot.tokens.google.

Bot-level integrations can be found under Settings → Integrations in the Studio.

Special bot-level integrations¶

A few providers are preconfigured to integrate with some aspects of the studio. These are the following:

Dialogflow¶

Allows bot users to use their own Dialogflow agent for intent resolution and intent management.

- provider: dialogflow
  context: bot
  description: Integrate with Google Dialogflow

Twilio¶

Enable the sms() Bubblescript function to send SMS notifications.

- provider: twilio
  context: bot
  description: Integrate with Twilio

Mailgun¶

Configure mailgun to use your own sender domain for the mail() Bubblescript function, and for using a custom sender domain for the e-mail channel, instead of the default of msg.botsquad.com.

- provider: mailgun
  context: bot
  description: Integrate with Mailgun

Pushwoosh¶

Allows the developer to set up push notifications through Pushwoosh for web or native app-based chats

- provider: pushwoosh
  context: bot
  description: Integrate with Pushwoosh

360 dialog¶

Enables the whatsapp() function to send template messages using the given 360dialog API key

- provider: dialog
  context: bot
  description: Integrate with 360 Dialog

Masvoz SMS API¶

Enables the sms() function to send SMS messages through the [Masvoz API][masvoz_sms] instead of through the default Twilio provider.

- provider: masvoz_sms
  context: bot
  description: Integrate with Masvoz SMS API

Google Service Account¶

It is possible to create an google_service_account token provider. This allows you to upload a Google service account JSON file in the integration. The get_access_token(token_id) function consequently fetches an access token from the Google API for the given service account and scope.

- provider: google_service_account
  context: bot
  alias: bigquery
  description: Integrate with Google BigQuery API
  scope: https://www.googleapis.com/auth/bigquery

The scope parameter is required for this API to work. See list of Google OAuth scopes.

Calendar¶

Calendar integrations allow the bot to plan appointments and perform various operations on calendars.

- provider: calendar
  context: bot
  icon: calendar
  title: Booking
  alias: booking

This will create a new constant (@booking) that can be passed as the calendar argument to the various calendaring functions.

To also enable the studio interface to create slots with, create another YAML DDL file. Make sure calendar_name and alias match.

type: calendar
title: Booking
storage:
  type: calendar
  calendar_name: booking

Salesforce¶

Provides the capability to autorefresh the SalesForce connection.

- context: bot
  alias: salesforce
  provider: salesforce
  icon: lightning
  title: "Salesforce"
  description: "Integration with Salesforce"
  oauth2:
    flow: client_credentials
    client_id: xxx"
    client_secret: "yyy"
    token_url: https://your-subdomain.my.salesforce.com/services/oauth2/token

OAuth2 integrations¶

To enable any oauth2 provider you can use the oauth2 provider in the integrations yaml:

- context: bot
  alias: discord1
  provider: oauth2
  icon: lightning
  title: "Discord"
  description: "An example integration"
  scope: "identify"
  oauth2:
    flow: auth_code
    client_id: "xxx"
    client_secret: "yyy"
    authorize_url: https://discord.com/oauth2/authorize
    token_url: https://discord.com/api/oauth2/token

Two different types of OAuth2 flows are supported, auth_code and client_credentials. Check with your specific provider on which one to use.

The OAuth2 client ID and client secret are normally obtained by creating an OAuth app on the provider side. On that page it is usually also required to specify a callback url back to the platform. Use https://studio.dialox.ai/auth/oauth2/callback when asked for the callback URL.

Storing arbitrary secrets¶

You can present a user interface for storing arbitrary information in the bot's secret store by specifying provider: secret as an entry in the integrations file:

- provider: secret
  alias: myapi_key
  context: bot
  description: API key for myapi.com

Once you have done this, navigate to Settings -> Integrations -> Secrets to find a form where you can enter a value for the secret:

ui_secret

Later on, you can use the get_access_token function to retrieve this information in Bubblescript:

dialog main do
  token = get_access_token(bot.tokens.myapi_key)
  say "Your token is: " + token
end

User-level integrations¶

For all the integrations with the user context, you should use the bot to let the user authenticate itself at the requested service. The following snippet shows 2 login buttons, one for Facebook and one for Google.

buttons "You need to login to continue" do
"Login with Google" ->
  open "#{oauth_link("google")}"
"Login with Facebook" ->
  open "#{oauth_link("facebook")}"
end

As soon as the user has completed the flow, a token: event is triggered in the bot:

dialog event: "token:google" do
  say "Thank you for logging in."
  info = get_token_info(event.payload)
  user.first_name = info.first_name
  user.profile_picture = info.image
  remember user
end

In the above example, information from the token is extracted and stored in the CRM, so the bot knows the user's name from then on.

The user's tokens are stored under the user.tokens key; for instance, user.tokens.google contains the identifier which links to the Google OAuth token. Use this identifier in the token helper functions to retrieve information about the token.

Bubblescript helper functions¶

In Bubblescript there are a few special functions that deal with the token OAuth flows. These are the following:

`oauth_link(alias)`¶

This function generates a link for the requested user-level integration, which starts the OAuth authorization flow.

The one required argument is the name of the provider or alias of which integration to start:

say oauth_link("google")

Note that you need to have an integrations YAML file set up with the corresponding provider configured. The scope (the set of requested permissions) also is defined inside the YAML file.

`get_token_info(token_id)`¶

Return some basic information about the user that is connected to the specific token:

log get_token_info(user.tokens.google)

The parameters that are inside the returned value are:

name
first_name
last_name
nickname
email
location
description
phone
urls

`get_access_token(token_id)`¶

Return the plain access token for the given token identifier. This access token is used in HTTP calls to perform requests to the integrated service.

The following example uses the access token to post a status update on Facebook:

message = ask "Please enter your status update"
token = get_access_token(user.tokens.facebook)
http_post "https://graph.facebook.com/v2.11/me/feed?access_token=" + url_encode(token), form: [message: message]
if http.status_code == 200 do
  say "Post created!"
else
  say "Something went wrong, check your logs."
end

Note that you need scope: email,publish_actions in the Facebook integrations config.

When the access token is expired, the following will happen: when a refresh token was given (e.g. in the case of Google), the access token is automatically refreshed and stored. In other cases, nil is returned. it is good practice to always check the return value of get_access_token to see whether it is valid.

`get_full_token(token_id)`¶

Retrieves the full token information structure, mainly for inspection purposes. The underlying data structure is an %Ueberauth.Auth{} struct. See the Überauth docs for more info.

say "Logging the token…"
log get_full_token(user.tokens.facebook)

`delete_token(token_id)`¶

Removes the given user or bot token, to be used for instance when implementing a "log out" flow. Returns true when the token was deleted, false when the token was not found or a valid ID was passed in.

provider: twilio context: bot description: "Configure SMS notifications"