Slack proxying

Message handlers

When omnibot routes messages to your handler, the handler doesn’t need to talk to slack; omnibot will do that for you. Just respond with a list of actions for omnibot to take on your behalf. The actions are just slack api calls you’d make:

{
    "actions":
    [
        {
            "action": "chat.postMessage",
            "kwargs": {
                "text": "Please do not use @here."
            }
        },
        {
            "action": "reactions.add",
            "kwargs": {
                "name": "broken_heart"
            }
        }
    ]
}

action is the API call to make, and kwargs is the key word arguments you’d pass into that API call.

Note that normally for most actions you’d need to include channel or thread_ts, but omnibot will automatically fill those in with the current channel and thread_ts, unless you override it. By default omnibot will always use a thread_ts, responding to messages using a thread; if you’d like to respond in the channel, rather than in a thread, you can set thread_ts to None.

When you send messages through the API, you need to use slack message format for things like links, channels, users, specials, etc.. Omnibot can handle these for you, if you’d like. To have omnibot parse your message into the right format, send the omnibot_parse keyword arg into the kwargs. omnibot_parse is a dict, mapping the field you want to parse with what you want parsed. For instance, let’s let omnibot parse the above message for us:

{
    "actions":
    [
        {
            "action": "chat.postMessage",
            "kwargs": {
                "text": "Please do not use @here.",
                "omnibot_parse": {"text": ["specials"]}
            }
        },
        {
            "action": "reactions.add",
            "kwargs": {
                "name": "broken_heart"
            }
        }
    ]
}

If the message isn’t parsed, then the @here in the above message would show as plain text. We’re now telling omnibot to parse the text kwarg and replace any special it finds (@here) with the slack formatted version (<!here|here>).

Slash command and interactive component handlers

When omnibot routes slash commands or interactive component events to your handler, the handler doesn’t need to talk to slack; omnibot can do that for you. Just respond with a list of responses for omnibot to send back to the response_url on your behalf. The responses are just standard responses you’d give back to the slash command or interactive component APIs:

{
    "responses":
    [
        {
            "text": "pong",
            "attachments": [
                {
                    "text": "Look at this game of ping pong over @here"
                }
            ]
        },
        {
            "response_type": "ephemeral",
            "text": "a private pong"
        }
    ]
}

Note that if you do not provide a response_type in the response, the default will be what’s set for the handler; if the handler doesn’t have response_type set, it defaults to ephemeral.

When you respond, you need to use slack message format for things like links, channels, users, specials, etc.. Omnibot can handle these for you, if you’d like. To have omnibot parse your message into the right format, send the omnibot_parse keyword arg into the response. omnibot_parse is a dict, mapping the field you want to parse with what you want parsed. For instance, let’s let omnibot parse the above message for us:

{
    "responses":
    [
        {
            "text": "pong",
            "attachments": [
                {
                    "text": "Look at this game of ping pong over @here"
                }
            ],
            "omnibot_parse": {"text": ["specials"]}
        },
        {
            "response_type": "ephemeral",
            "text": "a private pong"
        }
    ]
}

If the text isn’t parsed, then the @here in the above response would show as plain text. We’re now telling omnibot to parse the text kwarg and replace any special it finds (@here) with the slack formatted version (<!here|here>).

Unlike messages, it’s possible for your handler to respond directly to slash command or interactive component events, rather than needing to go back through omnibot. The response_url provided in the payload sent to your handler can be used to send responses. For each response you’d like to send, you’ll need to send it as a POST payload to the response_url. Remember, though, that you’ll need to send text in slack message format, which will require you to do your own parsing. Check out omnibot’s API for endpoints you can use to do basic parsing or lookups.

It’s also possible to ask omnibot to do a set of actions for you, as well; for instance:

{
    "responses":
    [
        {
            "text": "pong",
            "attachments": [
                {
                    "text": "Look at this game of ping pong over @here"
                }
            ]
        },
    ],
    "actions": [
        {
            "action": "chat.postMessage",
            "kwargs": {
                "channel": "pong",
                "text": "Someone pinged!",
                "omnibot_parse": {
                    "channel": ["channels"]
                }
            }
        }
    ]
}

The above will respond back to the slash command or interactive component, but it will also post a message into the pong channel on your behalf.