Stealth Smooch

This integration adds support for Smooch powered bots within Stealth. It can be used as a drop-in replacement for stealth-facebook with the exception of some specialized quick reply buttons (such as Email & Phone).

Via the Smooch interface, create a new Smooch app for your Stealth bot. Once you do, you'll be given your SMOOCH_APP_ID.

Follow the instructions on the smooch-api Ruby page to generate your secret keys. This will get you your SMOOCH_KEY_ID and SMOOCH_SECRET.

The last thing you will need is the SMOOCH_JWT_TOKEN which can be generated using this gem. After you have set the above creds to your services.yml file, from your bot's console, run:

Stealth::Services::Smooch::Client.generate_jwt_token

It will output the JWT token based on the app_id, key_id, and secret from your services.yml file.

You will want to add the Webhooks integration to the Smooch app you created above. Currently, this driver supports AppUser messages, Postbacks, and the Conversation Start webhooks.

Please note: the Conversation Start webhook is configured to send a payload with the value of conversation_start. Please handle that accordingly in your BotController.

default: &default
  smooch:
    app_id: <%= ENV['SMOOCH_APP_ID'] %>
    key_id: <%= ENV['SMOOCH_KEY_ID'] %>
    secret: <%= ENV['SMOOCH_SECRET'] %>
    jwt_token: <%= ENV['SMOOCH_JWT_TOKEN'] %>
    setup:
      persistent_menu:
        - type: 'url'
          url: 'https://mywebsite.com'
          text: 'About Us'
        - type: 'payload'
          payload: 'contact_support'
          text: 'Contact Support'

production:
  <<: *default

development:
  <<: *default

test:
  <<: *default

Additionally, you will need to create an initializer called smooch.rb in config/initializers:

SmoochApi.configure do |config|
  config.api_key['Authorization'] = Stealth.config.smooch.jwt_token
  config.api_key_prefix['Authorization'] = 'Bearer'
end

As with all Stealth integrations, integrations can be specified by environment.

These are the supported setup options:

The persistent menu is not supported by all integrations. For a complete list, please check out the Smooch Pesistent Menu Docs.

Setting the persistent menu is identical to creating buttons in text replies. Please see those docs for more info.

In order for your bot to receive messages from the Smooch app, we'll need to register our webhooks.

Set SMOOCH_ENDPOINT to the endpoint that will be receiving the hooks. It's configured as an ENV variable so you can specify different endpoints for each of your environments.

After you have set SMOOCH_ENDPOINT, running setup below will register your webhooks.

This will set the persistent menu (if available) and register your webhooks.

stealth setup smooch

Here are the supported replies for the Smooch integration:

These are standard text replies.

- reply_type: text
  text: Hello World!

Text replies can also include suggestions, which will be rendered as quick replies:

- reply_type: text
  text: What is your favorite color?
  suggestions:
    - text: Blue
    - text: Red

Although not as common, text replies can also include buttons:

- reply_type: text
  text: Would you like to give us a call?
  buttons:
    - type: payload
      text: 'Yes'
      payload: 'Yes'
    - type: payload
      text: 'No'
      payload: 'No'

Though suggestions are not a reply type on their own, they are frequently used to optimize the accuracy and speed of your bot. In the text reply type above, we used simple labels for our suggestions. Smooch supports a few special types of quick replies, however.

You can ask a user for their location:

- reply_type: text
  text: "Where are you located?"
  suggestions:
    - type: location

If the user chooses to share their location, the lat and lng will be available via current_message.location:

current_message.location[:lat]
current_message.location[:lng]

While images are not a special quick reply type, you can include and image_url for a quick reply as way of adding an icon to a quick reply button:

- reply_type: text
  text: "What is your favorite color?"
  suggestions:
    - text: Red
      image_url: "http://example.com/img/red.png"
    - text: Blue
      image_url: "http://example.com/img/blue.png"

More info here.

As with suggestions, buttons are not a reply type of their own but are used to make your bot more efficient. Smooch supports a few button types and these are the ones currently supported by this integration:

This is the most common button type. When a user presses a button that is payload type, that payload string will be sent to your bot. For example:

- reply_type: text
  text: Please press the button below
  buttons:
    - type: payload
      text: 'Press me!'
      payload: 'button pressed'

When a user presses the button labeled "Press me!", the payload button pressed will be accessible in bot via current_message.payload.

The url button is useful when sharing a link to a website. By default, it will open up within Facebook Messenger.

- reply_type: text
  text: Find out more via our website
  buttons:
    - type: url
      text: 'Visit website'
      url: 'https://example.org'

Delays are a very important part of bot design. They introduce a pause between text replies to give the user a chance to read each reply. With this integration, in addition to introducing a delay, we will also send a typing indicator to the user to indicate another reply is forthcoming. To insert a delay in your bot:

- reply_type: delay
  duration: 2

This will add a 2 second delay (with typing indicator). The duration can be specified as any floating point value, in seconds.

Smooch distinguishes between a single card and a carousel of cards. This integration does not, however. You can send a single card the same way you would send 10 cards (the current maximum).

- reply_type: cards
  elements:
    - title: My App
      subtitle: Download our app below or visit our website for more info.
      image_url: "https://my-app.com/app-image.png"
      buttons:
        - type: url
          url: "https://my-app.com"
          text: 'View'
          webview_height: 'tall'
        - type: url
          url: "https://itunes.apple.com/us/app/my-app"
          text: 'Download iOS App'

The above is a single card with two buttons. If you want to include more cards, though, you would just need to specify another listing under the elements heading.

More info about Smooch cards here.

A Smooch list is useful for displaying things like a news feed. You can find more info about Smooch lists here.

To generate a list:

- reply_type: list
  buttons:
    - type: payload
      text: View More
      payload: view_more
  elements:
    - title: Your Daily News Update
      subtitle: The following stories have been curated just for you.
      image_url: "https://picsum.photos/320/240"
      buttons:
        - type: url
          url: "https://news-articles.com/199"
          text: 'View'
    - title: Breakthrough in AI
      subtitle: Major breakthrough in the AI space.
      image_url: "https://picsum.photos/320/320"
      buttons:
        - type: url
          url: "https://news-articles.com/201"
          text: 'View'

The list itself supports having a single button that will be rendered on the bottom of the list. Each individual list item supports having one button as well. List items should have between 2-4 elements.

More info about Smooch lists here.

To send an image:

- reply_type: image
  image_url: 'https://example.org/image.png'

The image_url should be set to URL where the image has been uploaded.

Image replies support buttons and suggestions like text replies.

To send a file:

- reply_type: file
  file_url: 'https://example.org/some.pdf'

The file_url should be set to URL where the file has been uploaded.

File replies support buttons and suggestions like text replies.

To send a video:

- reply_type: video
  video_url: 'https://example.org/cool_video.mp4'

The video_url should be set to URL where the video has been uploaded.

Video replies support buttons and suggestions like text replies.

To send an audio clip:

- reply_type: audio
  audio_url: 'https://example.org/podcast.mp3'

The audio_url should be set to URL where the video has been uploaded.

Audio replies support buttons and suggestions like text replies.

When adding features to this library, you might find it helpful to get a full printout of the HTTP requests and responses from Smooch.

In order to configure your bot to show the debug output, modify your smooch.rb initializer like so:

class SmoochLogger

  def self.debug(msg)
    Stealth::Logger.l(topic: 'smooch', message: msg)
  end

end

SmoochApi.configure do |config|
  config.logger = SmoochLogger
  config.debugging = true
  config.api_key['Authorization'] = Stealth.config.smooch.jwt_token
  config.api_key_prefix['Authorization'] = 'Bearer'
end