Outgoing webhooks

Outgoing webhooks allow you to build or set up WyzePal integrations which are notified when certain types of messages are sent in WyzePal. 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 WyzePal integrations. For example, the WyzePal Botserver is built on top of this API.

WyzePal supports outgoing webhooks both in a clean native WyzePal 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 WyzePal.

To register an outgoing webhook:

  • Log in to the WyzePal server.
  • Navigate to Settings () -> Your bots -> Add a new bot. Select Outgoing webhook for bot type, the URL you'd like WyzePal 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.

Outgoing webhook format

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

{
    "bot_email": "outgoing-bot@localhost",
    "data": "@**Outgoing webhook test** WyzePal is the world\u2019s most productive group chat!",
    "message": {
        "avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1",
        "client": "website",
        "content": "@**Outgoing webhook test** WyzePal is the world\u2019s most productive group chat!",
        "display_recipient": "Verona",
        "id": 112,
        "is_me_message": false,
        "reactions": [],
        "recipient_id": 20,
        "rendered_content": "<p><span class=\"user-mention\" data-user-id=\"25\">@Outgoing webhook test</span> WyzePal is the world\u2019s most productive group chat!</p>",
        "sender_email": "iago@wyzepal.com",
        "sender_full_name": "Iago",
        "sender_id": 5,
        "sender_realm_str": "wyzepal",
        "stream_id": 5,
        "subject": "Verona2",
        "submessages": [],
        "timestamp": 1527876931,
        "topic_links": [],
        "type": "stream"
    },
    "token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0",
    "trigger": "mention"
}

Fields documentation

  • bot_email: string Email of the bot user.

  • data: string The message content, in raw Markdown format (not rendered to HTML).

  • trigger: string What aspect of the message triggered the outgoing webhook notification. Possible values include private_message and mention.

  • token: string A string of alphanumeric characters that can be used to authenticate the webhook request (each bot user uses a fixed token). You can get the token used by a given outgoing webhook bot in the wyzepalrc file downloaded when creating the bot.

  • message: object A dict containing details on the message that triggered the outgoing webhook, in the format used by GET /messages.

    • avatar_url: string The URL of the user's avatar. Can be null only if client_gravatar was passed, which means that the user has not uploaded an avatar in WyzePal, and the client should compute the gravatar URL by hashing the user's email address itself for this user.

    • client: string A WyzePal "client" string, describing what WyzePal client sent the message.

    • content: string The content/body of the message.

    • content_type: string The HTTP content_type for the message content. This will be text/html or text/x-markdown, depending on whether apply_markdown was set.

    • display_recipient: string | (object)[] Data on the recipient of the message; either the name of a stream or a dictionary containing basic data on the users who received the message.

    • id: integer The unique message ID. Messages should always be displayed sorted by ID.

    • is_me_message: boolean Whether the message is a [/me status message][status-messages]

    • reactions: (object)[] Data on any reactions to the message.

      • emoji_code: string A unique identifier, defining the specific emoji codepoint requested, within the namespace of the reaction_type.

        For example, for unicode_emoji, this will be an encoding of the Unicode codepoint.

      • emoji_name: string Name of the emoji.

      • reaction_type: string One of the following values:

        • unicode_emoji: Unicode emoji (emoji_code will be its Unicode codepoint).
        • realm_emoji: Custom emoji. (emoji_code will be its ID).
        • wyzepal_extra_emoji: Special emoji included with WyzePal. Exists to namespace the wyzepal emoji.
      • user_id: integer The ID of the user who added the reaction.

        Changes: New in WyzePal 3.0 (feature level 2). The user object is deprecated and will be removed in the future.

      • user: object Dictionary with data on the user who added the reaction, including the user ID as the id field. Note: In the events API, this user dictionary confusing had the user ID in a field called user_id instead. We recommend ignoring fields other than the user ID. Deprecated and to be removed in a future release once core clients have migrated to use the user_id field.

        • id: integer ID of the user.

        • email: string Email of the user.

        • full_name: string Full name of the user.

        • is_mirror_dummy: boolean Whether the user is a mirror dummy.

    • recipient_id: integer A unique ID for the set of users receiving the message (either a stream or group of users). Useful primarily for hashing.

    • sender_email: string The WyzePal display email address of the message's sender.

    • sender_full_name: string The full name of the message's sender.

    • sender_id: integer The user ID of the message's sender.

    • sender_realm_str: string A string identifier for the realm the sender is in. Unique only within the context of a given WyzePal server.

      E.g. on example.wyzepal.com, this will be example.

    • stream_id: integer Only present for stream messages; the ID of the stream.

    • subject: string The topic of the message. Currently always "" for private messages, though this could change if WyzePal adds support for topics in private message conversations.

      The field name is a legacy holdover from when topics were called "subjects" and will eventually change.

    • topic_links: (string)[] Data on any links to be included in the topic line (these are generated by [custom linkification filters][linkification-filters] that match content in the message's topic.)

      Changes: New in WyzePal 3.0 (feature level 1). Previously, this field was called subject_links; clients are recommended to rename subject_links to topic_links if present for compatibility with older WyzePal servers.

    • submessages: (string)[] Data used for certain experimental WyzePal integrations.

    • timestamp: integer The UNIX timestamp for when the message was sent, in UTC seconds.

    • type: string The type of the message: stream or private.

    • rendered_content: string The content/body of the message rendered in HTML.

Replying with a message

Many bots implemented using this outgoing webhook API will want to send a reply message into WyzePal. WyzePal's outgoing webhook API provides a convenient way to do that by simply returning an appropriate HTTP response to the WyzePal server.

A correctly implemented bot will return a JSON object containing one of two possible formats, described below.

Example response payloads

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.)

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 WyzePal!"
}

The content field should contain WyzePal-format markdown.

Note that an outgoing webhook bot can use the WyzePal REST API with its API key in case your bot needs to do something else, like add an emoji reaction or upload a file.

Slack-format webhook format

This interface translates WyzePal'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:

Name Description
token A string of alphanumeric characters you can use to authenticate the webhook request (each bot user uses a fixed token)
team_id String ID of the WyzePal organization
team_domain Domain of the WyzePal organization
channel_id Stream ID
channel_name Stream name
timestamp Timestamp for when message was sent
user_id ID of the user who sent the message
user_name Full name of sender
text The content of the message (in Markdown)
trigger_word Trigger method
service_id ID of the bot user

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

[('token', 'v9fpCdldZIej2bco3uoUvGp06PowKFOf'),
 ('team_id', 'wyzepal'),
 ('team_domain', 'wyzepal.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.