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).
Create Your Smooch App
Via the Smooch interface, create a new Smooch app for your Stealth bot. Once you do, you'll be given your
Follow the instructions on the smooch-api Ruby page to generate your secret keys. This will get you your
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:
It will output the JWT token based on the
secret from your
You will want to add the
Webhooks integration to the Smooch app you created above. Currently, this driver supports
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
Configure the Integration
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
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.
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
lng will be available via
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.
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
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
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'
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'
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'
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'
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