Cloud code

Execute custom code that is hosted on the flow.ai platform. Cloud code is JavaScript that runs in a sandboxed environment and allows you to easily customise and extend Flow.ai's capabilities.

Please note: When using cloud code the code execution or a call to a service must be done within 10 seconds.

Payload

Cloud code is a single function that is called with a payload. The payload contains data and information regarding the message that triggered the action and user.

Example:

/**
@param {object} payload - data and info
@param {string} payload.channelName - type of channel
@param {string} payload.query - what the user sends
@param {object} payload.params - data detected by AI
@param {object} payload.user - user that triggered the action
@param {string} payload.user.name - name of the user
@param {string} [payload.user.profile.firstName] - first name of the user
@param {string} [payload.user.profile.lastName] - Last name of the user
@param {string} [payload.user.profile.fullName] - first and last name combined
@param {string} [payload.user.profile.picture] - profile picture
@param {string} [payload.user.profile.locale] - user language
@param {string} [payload.user.profile.gender] - user gender
*/
(function(payload) {
    // Your custom logic
})

Triggers and params

Depending on the actions prior to execution you can expect a set of various params. For example a user shares a file or the bot detects a named entity.

Entities

AI can detect entities within text and those become availiable within your code. For example if a user asks: I want to book a hotel in Amsterdam and Amsterdam would be a entity named destinationCity. Note that params are always lists (arrays). The AI could detect multiple similair entities, for example: I want to book a hotel in Amsterdam and Kopenhagen.

Example:

if(Array.isArray(payload.params.destinationCity)) {
    payload.params.destinationCity.forEach(city => {
        // Do something with the city
        // city.value (keyword of the entity)
        // city.match (matched word, could have misspellings etc)
    })
}

Multimedia

When a user shares an image, video, audio or file the action will receive a collection of media elements:

Example:

// User shares an image
if(Array.isArray(payload.params.image)) {
    payload.params.image.forEach(image => {
        // Do something with the image
        const url = image.value
        // ..
    })
}

Location

When a user shares a location, the action will receive a collection of locations:

if(Array.isArray(payload.params.location)) {
    payload.params.location.forEach(location => {
        // Do something with the location
        const { lat, long } = location.value
        // ..
    })
}

Sending messages

Within cloude code all reponse templates are available. This allows you to build and send rich template responses within your custom code.

There are two methods to send back messages to a user. First is by simply returning within the cloud function, the other is by using the reply method.

Here is an example of sending a single message back to a user:

(function(payload) {

  const image = new Image({
    title: "Image description",
    url: "https://...."
  })

  return new Message('Cats are amazing creatures!')
    .addResponse(image)
})

A message can contain multiple response templates.

(function(payload) {

  const image1 = new Image({
    title: "Image description",
    url: "https://...."
  })

  const image2 = new Image({
    title: "Image description",
    url: "https://...."
  })

  return new Message('Cats are amazing creatures!')
    .addResponse(image1)
    .addResponse(image2)
})

It's also possible to reply with multiple messages. You might want to do that if you work with voice and speech based interfaces.

(function(payload) {
  return [
    new Message('Cats are amazing creatures!'),
    new Message('Or are you a dog person?')
  ]
})

Async replies

When you make a async call within your code it's not possible to reply with a message using the return method. Instead we provide a simple method called reply.

You can use reply to send back a single message back to a user.

Example:

// Send back a reply message to a user. 
// Use this when you have async logic like making a request to a REST API.
const message = new Message('Just saying hello')
reply(message)

Toolbelt

We provide a collection of builtin functions for doing stuff like sending notifications, emails or pauzing a bot

takeover

Notify the conversation needs to be taken over by a human. This will send a web push notification and place the interaction within the take over required list.

Optionally you can specify a custom message to be send with the notification.

Example:

toolbelt.takeover('Please review')

pauseBot

Temporarily disable all automatic interaction for a number of minutes. The duration is configured within the brain settings (Minutes to auto pause).

Example:

toolbelt.pauseBot()

email

Send an email notification. We support 2 type of email templates:

  • Takeover
  • Default

A take over email will list the contain last 20 messages of the conversation.

Example:

toolbelt.email({ 
  to: '[email protected]',
  // Optionally assign a custom title
  // subject: 'Please review;,  
  template: 'takeover'
})

With the default template you can send a custom message.

Example:

toolbelt.email({ 
  to: '[email protected]', 
  subject: 'Email subject', 
  message: 'Email message'
})

Request

Use the request module to make calls to other services. Do note that we have a execution time limit of 10 seconds. If your're backend call has not completed within that time span, it will fail.

(function(payload) {

  // Make a GET call
  request.get('https://api.themoviedb.org/3/movie/popular?api_key=YOUR_KEY')
    .then((result) => {

      const {
        status,
        data
      } = result

      // Check if we found movies
      if(status !== 200 || !data || !data.results || !data.results.length) {
        return reply(new Message(`No popular movies found..`))
      }

      // Create a list for movie titles
      const titles = []

      // Create a card carousel
      const carousel = new Carousel()

      data.results.forEach((movie, idx) => {

        if(idx >= 4) {
          // Just 5 movies, skip the other
          return
        }

        // Add the title to the list
        titles.push(movie.title)

        // Create a movie card
        const card = new Card({
          title: movie.title,
          subtitle: movie.overview,
          image: new Media(`https://image.tmdb.org/t/p/w500${movie.poster_path}`)
        })

        // Add the card to the carousel
        carousel.addCard(card)
      })

      // Create a message with fallback speech
      const message = new Message(`The most popular are ${titles.join(', ')}`)
      message.addResponse(carousel)

      // Send the popular movies
      reply(message)
    })
    .catch(err => {
      // This is not good..
      reply(new Message(`Computer says no..`))
    })
  })

More information how to use request at https://github.com/mzabriskie/axios

results matching ""

    No results matching ""