This document discusses how to build a YellowAnt application with Ruby on Rails that allows users to manage a to-do list. It covers defining commands, handling user authentication through OAuth, processing commands by verifying tokens and checking event types, and formatting response messages with attachments, fields, buttons, and additional data. The example application will have commands to create, delete, get, list, and update to-do items, with the responses rendered back in the YellowAnt client.

1. Building a YellowAnt
application with Ruby on
Rails

2. Basics first
Every application on YellowAnt has an invoke name
Every application on YellowAnt comprises of commands
A command may or may not have arguments
An argument can be of different types: int, string, boolean etc.
An argument may or may not be required for the command
Every command returns a YellowAnt message
A command may optionally return some data along with the message to be used
in workflows

3. How users will use your application
A user will first authenticate your application with his/her YellowAnt account
You will receive an oAuth code in your redirect_url
You will exchange that code for a permanent user token
You will create a user integration
Your application will then show in the list of integrated applications for the user
The user will then be able to command your application through Dialogs,
commands, buttons or workflows from Slack or Teams

4. Example
You create an GMail application integration with invoke name “gmail”
You create commands : send(takes inputs to, subject and body) and list(take
args label)
The user authenticates your application with his/her YellowAnt account and then
authenticated his/her GMail application. You create a new user integration “gmail”
and store the Gmail credentials against the user integration id
The user can then go to Slack.Teams and command:
gmail send to “vishwa@yellowant.com” subject “Test” body “Test”
You process the send command and send back a confirmation message

5. Example - continued
The user can also integrate another Gmail account. In this case, when the you
create a new user integration after authenticating the user’s YellowAnt and GMail
account, the new invoke name for the user will be gmail-1, since gmail is already
being used. You store the new Gmail credentials against this new user integration
id
To send an email, now from a different account, the user can command:
gmail-1 send to “vishwa@yellowant.com” subject “Test” body “Test”
If the user integrated a third email account, the new user integration id will be
gmail-3… and so on

6. Application OAuthentication flow
Application
1. User visits application page
2. Application redirects to YellowAnt
authentication page
3.
User grants
access
5.
App exchanges auth
code with long-lived token
4.
Server returns
authorization code
6. App creates user integration

7. What we will be building
A YellowAnt bot with invoke name “todo” that creates a to-do list and allows users
to
● Create an item
● List all items
● Update an item
● Delete an item

8. Database we will query through YellowAnt

9. Step 1: Define the application, commands and args
1. create_item
2. deleteitem
3. getitem
4. get_list
5. updateitem

10. Setting up user authentication
Redirect to YellowAnt Authentication URL
Obtain authentication code
Exchange auth code with token
Fetch User details
Create new application integration for the user

11. Command flow
Application
1.User executes
command in
client(YellowAnt Web
/Slack/Teams)
2.YellowAnt send
command object to
application api_url
3.Application processes
command and send back
message object
4.YellowAnt renders
message object in client

12. Processing commands
Verify verification_token
Check event_type
For “event_type” == “command”: get function name and parameters. Process
command.
Construct Message Object
Append some data to the message
Return Message

13. Formatting: Attachments
1. title
2. text
3. images

14. Formatting: Fields
1. title
2. text

15. Formatting: Buttons
1. Encoding command in buttons
2. Asking user for additional inputs

16. Adding data to response
1. Defining output keys
2. Adding output keys to functions
3. Appending data to message object