By using Custom Commands, you can receive all messages sent using a specific slash command, eg. /ticket, in your application. When configured, every slash command message happening in a Stream Chat application will propagate to an endpoint via an HTTP POST request.

1
2
3
4
const message = { 
    text: '/ticket suspicious transaction with id 1234' 
}; 
const response = await channel.sendMessage(message);

Setting up your Custom Command consists of the following steps:

1. Registering your Custom Command

2. Configure a Channel Type

3. Configuring a Custom Action Handler URL

4. Implement a handler for your Custom Command

The API provides methods to create, list, get, update, and delete Custom Command definitions. These determine which commands are allowed to be used and how they're presented to the user by providing a description of the command.

1
2
3
4
5
6
await client.createCommand({ 
	name: "ticket", 
	description: "Create a support ticket", 
	args: "[description]", 
	set: "support_commands_set", 
});

Please note that applications have a hard limit of 50 custom commands. If you need more than this please have a look at the Multi-tenant & Teams section.

You can retrieve the list of all custom commands defined for your application.

1
await client.listCommands();

You can retrieve a custom command definition.

1
await client.getCommand("ticket");

Custom command description, args & set can be changed. Only the fields that must change need to be provided, fields that are not provided to this API will remain unchanged.

1
2
3
await client.updateCommand("ticket", { 
	description: 'Create customer support tickets', 
});

You can remove a custom command definition.

1
await client.deleteCommand("ticket");

In order to be able to use this command in a channel, we’ll need to create, or update an existing, channel type to include the ticket command.

1
2
3
4
await client.createChannelType({ 
    name: "support-channel-type", 
    commands: ["ticket"], 
});

In order to use the defined custom commands, you will first have to set an endpoint URL in the App Settings.

1
2
3
await client.updateAppSettings({ 
	custom_action_handler_url: "https://example.com/webhooks/stream/custom-commands?type={type}", 
});

Your endpoint will receive a POST request with a JSON encoded body containing: message, user and form_data objects. The form_data object will contain values of the interactions initiated by either Attachment or MML actions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{ 
   "message":{ 
      "id":"", 
      "text":"/ticket suspicious transaction with id 1234", 
      "command": "ticket", 
      "args": "suspicious transaction with id 1234", 
      "html":"", 
      "type":"regular", 
      "attachments":[], 
      "latest_reactions":[], 
      "own_reactions":[], 
      "reaction_counts":null, 
      "reaction_scores":null, 
      "reply_count":0, 
      "mentioned_users":[], 
      "silent":false 
   }, 
   "user":{ 
     "id":"17f8ab2c-c7e7-4564-922b-e5450dbe4fe7", 
     "role":"user", 
     "banned":false, 
     "online":false 
   }, 
   "form_data":{ 
      "action":"submit", 
      "name": "John Doe", 
      "email": "john@doe.com" 
   } 
}

If you intend to make any change to the message, you should return a JSON encoded response with the same message structure. Please note that not all message fields can be changed, the full list of fields that can be modified is available in the rewriting messages section.

Your endpoint can decide to reject the command and return a user message. To do that the endpoint must return a regular message with type set to error.

1
2
3
4
5
6
{ 
   "message":{ 
      "type":"error", 
      "text":"invalid arguments for command /ticket" 
   } 
}

You can also decide to modify the message, in that case you return the updated version of the message and it will overwrite the user input.

1
2
3
4
5
{ 
   "message":{ 
      "text":"Ticket #85736 has been created" 
   } 
}

Interactions can be initiated either using Attachment actions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{ 
   "message": { 
    "text": "Ticket #85736 has been created", 
    "attachments": [ 
        { 
            "type": "text", 
            "actions": [ 
                { 
                    "name": "action", 
                    "text": "Send", 
                    "style": "primary", 
                    "type": "button", 
                    "value": "submit" 
                }, 
                { 
                    "name": "action", 
                    "text": "Cancel", 
                    "style": "default", 
                    "type": "button", 
                    "value": "cancel" 
                } 
        } 
    ] 
   } 
}

Or by using MML formatted messages:

1
2
3
4
5
{ 
   "message": { 
   "text": "this message contains a MML message." 
   "mml": "<mml><text>Ticket #85736 has been created</text><button name=\"action\" value=\"submit\">Send</button></mml>", 
}

Your webhook endpoint will be part of the send message transaction, so you should avoid performing any remote calls or potentially slow operations while processing the request. Stream Chat will give your endpoint 1 second of time to reply. If your endpoint is not available (ie. returns a response with status codes 4xx or 5xx) or takes too long, Stream Chat will continue with the execution and save the message as usual.

To make sure that an outage on the hook does not impact your application, Stream will pause your webhook once it is considered unreachable and it will automatically resume once the webhook is found to be healthy again.

An example of how to handle incoming Custom Command requests can be found in this repo.