Botsquad documentation logo

Using API integrations, you can connect your bot to external services, to perform API calls. 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 currently supported platforms are the following:

Please contact us if you need access to other platforms.

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
  context: user
-
  provider: facebook
  context: user

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

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.

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.

Token helper functions

In the DSL 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 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:

get_access_token(token_id)

Return the plain access token for the given token identifer. 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.