Documentation
Now we're talking
Welcome to Botcopy! The following is to familiarize you with the Google Assistant responses that work with Botcopy. Google also offers ample documentation on Dialogflow and Google Assistant. If you find any of these instructions too hard to follow, please don't hesitate to get in touch with us.
Branding
Menus provide options to your users. It can be used to cover the main flows of your bot and get your users back on track.
Build your menu in Dialogflow. Create an intent, set one of its training phrases to "menu" and add your chosen response. When a user clicks on menu on the window, this will trigger your menu intent.
Note: You may hide the menu by toggling it off in Window and Messages withing Branding.
Changes to the chat window's colors, fonts, size, and full-screen functionality (CUI mode) can we found in the Window and Messages Advanced section within a bot's branding tab.
Select from our pre-designed color schemes or select your own colors within the greeter advanced section.
Greeter vs Avatar
The greater is the chat icon displayed before clicking into the chat window. Botcopy accepts both images and gif files for greeters.
The avatar is the icon within the chat that represents your company's response.
CUI stands for Conversational User Interface. If you would like a full-screen chat experience when the users enter a specific URL make sure this toggle is on. The ability to minimize the screen will be removed.
If you want this experience on some pages but not others add another bot, connect the same agent, toggle the CUI mode on, and insert this new HTML snippet into the web-page desired.
Google Assistant Responses:
A simple response displays as a regular text file triggered from a users intent. If you would like to add buttons to this text add a new response type 'suggestion chips'.
Suggestion chips are suggested options for your users to choose from. Add them strategically to help your customers navigate your chat more easily.
Link-out Suggestions display a button that links out to a URL.
Basic cards can be used for images, gifs, videos and files by placing the URL in the image URL field. Cards typically contain a title, text, and a button.
Videos:
Paste the video URL into the top input field where it says "Enter Image URL.". Currently, Botcopy accepts Dropbox URLs.
IMPORTANT: You must change the "www" to "dl". Please see an example of this change below.
Original URL
https://www.dropbox.com/s/49cj0a442kxig1d/FRont%20page%20ad%20%2887060D21-08F8-4195-9F09-340CA2A64C3F%29.mp4?dl=0
Botcopy accepted
https://dl.dropbox.com/s/49cj0a442kxig1d/FRont%20page%20ad%20%2887060D21-08F8-4195-9F09-340CA2A64C3F%29.mp4?dl=0
Use carousel cards to display images in a gallery format. Doesn't support video files.
Title and subtitle fields: Google has not fully released these fields from this component. Use Item title and Item description instead.
For a carousel with selections that link to web pages, a Browse carousel card is recommended. These let users click on a selection in the carousel to link out to a url in their browser. Regular Carousel cards only link to other intents within your Dialogflow agent.
Browse Carousel Cards as a Google Assistant response are under development by Dialogflow. However, it is possible to display Browse Carousel Cards through fulfillment.
Dialogflow requires you to add a simple response* and a minimum of 2 list items to Lists. Botcopy supports a List header, List item titles, List item descriptions, and images for each List item. Below is an image of what they look like within our chat.
*You can display a List by itself by toggling the ON option next to 'Use responses from the DEFAULT tab as the first responses' in your Dialogflow console.
Table cards are still under development by Dialogflow. We will update these docs when this component has been updated.
Media Content was designed mainly for audio files. However, we are working on making them work for images and video as well. Don't forget to convert the url to mp3 or mp4.
If you'd like to send just the video, image or file without simple response or suggestion chips you can use a custom payload.
Fulfillment Responses
Dialogflow Requirements:
agent.requestSource = agent.ACTIONS_ON_GOOGLE; is required to precede const conv = agent.conv(); for your response payloads.
When using the actions of google package, ensure your dependencies are up to date. "dialogflow-fulfillment" should be version ^0.6.1.
Note: When creating a new agent on Dialogflow, the package.json that is generated does not use the latest dependencies.
package.json example with updated dependencies:
{
"name": "dialogflowFirebaseFulfillment",
"description": "This is a Botcopy example for dependencies for a Dialogflow agents using Cloud Functions for Firebase",
"version": "0.0.1",
"private": true,
"license": "Apache Version 2.0",
"author": "Google Inc.",
"engines": {
"node": "6"
},
"scripts": {
"start": "firebase serve --only functions:dialogflowFirebaseFulfillment",
"deploy": "firebase deploy --only functions:dialogflowFirebaseFulfillment"
},
"dependencies": {
"actions-on-google": "^2.5.0",
"firebase-admin": "^6.4.0",
"firebase-functions": "^2.1.0",
"dialogflow": "^4.0.3",
"dialogflow-fulfillment": "^0.6.1"
}
}
For reference, here is the default fulfillment package.json generated by Dialogflow.
{
"name": "dialogflowFirebaseFulfillment",
"description": "This is the default fulfillment for a Dialogflow agents using Cloud Functions for Firebase",
"version": "0.0.1",
"private": true,
"license": "Apache Version 2.0",
"author": "Google Inc.",
"engines": {
"node": "8"
},
"scripts": {
"start": "firebase serve --only functions:dialogflowFirebaseFulfillment",
"deploy": "firebase deploy --only functions:dialogflowFirebaseFulfillment"
},
"dependencies": {
"actions-on-google": "^2.2.0",
"firebase-admin": "^5.13.1",
"firebase-functions": "^2.0.2",
"dialogflow": "^0.6.0",
"dialogflow-fulfillment": "^0.5.0"
}
}
Simple Responses are text responses from your agent. They are required by Google to precede a rich response (Suggestion Chips, Carousels, Browse Carousels etc)
function simpleResponse(agent) {
agent.requestSource = "ACTIONS_ON_GOOGLE";
let conv = agent.conv();
conv.ask('This is a simple response from fulfillment.');
agent.add(conv);
}
Suggestion Chips offer options to users.
Here is a working example for a Suggestion Chips using the actions-on-google package.
// for this example, you must require the 'actions-on-google' library
// deconstruct the Suggestions class from the library at the top of your document
const { Suggestions } = require('actions-on-google')
function suggestions(agent) {
agent.requestSource = "ACTIONS_ON_GOOGLE";
let conv = agent.conv();
conv.ask('This is a simple response from fulfillment.');
//adds a single suggestion chip
conv.ask(new Suggestions('Suggestion Chips'));
//adds multiple suggestion chips
conv.ask(new Suggestions(['suggestion 1', 'suggestion 2']));
agent.add(conv);
}
Here is a working example for a Link Out Suggestion using the actions-on-google package.
// for this example, you must require the 'actions-on-google' library
// deconstruct the LinkOutSuggestion class from the library at the top of your document
const { LinkOutSuggestion } = require('actions-on-google')
function linkOut(agent) {
agent.requestSource = agent.ACTIONS_ON_GOOGLE;
const conv = agent.conv();
conv.ask('Simple responses are required before a rich response');
conv.ask(
new LinkOutSuggestion({
name: 'Title of Link Out',
url: 'https://botcopy.com'
})
);
agent.add(conv);
}
Here is an example on adding a Basic Card in fulfillment with the actions-on-google package
// deconstruct the Basic Card and Button classes from the library at the top of your document
const { BasicCard, Button } = require('actions-on-google')
function aogBasicCard(agent) {
agent.requestSource = agent.ACTIONS_ON_GOOGLE
const conv = agent.conv()
conv.ask('Here is a basic card through fulfillment')
conv.ask(
new BasicCard({
buttons: [
new Button({ title: 'Test Button', url: 'https://botcopy.com' }),
new Button({ title: 'Test Button 2', url: 'https://botcopy.com' })
],
text: 'Test formatted text',
image: new Image({
url:
'https://cdn-images-1.medium.com/max/1200/1*s-JvYKXGEnYPdyIgT0w7gw.png',
alt: 'Bot banner'
}),
subtitle: 'Test subtitle',
title: 'Test title'
})
)
agent.add(conv)
}
Below is an example of how to add a carousel as a response in fulfillment using the actions-on-google package. We recommend using this package over the dialogflow-fulfillment package.
// for this example, you must require the 'actions-on-google' library
// deconstruct the Carousel and Image classes from the library at the top of your document
// example: const { Carousel, Image } = require('actions-on-google')
function fulfillmentCarousel(agent) {
// set your agent's requestSource to 'ACTIONS_ON_GOOGLE'
agent.requestSource = agent.ACTIONS_ON_GOOGLE;
// declare a variable conv (this can be a global variable or within an intent response function)
let conv = agent.conv();
// conv.ask your responses
// this is a simple text response
conv.ask('This is a carousel example.');
// this is a carousel response
conv.ask(
new Carousel({
// items in your carousel
items: {
// option key name - sent as a response when a user clicks on this card
SELECTION_KEY_ONE: {
synonyms: ['synonym 1', 'synonym 2', 'synonym 3'],
// title of your carousel item
title: 'Title of First Carousel Item',
// description of your item
description: 'This is a description of a carousel item.',
// an image associated with a card. note the new 'Image' class we imported
image: new Image({
url: 'IMG_URL_AOG.com',
alt: 'Image alternate text'
})
},
// second carousel item
SELECTION_KEY_GOOGLE_HOME: {
synonyms: ['Google Home Assistant', 'Assistant on the Google Home'],
title: 'Google Home',
description:
'Google Home is a voice-activated speaker powered by ' +
'the Google Assistant.',
image: new Image({
url: 'IMG_URL_GOOGLE_HOME.com',
alt: 'Google Home'
})
},
// third carousel item
SELECTION_KEY_GOOGLE_PIXEL: {
synonyms: ['Google Pixel XL', 'Pixel', 'Pixel XL'],
title: 'Google Pixel',
description: 'Pixel. Phone by Google.',
image: new Image({
url: 'IMG_URL_GOOGLE_PIXEL.com',
alt: 'Google Pixel'
})
}
}
})
);
// add your conv variable to your agent
// this sends all your responses to your botcopy widget
agent.add(conv);
}
Below is an example of how to add a carousel as a response in fulfillment using the dialogflow-fulfillment package.
// for this example, you must require the 'dialogflow-fulfillment' library
// deconstruct the Payload class from the library at the top of your document
// example: const { Payload } = require('dialogflow-fulfillment')
function fulfillmentPayload(agent) {
// set your agent's requestSource to 'ACTIONS_ON_GOOGLE'
agent.requestSource = 'ACTIONS_ON_GOOGLE';
// use agent.add and the new Payload class to send a raw JSON Carousel to botcopy
agent.add(
new Payload(agent.ACTIONS_ON_GOOGLE, {
expectUserResponse: true,
richResponse: {
items: [
{
simpleResponse: {
textToSpeech: 'Choose a item'
}
}
]
},
systemIntent: {
intent: 'actions.intent.OPTION',
data: {
'@type': 'type.googleapis.com/google.actions.v2.OptionValueSpec',
carouselSelect: {
items: [
{
optionInfo: {
key: 'first title'
},
description: 'first description',
image: {
url:
'https://developers.google.com/actions/images/badges/XPM_BADGING_GoogleAssistant_VER.png',
accessibilityText: 'first alt'
},
title: 'first title'
},
{
optionInfo: {
key: 'second'
},
description: 'second description',
image: {
url:
'https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw',
accessibilityText: 'second alt'
},
title: 'second title'
}
]
}
}
}
})
);
}
Here is an example on adding a Browse Carousel Card in fulfillment with the actions-on-google package
// deconstruct the BrowseCarousel, BrowseCarouselItem and Image classes from the library at the top of your document
const { BrowseCarousel, BrowseCarouselItem, Image } = require('actions-on-google')
function browseCarousel(agent) {
agent.requestSource = "ACTIONS_ON_GOOGLE";
let conv = agent.conv();
conv.ask('This is a browse carousel example from fulfillment.');
// Create a browse carousel
conv.ask(new BrowseCarousel({
items: [
new BrowseCarouselItem({
title: 'Title of item 1',
url: 'https://botcopy.com',
description: 'Description of item 1',
image: new Image({
url: 'https://www.botcopy.com/wp-content/uploads/2019/01/Screen-Shot-2019-01-27-at-3.37.28-PM.png',
alt: 'Image alternate text',
}),
footer: 'Item 1 footer', //Supported in next update
}),
new BrowseCarouselItem({
title: 'Title of Item 2',
url: 'https://botcopy.com',
description: 'Description of Item 2',
image: new Image({
url: 'https://www.botcopy.com/wp-content/uploads/2019/01/Screen-Shot-2019-01-25-at-10.31.54-AM.png',
alt: 'Image alternate text',
}),
footer: 'Item 2 footer',
}),
],
}));
agent.add(conv);
}
Below is an example of how to add a List in fulfillment using the actions-on-google package.
// this example uses the List class from 'actions-on-google'
// the structure of a list is similar to a carousel
// you'll need to deconstruct the List and Image classes from the actions-on-google package
const { List, Image } = require('actions-on-google')
function list(agent) {
// set your agent's requestSource to 'ACTIONS_ON_GOOGLE'
agent.requestSource = agent.ACTIONS_ON_GOOGLE;
// declare a variable conv (this can be a global variable or within an intent response function)
let conv = agent.conv();
// conv.ask your responses
// this is a simple text response
conv.ask('This is a list example.');
// this is a list response
conv.ask(
new List({
// one main difference between a list and a carousel is the title
// this title is optional. if you choose to include one, it will be rendered as a header over the list
title: 'List Title',
items: {
// the fields within a list mirror those in a carousel
SELECTION_KEY_ONE: {
synonyms: ['synonym 1', 'synonym 2', 'synonym 3'],
title: 'Title of First List Item',
description: 'This is a description of a list item.',
// note the image field uses the Image class like carousels
image: new Image({
url: 'IMG_URL_AOG.com',
alt: 'Image alternate text'
})
},
// Add the second item to the list
SELECTION_KEY_GOOGLE_HOME: {
synonyms: ['Google Home Assistant', 'Assistant on the Google Home'],
title: 'Google Home',
description:
'Google Home is a voice-activated speaker powered by ' +
'the Google Assistant.',
image: new Image({
url: 'IMG_URL_GOOGLE_HOME.com',
alt: 'Google Home'
})
},
// Add the third item to the list
SELECTION_KEY_GOOGLE_PIXEL: {
synonyms: ['Google Pixel XL', 'Pixel', 'Pixel XL'],
title: 'Google Pixel',
description: 'Pixel. Phone by Google.',
image: new Image({
url: 'IMG_URL_GOOGLE_PIXEL.com',
alt: 'Google Pixel'
})
}
}
})
);
// add your conv variable to your agent
// this sends all your responses to your botcopy widget
agent.add(conv);
}
Language Settings
Botcopy’s widget supports multilingual agents based on the preferred language in each of your end users' browser. To enable localization in Dialogflow, find the “Languages” tab in your agent's settings and add the languages you desire from the ones Google currently makes available. Once the alternate intents, entities, training phrases and fulfillment responses are built out in your Dialogflow agent, the language on your widget will display the appropriate language. See video for details:
Portal
- Copy the generated embed snippet from the configure page on your portal.
- Paste the embed snippet into your <head> or <body> tags
- Your branded widget will appear in the bottom right of your website
Botcopy has a built in integration with Chatbase and Dashbot. Just provide us your API key to link your account.
Chatbase
Dashbot
Please note the platform must be set to Webchat
Tag Manager
If you use the google tag manager, you'll need to tick the box for write access underneath the HTML field. Additionally, you may need to remove the defer="true" if write access isn't enough.
Bot prompts enable you to make your website conversational by setting triggers with Botcopy and building your prompts using Dialogflow. Simply set a trigger (unique training phrase or event) and a page url to add a bot prompt to a particular page. Additional triggers coming soon!
*Make sure to remove https:// from the url input
To pass data from URLs, you can use our ref parameter detection feature. The Botcopy widget will detect the value from your ref key and set a context on your agent.
Typical use cases:
- Linking marketing campaign to specific users
- Referencing specific products
- Displaying relevant prompt based on user
Example Flow:
- User receives email
- User clicks email with link www.botcopy.com?ref=customer1
- Widget detects ref=customer1
- Assigns customer1 as a parameter to context 'botcopy-ref-context' (the name will always be botcopy-ref-context and has a lifespan of 2)
In the example below we setup a google sheet api using SheetLabs.
Example function using actions-on-google package:
function refTestConv(agent) {
const contextName = 'botcopy-ref-context'; // 'botcopy-ref-context' is the context we assign the value from your ref key
agent.requestSource = 'ACTIONS_ON_GOOGLE';
const conv = agent.conv();
conv.ask('Testing the Conv ref');
const botcopyRefContext = agent.context.get(contextName);
console.log('botcopy-ref-context', botcopyRefContext);
if (!botcopyRefContext || !botcopyRefContext.parameters || !botcopyRefContext.parameters.botcopyRefValue) {
conv.ask('botcopyRefContext.parameters.botcopyRefValue is empty!');
return; // If the ref is undefined show a different response
}
const { parameters: { botcopyRef, botcopyRefValue } } = botcopyRefContext;
// Optional to peel off a part of the value
const botcopyRefValueCleaned = botcopyRefValue.replace('customer', '');
conv.ask(`sent ref was: ${botcopyRefValue} and cleaned: ${botcopyRefValueCleaned}`);
return pullFromSheetlabs(botcopyRefValueCleaned)
.then((parameters) => {
// once we have pulled the information, set a new context
// new userContext has information pulled from db
conv.contexts.set('userContext', 100, parameters);
const userContext = conv.contexts.output.userContext;
console.log('userContext', userContext);
if (!userContext) {
throw new Error('userContext not found');
}
const { parameters: { firstName, lastName, email } } = userContext;
console.log('firstlastemail', firstName, lastName, email);
conv.ask(`Hi, ${firstName} ${lastName}, is ${email} still your current email address?`);
})
.catch((e) => {
conv.ask(`could not load data from sheets! error: ${e.message}`);
})
.then(() => {
// end conversation and send to user
agent.add(conv);
});
}
//Function referencing context parameters and pulling data from sheet to display
function pullFromSheetlabs(id) {
// pull data from salesforce / crm / database with ref variable
// we used sheetlabs to create a google sheet api
// the following refs correlate with records in the sheet
// 5024 - Matthew Porter matt@matt.com
// 7482 - Alex Seegers alex@alex.com
// 1337 - Phil Holly phil@phil.com
const url = `https://sheetlabs.com/SUNS/reftest?ref=${id}`;
// const url = `https://sheetlabs.com/SUNS/reftest?ref=5024`;
return axios.get(url).then((res) => {
console.log('res.data', res.data);
const parameters = {};
parameters.firstName = res.data[0].firstName;
parameters.lastName = res.data[0].lastName;
parameters.email = res.data[0].email;
console.log('parameters post axios', parameters);
return parameters;
}).catch((e) => {
console.log('axios error', e);
throw e;
});
}