CSML Studio also offers a way to preprocess every incoming event of certain types, in order to add some metadata or transform it. Here are some use cases:

• transcribe audio inputs

• translate incoming text

• save uploaded files to a dedicated file storage

• perform OCR on each uploaded image

• run a custom natural language processing library on text inputs (for that use case, you may also want to look at Natural Language Processing)

Preprocessors are simply external apps that are run on every incoming event (of the given type) and return a valid CSML event. The only specificity is that the parameters it must accept and return are standard CSML event payloads. Preprocessors that fail to accept or return such payloads are simply ignored and your incoming event will not be transformed.

How to add a CSML preprocessor

Let's create a simple Text preprocessor that will return a picture of a hot dog if the user had the word "hot dog" in their input, or change the text to "Not hot dog" otherwise.

To add a preprocessor, you first need to add a preprocessor-compatible app under the apps section (see here). For this tutorial, let's just use the Quick Mode, but of course you can use Complete Mode as well.

This is the code we are going to use:

exports.handler = async (event) => {

  const text = event.content.text;

  if (text.toLowerCase().includes('hot dog')) {
    return {
      content_type: 'image',
      content: {
P        url: 'https://media.istockphoto.com/photos/hot-dog-on-white-picture-id1130731707',
        _original_event: event,
      },
    };
  }

  return {
    content_type: 'text',
    content: {
      text: 'Not hot dog!',
      _original_event: event,
    },
  };

};

It is really simple: if the user text input contains the words "hot dog" anywhere, then return an image of a hotdog. Otherwise, change the text to "Not hot dog". In both cases, the original, untransformed event is still accessible with event._original_event in you CSML code, if needed.

Next, go to Apps > Add Custom App and under Quick Mode, simply copy and paste it, select a name for your app (for instance, hotdog seems like a fitting name), and click save.

Then, head to the Preprocessing page. We only want to preprocess text events, but of course, we could do a similar app for other types of events.

Now, back to the CSML Editor, you can do something like the following:

start:
  if (event.get_type() == "image") say Image(event)
  else say event
  goto end

CSML provides a way to execute external code in any language of your choice via a Foreign Function Interface, represented by the App() keyword.

Here are some ideas for CSML integrations:

• file tickets to Zendesk, ServiceNow or Front

• create leads in Hubspot, Mailchimp, Salesforce

• store data on Airtable, Google Sheet, Amazon DynamoDB

• upload files to Box, Google Docs, Office 365

• analyze text with SAP Conversational AI, Dialogflow, Rasa

• book meetings on Google Calendar, Hubspot, Calendly

• trigger events in Zapier, IFTTT, Integromat

• generate QR codes, format documents, upload images...

• and many more!

There are 2 ways you can augment your CSML chatbot by connecting it to other services: authoring your own custom apps, or installing ready-to-use CSML Integrations.

If you already have custom code that you would like to use in your chatbot, you can import it directly as a custom app in CSML Studio and use it without any change.

In CSML Studio, apps are run by default on AWS Lambda, which ensures maximum availability, scalability and security by isolating your code in separate containers. The supported runtimes are currently:

• Nodejs v10.x and 12.x

• Java 8 and 11

• Python 2.7, 3.6, 3.7 and 3.8

• Dotnetcore 2.1 and 3.1

• Go 1.x

• Ruby 2.5 and 2.7

To get started with AWS Lambda compatible deployment package in any language, you can refer to this documentation.

Quick Mode

The easiest way to author custom apps in CSML Studio is to use the Quick Mode, which provides you with a code editor to create your app directly in the browser. There are several limitations:

• only nodejs is supported (support for python will be added shortly)

• quick apps can not contain more than 4096 characters

• custom modules can not be added (however all native node modules are supported)

• environment variables can not be configured

If you need more configuration options (other languages, bigger package size, custom modules), we recommend using the Complete Mode as explained below.

As an example, let's create a simple nodejs 12.x app that will return a random user from RandomUser.me. This code performs a simple GET request to https://randomuser.me/api and returns the first user in the returned array. The code is available here on github: download it or clone it to get started.

The App Code

To test this program, simply run node test.js at the root of the project. You should see something like the following:

Authoring in Quick Mode

Select Add Custom App at the top-right corner of the apps page, which brings you directly to Quick Mode (nodejs). Simply copy-paste the content of index.js into the code editor, choose a name for your app, then click Save.

You can now use your app in your CSML Chatbot, like this:

start:
  do user = App("getRandomUser")
  say "The random user's name is: {{user.name.first}} {{user.name.last}}"
  goto end 

Complete Mode

With complete mode, a few extra steps are needed, as you will need to provide the code in a deployment package and upload it on the platform.

Creating a deployment package

At the root of the project as downloaded from github, run the command zip -r9 ../randomuser.zip .. This will create a deployment package for your app, that you will be able to import in CSML Studio.

Uploading to CSML Studio

In the sidebar, click on Apps > Add a new app. In the app creation page, upload your deployment package, give your app a distinctive and unique name such as getRandomUser, leave index.handler as your app's main handler and select nodejs12.x as the runtime.

You can leave the sections below as is for now; if your app took any argument or required any environment variable, this is where you would configure it.

Once you are done, simply save. You can now use your app in your CSML Chatbot as above.

Good practices

• As in every development project, apps have a processing cost associated to them. The more difficult the task is, the longer it takes to perform, the worse your user experience will be. Keep in mind that running apps will also increase the latency between the user's input and the bot's response. If possible, try to stick to native CSML code!

• It is always a good practice to only return what you intend to use. For example, if you are interfacing with a product catalog, do you need to get all 3542 items in the catalog, or will the first 5 suffice? If you are retrieving a list of items, what properties from that list do you actually need?

