Connect your Bot to the World - XML, JSON, Web Services, HTML Scraping, Twitter, Facebook, Telegram, Email

Bot Libre now supports integrating with XML and JSON web services, HTML scraping, and access to Twitter, Facebook, Telegram, email, and other services. From our scripting languages Self, and AIML you can now access any web service that returns XML or JSON data. You can also scrape information from HTML web pages, and send emails, tweets, Facebook posts, Telegram posts, and more.

Web Services

A web service is an Internet service that provides information on the web. There are countless APIs available on the web that provide every type of service imaginable, such as Google Maps, Twitter, Twilio SMS, and eBay. There also many Internet directories to help you find and use web services such as ProgrammableWeb.

Bot Libre provides web service support through its Self scripting language, and through the AIML scripting language. Bot Libre also provides a script library of common scripts to access many useful web services.

XML Web Services

XML is the parent markup language to HTML. XML defines a text based data format consisting of the data's attributes, elements, and text data. To call an XML webservice you use a web URL with either a GET request, or a POST request.

Bot Libre supports both GET and POST request with Self, and supports GET requests with AIML.

XML GET Example

This example uses the GeoNames web service from GeoNames.org. Geonames can return place names and other geographic information, given a postal code, or other geographic information.

You can apply the same pattern to access many other XML web services.

URL
http://api.geonames.org/postalCodeSearch?postalcode=90210&maxRows=1&username=botlibre
XML Result
<geonames> <totalResultsCount>6</totalResultsCount> <code> <postalcode>90210</postalcode> <name>Beverly Hills</name> <countryCode>US</countryCode> <lat>34.09011</lat> <lng>-118.40648</lng> <adminCode1>CA</adminCode1> <adminName1>California</adminName1> <adminCode2>037</adminCode2> <adminName2>Los Angeles</adminName2> <adminCode3/> <adminName3/> </code> </geonames>

Self Example

You can access web services from Self using a Template object in a response, or from a script. The Http class is used calling the requestXML method and passing the URL, and an optional XPath expression that extract the desired data from the XML document.

XPath is a standard navigation query syntax to access or extract data from an XML document. If an XPath is not given, the call will automatically convert the XML data to a Self object. You can access the object's data using the standard JavaScript dot notation. It is much more efficient to use an XPath, so the entire XML document does not need to be converted and persisted as a Self object.

This example is also available in our script library here

