Outgoing Webhooks

Outgoing Webhooks allow you to build or set up uKnowva Messenger integrations which are notified when certain types of messages are sent in uKnowva Messenger. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to power a wide range of uKnowva Messenger integrations. For example, the uKnowva Messenger Botserver is built on top of this API.

uKnowva Messenger supports outgoing webhooks both in a clean native uKnowva Messenger format, as well as a format that's compatible with Slack's outgoing webhook API, which can help with porting an existing Slack integration to work with uKnowva Messenger.

To register an outgoing webhook:

• Log in to the uKnowva Messenger server.
• Navigate to Settings () -> Your bots -> Add a new bot. Select Outgoing webhook for bot type, the URL you'd like uKnowva Messenger to post to as the Endpoint URL, the format you want, and click on Create bot. to submit the form/
• Your new bot user will appear in the Active bots panel, which you can use to edit the bot's settings.

Triggering

There are currently two ways to trigger an outgoing webhook: 1. @-mention the bot user in a stream. If the bot replies, its reply will be sent to that stream and topic. 2. Send a private message with the bot as one of the recipients. If the bot replies, its reply will be sent to that thread.

uKnowva Messenger message format

The uKnowva Messenger-format webhook messages post the following data, encoded as JSON:

Some of the important fields in the message dict include the following:

A correctly implemented endpoint will do the following:

• It will calculate a response that we call the "content" of the response.
• It will encode the content in uKnowva Messenger's flavor of markdown (or just plain text).
• It will then make a dictionary with key of "content" and the value being that content. (Note that "response_string" is a deprecated synonym for "content".)
• It will encode that dictionary as JSON.

If the bot code wants to opt out of responding, it can explicitly encode a JSON dictionary that contains response_not_required set to True, so that no response message is sent to the user. (This is helpful to distinguish deliberate non-responses from bugs.)

Example incoming payload

This is an example of the JSON payload that the uKnowva Messenger server will POST to your server:

{
    "bot_email": "outgoing-bot@localhost",
    "data": "@**Outgoing Webhook Test** uKnowva Messenger is the world\u2019s most productive group chat!",
    "message": {
        "client": "website",
        "content": "@**Outgoing Webhook Test** uKnowva Messenger is the world\u2019s most productive group chat!",
        "display_recipient": "Verona",
        "id": 112,
        "is_me_message": false,
        "raw_display_recipient": "Verona",
        "reactions": [],
        "recipient_id": 20,
        "recipient_type": 2,
        "recipient_type_id": 5,
        "rendered_content": "<p><span class=\"user-mention\" data-user-id=\"25\">@Outgoing Webhook Test</span> uKnowva Messenger is the world\u2019s most productive group chat!</p>",
        "sender_avatar_source": "G",
        "sender_avatar_version": 1,
        "sender_email": "iago@zulip.com",
        "sender_full_name": "Iago",
        "sender_id": 5,
        "sender_is_mirror_dummy": false,
        "sender_realm_id": 1,
        "sender_realm_str": "zulip",
        "sender_short_name": "iago",
        "stream_id": 5,
        "subject": "Verona2",
        "subject_links": [],
        "submessages": [],
        "timestamp": 1527876931,
        "type": "stream"
    },
    "token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0",
    "trigger": "mention"
}

Example response payloads

Here's an example of the JSON your server should respond with if you would not like to send a response message:

{
    "response_not_required": true
}

Here's an example of the JSON your server should respond with if you would like to send a response message:

{
    "content": "Hey, we just received something from uKnowva Messenger!"
}

Slack-format webhook format

This interface translates uKnowva Messenger's outgoing webhook's request into the format that Slack's outgoing webhook interface sends. As a result, one should be able to use this to interact with third-party integrations designed to work with Slack's outgoing webhook interface. Here's how we fill in the fields that a Slack-format webhook expects:

The above data is posted as list of tuples (not JSON), here's an example:

[('token', 'v9fpCdldZIej2bco3uoUvGp06PowKFOf'),
 ('team_id', 'zulip'),
 ('team_domain', 'zulip.com'),
 ('channel_id', '123'),
 ('channel_name', 'integrations'),
 ('timestamp', 1532078950),
 ('user_id', 21),
 ('user_name', 'Sample User'),
 ('text', '@**test**'),
 ('trigger_word', 'mention'),
 ('service_id', 27)]

• For successful request, if data is returned, it returns that data, else it returns a blank response.
• For failed request, it returns the reason of failure, as returned by the server, or the exception message.