Introduction to Commands

Text Commands

A text command simply responds to the user immediately with a text that you have predefined in the command configuration. These kind of commands are useful for having frequent text, links or information that your team needs to access on a recurring basis.

For example: you can create a text command named "manifesto" that responds with a text description of what your company manifesto is. Users will be able to use that command in channels or from private conversations with DailyBot.

In-chat Forms triggered by Commands

It is possible to create commands that trigger a native in-chat form that you build with DailyBot. With DailyBot forms and commands you can build use cases based on data that you collect through the chat, the you enter in a Form will be stored in a DailyBot table, and you can use DailyBot to also search for responses stores in that Form.

On the web application, navigate to the "Forms" section to learn more. If you want to search across the form responses, type the command name followed by the keyword "search" and then your query.

Example: if your command to trigger a form is named "inventory", you can also type "inventory search my_keyword" - DailyBot will give you the responses that match with your search.

HTTP Commands

The HTTP Commands let you process a DailyBot command with an app (endpoint) of your own creation, and then respond with dynamic information. This is very powerful and useful for many use cases.

For example: you can create an HTTP command named "sales" and implement your logic to return the key metrics, so users can access this information in a simple way just using DailyBot, from their own chat app (desktop or mobile).

You can even use HTTP commands for ChatOps: implementing custom workflows and operations of your company that run entirely on the chat. More examples include: deploying an app, getting the version of an app, showing analytics, seeing a repository active branches, etc.

Implementing a custom command

HTTPS required

Your endpoint implementation must be HTTPS (mandatory) - and you can configure the HTTP method you want to trigger, on the web application.

Once a command is processed, DailyBot delivers a payload to your endpoint, including special HTTP headers.

Headers

X-DailyBot-Signature: String

The X-DailyBot-Signature header will include your Command signature. You can get the signature by opening your command (in the web app, edit mode) and then clicking the "view signature" link.

Recommendation: use the signature header in your endpoint to validate that the request is authentic.

Processing the request

The payload will include basic information for you to identify the user and the DailyBot workspace. It also defines whether the message is coming from a public channel.

Request body (payload) example:

  
  {
    "intent": "your_command_intent_name",
    "event_timestamp": 1620847161125,
    "organization_uuid": "d470abcd-b311-4f4d-81a8-2ca290845432",
    "organization_timezone": "America/Bogota",
    "user_uuid": "0024dg21-1c12-4d31-a31f-95e26f675432",
    "user_full_name": "John Doe",
    "user_external_id": "U026YK187FW",
    "user_timezone": "America/New_York",
    "user_role": "ADMIN",
    "is_channel_message": false,
    "channel": "XDSZ1232",
    "exchange_token": null,
    "platform": "slack",
    "params": {
      "query": ""
    }
  }
  

‍

These are the fields:

• intent: your command intent name
• event_timestamp: timestamp related to when the user triggered the command
• organization_uuid: UUID related to the DailyBot organization
• organization_timezone: ISO timezone for this DailyBot organization
• user_uuid: UUID related to the user who triggered the command
• user_full_name: Full name of user who triggered the command
• user_time_zone: ISO timezone for the user who triggered the command
• user_role: the DailyBot role for the user who triggered the command (ADMIN, MEMBER)
• is_channel_message: boolean, when true, it indicates the command was triggered in a channel. When false, it indicates it is a direct message to DailyBot.
• channel: chat platform channel ID related to where the command was triggered
• exchange_token: optional, it includes a special token for commands that will reply async
• platform: the chat platform name where the command was triggered
• params: additional query params that were passed to the command when it was triggered

‍

Implementing complex logic with the "params.query"

Notice you can build your command to implement more complex logic, using the params.query object.

When users use the command, they can include more words or numbers after the command invocation (separated with a space).

Example:

• Your command name is "sales"
• If a user types "sales report for 3 days" — you will get a params: {query:"report for 3 days"}
• If a user types "sales report from last week" — you will get a params: {query:"report from last week"}

As you can see, you can use one only Command in DailyBot to build complex utilities that can react to multiple parameters.

💡 Recommendation:

If you are developing any complex logic and your command will support several parameters, consider adding a "help" keyword to give instructions to the users about how to use the command logic.

Responding to the request

The Content-Type should always be application/json.

Your endpoint can use different formats to respond to the command's request:

1. Plain text content
2. JSON: you can configure the command to use a specific JSON field as the response text that will be displayed to the user
3. Interactive buttons: respond with a special payload to include text and interactive buttons. Users will be able to click those buttons and that will send another payload to your endpoint

Responding with plain text content

The simplest method, just make sure your endpoint responds with a text body (as a JSON valid string). DailyBot will render that text to the user. You can also use simple markdown.

Hi, this is a *text response*.

Responding with a JSON field

Your endpoint can respond with a JSON object. You can specify what JSON field should be used as the response to be rendered to the user.

Configure the JSON response param in DailyBot's web app, at the command settings page:

Responding with interactive buttons

Use a JSON to include a payload with a special format if you want to render buttons.

  
  {
    "message": "Hi, this is your command responding to DailyBot.",
    "buttons": [
      {
        "label": "button_title",
        "label_after_click": "message_after_the_button",
        "value": "your_command_intent_name optional_param",
        "button_type": "Command"
      }
    ],
    "image_url": "link"
	}
  

‍

‍In case you are using a custom JSON Response Param, you must include this response payload in your JSON Response Param.

• message: required Text, the text that will be displayed to the user
• buttons: optional Array, the interactive buttons
• image_url: optional URL, an image (png, gif, jpg) that will be rendered as an in-chat card

‍

Notice that the buttons have to be an array, and each item will be a button, it includes these fields:

• label: the button label the user sees
• label_after_click: once the user clicks the button, DailyBot will show this text to the user
• value: the actual value that DailyBot will process. IMPORTANT: this should always include your command intent name, e.g. "sales button_1_clicked"
• button_type: it should always contain the word "Command" - this field will allow future features/behaviors around buttons.

‍

Buttons example

Let's see an example for the "sales" command, responding with a few buttons/choices for the user:

The following code will render these buttons:

  
  {
    "message": "Last week sales were " + percent_increase_sales + " 📈",
    "buttons": [
      {
        "label": "Last month",
        "label_after_click": "Getting sales last month...",
        "value": "sales last month",
        "button_type": "Command"
      },
      {
        "label": "Last quarter",
        "label_after_click": "Getting sales last quarter...",
        "value": "sales last quarter",
        "button_type": "Command"
      },
      {
        "label": "Current MRR",
        "label_after_click": "Getting the current MRR...",
        "value": "sales MRR",
        "button_type": "Command"
      }
    ]
	}
  

‍

Response times

Your endpoint should process the request and respond to DailyBot in less than 10 seconds.

Do you need to process a message for more than 10 seconds? It is possible to respond asynchronously, please contact our support team. This option is available but is not currently open for all developers.

🛠 Code example

We created a CodeSandbox project where you can see a Command implementation example in NodeJS.

https://codesandbox.io/s/dailybot-sample-command-demo-6nu1u

You can use CodeSandbox to clone the project (fork) and play with it yourself.

‍