• Apps are limited to 30s of execution time. If it takes longer, the app will stop and return an error.

• Apps only get 512MB of RAM by default. Any excessive resource usage will lead the app to stop its execution immediately.

• If you are saving the output of your app to a do x = App(..) (or a remember), the data is subject to the usual memory size limitations. In general, if your app returns more than a few KB of data, ask yourself if you really need all that data that you most likely won't be able to display in a chatbot (text-based, so really light) or if you shouldn't strip it down directly in the app itself!

CSML Apps are a great way to extend the capabilities of your CSML chatbot by integrating other products with your bot without writing any additional code. CSML Studio provides a number of ready-to-user integrations (over 50 and growing!), that make it possible to integrate your chatbot with the most popular services and applications on the market.

CSML Studio integrations are ready to use. To configure an integration, you only need to configure the required credentials for this app (but some don't require any authentication!). The app's description will have the information on how to get setup.

Example: Giphy app

For instance, if you are looking to add some fun Gifs to your bot, you can try our Giphy integration. To get started, go to Apps > Available Integrations > Giphy.

Simply click on Install, and you are done! Some apps require credentials or API keys, but this one does not. If that's the case you are prompted to add environment variables upon installation.

Then, to use the app in your code, you can use it like this:

start:
  do gifs = App("giphy", action="gif", query="hello")
  say Image(gifs[0])
  goto end

CSML Studio also comes with a number of tools helping you perform day-to-day tasks such as generating QR codes, manipulating dates and times, or scheduling conversation events in the future.

Scheduler

The scheduler is a good way to plan events to happen at a later time. There are 2 types of scheduled events:

• webhook, when you want a certain URL to be notified at a later time

• broadcast, when you want to create a new conversation with the user later

To install the CSML scheduler, go to Apps > Available Integrations > Scheduler, and click Install.

Example scenario

Imagine an e-commerce chatbot where the user leaves the conversation before checkout, but has items in their cart. In that situation, you might want to send them a reminder a few hours later that they have items in their shopping cart and they might not want to loose them. Heck, why not throw a discount code with it?

Of course, if the user did go through with their order, you want to cancel this reminder, because it does not make sense to keep it.

Here is what this scenario would look like in CSML:

start:
  say "Thanks for shopping with us!"
  goto shop

shop:
  // cancel any existing reminder
  if (sched) do App("utils/scheduler", action="cancel", schedule_id="cart_reminder")
  // ... get the user to buy some items
  say Question("Select an item to buy", buttons=[Button("Mascara"), Button("Perfume")])
  hold
  // then add a new reminder with ID "cart_reminder"
  remember sched = App("utils/scheduler", delay="1 hr", flow_id="remind_cart", schedule_id="cart_reminder")
  
  say "You have {{cart.count}} items in your shopping cart, for a total of ${{cart.total}}"
  say Question(
    "What do you want to do?",
    button_type="quick_reply",
    buttons=[
      Button("Continue shopping 🛍") as shop,
      Button("Go to checkout 💵") as checkout,
    ]
  )
  hold
  // the user wants to continue shopping, let them do that
  if (event.match(shop)) {
    goto shop
  }
  goto checkout

checkout:
  // execute the order from the user
  say "Go to stripe payment page to pay here: XXX"
  hold
  // no need to remind the user anymore, they already paid
  if (sched) do App("utils/scheduler", action="cancel", schedule_id="cart_reminder")

Read below for more information on how to create scheduled items.

Scheduling a webhook call

You can schedule a POST request to a webhook using something like the following:

do sched = App(
    "utils/scheduler",
    action = "webhook",
    url = "https://my.url.com/whatever",
    body = { "some": ["custom", "data"] },
    delay = "10 min",
)
say "Created scheduled event with ID {{sched.result.schedule_id}}"

This means that in about 10 minutes, the endpoint https://my.url.com/whatever will receive a POST request containing the body { "some": ["custom", "data"] }.

Scheduling a broadcast

You can schedule a broadcast to the current user with something like the following:

do sched = App(
    "utils/scheduler",
    action = "broadcast",
    flow_id = "nameOfFlow",
    metadata = { "some": ["custom", "data"] },
    delay = "3 hrs",
)
say "Created scheduled event with ID {{sched.result.schedule_id}}"

This means that in about 30 minutes, the user will receive a new conversation initiated by the chatbot from flow nameOfFlow with the given additional metadata.

Cancelling a schedule

It is possible to cancel a scheduled event by calling the following app, where schedule_id is the ID of the schedule you want to cancel:

do App(
    "utils/scheduler",
    action = "cancel",
    schedule_id = schedule_id
)

Example response

{
    "success": true,
    "result": {
        "action": "broadcast",
        "flow_id": "remind_cart",
        "schedule_id": "some-id",
        "scheduled_at": "2020-07-09T20:02:57.255Z",
        "scheduled_at_unix": 1594324977
    }
}

Caveats

• Events will be executed within 1 minute after your event is scheduled.

• If you do not set your own schedule_id, a random schedule_id will be generated.

• You can use the delay (with either human-readable times, such as "1 hr", "5 min" or a number of milliseconds) or the schedule_time (an ISO-formatted time string OR unix timestamp integer describing when to schedule the event. Example: 1592843603, "2020-06-22T16:33:44.377Z") parameters to set the time for your event.

• You can schedule events at any point within the next 1 minute - 1 month.

• Failed events will not be retried. We guarantee that the event will go off, but make sure that your endpoint is available at the time of the scheduled webhook, or that the channel supports scheduled broadcasts.