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:
- Microsoft
- Operator (Enreach / Voiceworks)
- 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
- eitheruser
orbot
, see the next section.provider
- one of the supported platforms (google
orfacebook
), in lowercase. Forbot
-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
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:
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
- 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"