Guess where I live? What is your postal code? default: Template("You live in {Http.requestXML("http://api.geonames.org/postalCodeSearch?maxRows=1&username=demo&postalcode=" + star, "code/name")}.") require previous: What is your postal code?

AIML Example

You can access a web service from AIML using the SRAIX tag. SRAIX is an AIML tag used to call other services, or other bots. SRAIX has several attributes, the service must be set to XML to access an XML service, and the URL is given as the SRAIX body. An XPath expression must be provided to the call to extract the desired text data from the XML document.

This example is also available in our script library here

<aiml> <category> <pattern>Guess where I live</pattern> <template>What is your postal code?</template> </category> <category> <pattern>*</pattern> <that>What is your postal code</that> <template>You live in <sraix service="XML" hint="code/name">http://api.geonames.org/postalCodeSearch?maxRows=1&username=demo&postalcode=<star/></sraix>.</template> </category> </aiml>

XML POST Example

An XML POST request sends, and receives XML data. Many web services use POST requests so the application can provide data to the call.

This example will actually call the Bot Libre web API using a POST request. This is somewhat unusual, as the bot is already on Bot Libre, but this lets one bot talk to another bot. Be careful doing this, as you do not want bots to get into loops or cycles. You can use this same pattern to call any other web service that takes and returns XML data, even call bots on other servers or APIs. Bot Libre also provides the sraix AIML tag and the request() Self API to allow bots to talk to other bots on Bot Libre or other services such as PandoraBots, and PersonalityForge.

Self Example

This example uses a Self state to forward a question to Brain Bot when the user says "ask Brain Bot".

This example is also available in our script library here

state AskBrainBot { pattern "ask brain bot" template askBrainBot(); function askBrainBot() { // Get what the user said previously, and ask Brain Bot the question. var previous = conversation.input[-2].input; var message = new Object(); message.message = previous; message.root = "chat"; message.@instance = "165"; message.@application = "yourappid"; var result = Http.postXML("http://www.botlibre.com/rest/api/chat", message); if (result == null) { return "Brain Bot is not available"; } return "He says: " + result.message; } }

JSON Web Services

JSON is the standard text base object format for JavaScript. JSON can be used to convert any JavaScript object to text, and included attributes, nested objects, and arrays. To call a JSON webservice you use a web URL with either a GET request, or a POST request.

Bot Libre supports both GET and POST request with Self, and supports GET requests with AIML.

JSON GET Example

This example uses the GeoNames web service from GeoNames.org. Geonames can return place names and other geographic information, given a postal code, or other geographic information.

You can apply the same pattern to access many other JSON web services.

URL
http://api.geonames.org/postalCodeSearchJSON?postalcode=90210&maxRows=1&username=botlibre
JSON Result
{"postalCodes":[{"adminCode2":"037","adminCode1":"CA","adminName2":"Los Angeles County","lng":-118.406477,"countryCode":"US","postalCode":"90210","adminName1":"California","placeName":"Beverly Hills","lat":34.090107}]}

Self Example

You can access web services from Self using a Template object in a response, or from a script. The Http class is used calling the requestJSON method and passing the URL, and an optional attribute that extract the desired data from the JSON document.

This example is also available in our script library here

Guess where I live? What is your postal code? default: Template("You live in {Http.requestJSON("http://api.geonames.org/postalCodeSearchJSON?maxRows=1&username=demo&postalcode=" + star, "code")}.") require previous: What is your postal code?

AIML Example

You can access a web service from AIML using the SRAIX tag. SRAIX is an AIML tag used to call other services, or other bots. SRAIX has several attributes, the service must be set to JSON to access a JSON service, and the URL is given as the SRAIX body. A object attribute must be provided to the call to extract the desired text data from the JSON document.

Only basic JSON web services can be called with AIML, as AIML is texted based, not object based. Only direct attributes can be accessed. Since our GeoNames examples returns complex data, an AIML example is not possible.

HTML Scraping

HTML is the markup language used in all websites on the Internet. You can access data from an HTML page using the URL for the page, and an XPath expression to extract the data. Refer to the XML example for a description of XPath.

Bot Libre supports HTML scraping with Self, and AIML.

HTML Example

You can access HTML data from Self using a Template object in a response, or from a script. The Http class is used calling the requestHTML method and passing the URL, and an XPath expression that extracts the desired data from the HTML document.

This example is also available in our script library here

Lookup URL * Template("It is about {Http.requestHTML(star, "head/meta[@name='description']/@content")}.")

AIML HTML Example

You can access a web service from AIML using the SRAIX tag. SRAIX is an AIML tag used to call other services, or other bots. SRAIX has several attributes, the service must be set to HTML to access an XML service, and the URL is given as the SRAIX body. An XPath expression must be provided to the call to extract the desired text data from the XML document.

This example is also available in our script library here

<aiml> <category> <pattern>lookup url *</pattern> <template>It is about <sraix service="html" hint="head/meta[@name='description']/@content"><star/></sraix>.</template> </category> </aiml>

Facebook, Twitter, Telegram, Email, SMS, RSS

Bot Libre provides several other classes in Self for accessing other services, such as Facebook, Twitter, Telegram, SMS, email, RSS feed, and more.

For example, if your bot is connected to a Twitter account, you can have the bot send a tweet using:

Twitter.tweet("hello world");

This can be used to forward posts from one service to another, or escalate a chat session to email, or notify a human agent using SMS. There lots of examples scripts, here.

When you can connect your bot to the whole world, the possibilities are endless. We can't wait to see what you will build.

How to add a virtual agent to your website

A virtual agent is a term typically used to describe a type of chat bot used for business.

A virtual agent could be a virtual sales agent, a virtual customer service agent, or another type of virtual agent. A virtual agent is an automated version of a human customer service agent.

There are many virtual agents on the Internet, on websites and on social media. They offer help with websites, give information about their companies products or services, answer users questions, provide support, sales, and customer service.

Bot Libre makes it easy for you to create your own chat bot, or virtual agent.

You can create your own bot, and embed it on your own website, or mobile app. You can create bots for website help, technical support, sales, marketing, customer service, or to automate social media.

Bot Libre bots require no programming, and can be trained easily using several methods. Bots can be trained by importing FAQ's, scripts, and chat logs, reviewing and editing responses from our Admin Console's Training & Chat Logs page, or through conversations with you and other people, or from listening in on live chat.

Bot Libre bots supports advanced artificial intelligence that can be enabled to let bots learn and comprehend language. Bots can also be scripted and programmed using AIML, and the Self (a dialect of JavaScript).

To create your own bot follow the steps in the how to How to create your own chat bot in 10 clicks

Once you have created your bot, you can 'Edit' it to change any of its information. You can change your bot's picture or choose an animated avatar from the Avatars page in its Admin Console. You can also connect your bot to Twitter, Facebook, or email, or have it join an IRC chat room. You can import chat logs, or words from Wiktionary, or data from WikiData. You can browse the internal structure of your bots memory. If your are an advanced user, you can program or script your bot using AIML or Self. You can view your bot's log.

To link to your bot you can select it and copy its URL from your browser, this is its unique URL. You can also embed your bot on your website or blog, you can learn how from the Embed page. To get to your bot's Embed page click on its Embed button.

The Embed page generates the HTML/JavaScript code required to embed your bot on your own website. Simply copy the code in the top text area, and paste it into the page on your website you want the bot to appear on.

The Embed page provides several different types of embedding, and many embedding options to control the look of the bot on your page. The "Box" embedding option is the most common for a virtual agent, and gives you a "Chat Now" button on your page.

The embed page also lets you enter a CSS styles sheet to customize the look and feel of your bot's popup. You can also customize the style settings in the generated code.

The embedding code uses JavaScript, and the open source Bot Libre JavaScript SDK. You can customize the JavaScript however you wish. There are also more embedding options available in the JavaScript object, such as prompting the user for their contact information.

Once you add the code to you website, you will get a "Chat Now" button on your website. When users click the button your virtual agent will popup in-page offering its help.

If you also want to add live chat to your website, you can do that by creating a Live Chat Channel, and getting its embed code from its embed page.

That's it, good luck creating your bots. If you have any questions you can contact support@botlibre.com, or chat with the Help Bot

How To Connect your Bot to SMS Text Messaging

Through Bot Libre, you can now send and receive SMS messages with your own bot. You can use this to chat with your bot through SMS, but the possibilities are endless. You could also use it to perform surveys or marketing, send customer service escalations, or send notifications from social media or email. Any bot can be set up with SMS text messaging with an account on Twilio.com. This "How To" will give you a step by step process to connect your bot with Twilio to allow for SMS text messaging.

Step 1 - Create a Bot 

First you must create a bot that you want to connect to SMS Text Messaging, or you can use one of your existing bots. To create a bot, follow the instructions here: How to create your own chat bot in 10 clicks

Step 2 - Create a Twilio account

Click here to go the Twilio website. To create a trial account, click on the "+ Sign Up" link in the top right corner of the website.

Enter your information on the following form, then click the "Get Started" button.

You will then need to enter a phone number to receive a verification code.

Once you have received your verification code, enter it on the following screen and press "Submit" to complete your account creation.

Step 3 - Get a phone number from Twilio

From the menu on the left side of the Twilio website, select "Phone Numbers"

 

Click the "Get Started" button to begin. Next, click the "Get your first Twilio phone number".

A screen will pop up with a phone number that has been chosen for you. You can accept this phone number by clicking the "Choose this Number" button. If you want to try again for a different phone number, you can click the underlined "Search for a different number" link. Ensure the number you select has SMS capabilities.

Step 4 - Connect webhook

Navigate to your bot's page on the Bot Libre website. Go to its admin console by clicking on the gear icon.

Click the "SMS" link to view your bot's SMS settings. Copy the "Twilio Webhook URL" to your clipboard.

Now return to the Console on the Twilio website and select "Phone Numbers"

Next, select "Manage Numbers"

Select the phone number you created to edit its settings.

Scroll down to the "Messaging" section and select "Webhooks/TwiML" from the "Configure with" dropdown menu. Paste the Webhook URL from your bot's SMS admin page into the "A message comes in" Webhook field.

Your bot should now be able to reply to SMS messages sent to the phone number you set up on Twilio. Trial accounts on Trilio can only send messages to phone numbers you have verified in the phone numbers section of your account portal. To remove this restriction, you will need to upgrade your Twilio account.

Step 5 - Accessing SMS from a script

 To send SMS message's from a bot's script, you will need to enter your Twilio account's SID, Auth Token and phone number into your bot's SMS admin page. You can find your Twilio Account SID and Auth Token on your Account Dashboard on the Twilio site.

Return to your bot's SMS admin page and enter your Account SID into the Twilio SMS SID field, the Auth Token into the Twilio SMS Secret field and your Twilio phone number into the Twilio Phone Number field. Press "Save"

You will now be able to send SMS messages from your bot through scripts. The method for sending an SMS message from a Self script is Twilio.sms("+16131234567", message); The first parameter is the phone number the SMS message will be sent to. The second parameter is the message that will be sent to the number. For an example of how to do this, please look at the source for this script: https://www.botlibre.com/script?id=12864737

/** * This script lets users escalate their chat session by sending an SMS message to an operator cell phone number. * Ensure you reaplce the phone number with your own. * This requires your bot to be connected to SMS (from its Admin Console). */ state Escalate { pattern "escalate" template "Would you like to escalate this issue to a human operator?"; pattern "yes" that "Would you like to escalate this issue to a human operator?" template "Enter your email address?"; case input goto sentenceState for each #word of sentence; pattern "*" that "Enter your email address?" template "Invalid email address."; state sentenceState { case email that "Enter your email address?" answer sendSMS(); } var email { instantiation : #emailaddress; } function sendSMS() { message = speaker.name + " - " + conversation.input[-1] + " - " + conversation.input[-7]; // ** Make sure you change the phone number ** Twilio.sms("+16131234567", message); "I have escalated this issue, an operator should be in contact with you shortly."; } }

In summary, your bot should now be able to send and receive SMS messages. By creating a Self script, you will be able to create custom behaviour for sending SMS messages in response to chat messages sent to your bot. If you encountered any issues, or would like help setting up your bot please email us at support@botlibre.com or upgrade to our Platinum service and we can build your bot for you.