Writing custom commands

Writing custom slash commands

There are many occasions when it would be useful to have your own slash commands that do things that are specific to your own business. For example, you might want to create a command that can automatically send an invoice to a customer when they ask for one on your live chat.

To write your own slash command you will need to create your own web service that can accept an HTTP request from Natterly and respond with an array of instructions that should be performed. Once you have this, you can map a command to your own URL.

When the command is executed by a user a POST request will be made to the URL associated with the command. This request will include information about the chat & user in the body of the request. The body will be a JSON hash with the following attributes:

  • chat - full details about the chat (see API reference)
  • command - the command name that was executed
  • argument - any arguments that were provided after the command name
  • user - details about the user who invoked the command (see API reference)

Responding to a slash command request

You should respond to the HTTP request within 3 seconds and it must return a 200 OK status with a JSON-encoded body. The actual body will define how Natterly will action your request.

The response should be an array containing a number of hashes. Each hash in the array represents an action that will be performed (in order) by Natterly. This is an example:

      "text":"This is an example message!"
      "text":"This is an example whisper!",

The actions that are available as shown below. Depending on the action, additional information will also be required to be sent along with it.

If any of the actions fails to be executed, all further actions will be cancelled and an error will be sent to the channel for all users to see.

  • SendMessage - this action will send a message to the chat that the command is executed within. The message will always be shown as from the person executing the action.

    • A message hash should also be included within the action hash.
    • The text attribute should contain the text for the message.
    • The visibility attribute controls who sees the message. It can be "Full" (to show it to everyone), "User" (to show to users only) or "Visitor" (to show to visitors only).
    • The formatting attribute controls how the message should be formatted.
    • The event attribute is a boolean if you'd prefer the message be shown as an event rather than an actual message.
  • CloseChat - this action will close the chat that the command was executed within. No further attributes are required.

Configuring your new slash command

Once you have a URL that can executed your slash command you need to configure it within the Natterly console. Login and head over to Settings and then Integrations. You'll find an integration called Slash Commands and you'll be able to configure it in there.