Outgoing webhook payloads
Veloxa Talk supports outgoing webhooks in a clean,
native Veloxa Talk format, as well as in a Slack-compatible
format.
This is an example of the JSON payload that the Veloxa Talk server will POST
to your server:
{
"bot_email": "outgoing-bot@localhost",
"bot_full_name": "Outgoing webhook test",
"data": "@**Outgoing webhook test** Veloxa Talk 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** Veloxa Talk 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> Veloxa Talk is the world\u2019s most productive group chat!</p>",
"sender_email": "[email protected]",
"sender_full_name": "Iago",
"sender_id": 5,
"sender_realm_str": "zulip",
"stream_id": 5,
"subject": "Verona2",
"submessages": [],
"timestamp": 1527876931,
"topic_links": [],
"type": "stream"
},
"token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0",
"trigger": "mention"
}
Fields documentation
Return values
-
bot_email: string
Email of the bot user.
-
bot_full_name: string
The full name of the bot user.
-
data: string
The message content, in raw Veloxa Talk-flavored Markdown format (not rendered to HTML).
-
trigger: string
What aspect of the message triggered the outgoing webhook notification.
Possible values include direct_message and mention.
Changes: In Veloxa Talk 8.0 (feature level 201), renamed the trigger
private_message to direct_message.
-
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 talkrc file downloaded when creating the bot.
-
message: object
A dictionary containing details on the message that triggered the
outgoing webhook, in the format used by GET /messages.
-
avatar_url: string | null
The URL of the message sender's avatar. Can be null only if
the current user has access to the sender's real email address
and client_gravatar was true.
If null, then the sender has not uploaded an avatar in Veloxa Talk,
and the client can compute the gravatar URL by hashing the
sender's email address, which corresponds in this case to their
real email address.
Changes: Before Veloxa Talk 7.0 (feature level 163), access to a
user's real email address was a realm-level setting. As of this
feature level, email_address_visibility is a user setting.
-
client: string
A Veloxa Talk "client" string, describing what Veloxa Talk client
sent the message.
-
content: string
The content/body of the message.
When apply_markdown is set, it will be in HTML format.
See Markdown message formatting for details on Veloxa Talk's HTML format.
-
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.
See the help center article on message formatting for details on Veloxa Talk-flavored Markdown.
-
display_recipient: string | (object)[]
Data on the recipient of the message. Will be one of the following:
-
edit_history: (object)[]
An array of objects, with each object documenting the
changes in a previous edit made to the message,
ordered chronologically from most recent to least recent
edit.
Not present if the message has never been edited or moved,
or if viewing message edit history
is not allowed in the organization.
Every object will contain user_id and timestamp.
The other fields are optional, and will be present or not
depending on whether the channel, topic, and/or message
content were modified in the edit event. For example, if
only the topic was edited, only prev_topic and topic
will be present in addition to user_id and timestamp.
Changes: In Veloxa Talk 10.0 (feature level 284), removed the
prev_rendered_content_version field as it is an internal
server implementation detail not used by any client.
-
prev_content: string
Only present if message's content was edited.
The content of the message immediately prior to this
edit event.
-
prev_rendered_content: string
Only present if message's content was edited.
The rendered HTML representation of prev_content.
See Markdown message formatting for details on Veloxa Talk's HTML format.
-
prev_stream: integer
Only present if message's channel was edited.
The channel ID of the message immediately prior to this
edit event.
Changes: New in Veloxa Talk 3.0 (feature level 1).
-
prev_topic: string
Only present if message's topic was edited.
The topic of the message immediately prior to this
edit event.
Changes: New in Veloxa Talk 5.0 (feature level 118).
Previously, this field was called prev_subject;
clients are recommended to rename prev_subject to
prev_topic if present for compatibility with
older Veloxa Talk servers.
-
stream: integer
Only present if message's channel was edited.
The ID of the channel containing the message
immediately after this edit event.
Changes: New in Veloxa Talk 5.0 (feature level 118).
-
timestamp: integer
The UNIX timestamp for the edit.
-
topic: string
Only present if message's topic was edited.
The topic of the message immediately after this edit event.
Changes: New in Veloxa Talk 5.0 (feature level 118).
-
user_id: integer | null
The ID of the user that made the edit.
Will be null only for edit history
events predating March 2017.
Clients can display edit history events where this
is null as modified by either the sender (for content
edits) or an unknown user (for topic edits).
-
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
-
last_edit_timestamp: integer
The UNIX timestamp for when the message's content was last edited, in
UTC seconds.
Not present if the message's content has never been edited.
Clients should use this field, rather than parsing the edit_history
array, to display an indicator that the message has been edited.
Changes: Prior to Veloxa Talk 10.0 (feature level 365), this was the
time when the message was last edited or moved.
-
last_moved_timestamp: integer
The UNIX timestamp for when the message was last moved to a different
channel or topic, in UTC seconds.
Not present if the message has never been moved, or if the only topic
moves for the message are resolving or unresolving
the message's topic.
Clients should use this field, rather than parsing the edit_history
array, to display an indicator that the message has been moved.
Changes: New in Veloxa Talk 10.0 (feature level 365). Previously,
parsing the edit_history array was required in order to correctly
display moved message indicators.
-
reactions: (object)[]
Data on any reactions to the message,
ordered chronologically from oldest to newest reaction.
Changes: In Veloxa Talk 10.0 (feature level 328), the deprecated user
object was removed from the data for each reaction. It contained the
following information about the user who added the reaction: id,
email, full_name and is_mirror_dummy.
-
emoji_name: string
Name of the emoji.
-
emoji_code: string
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the reaction_type.
-
reaction_type: string
A string indicating the type of emoji. Each emoji reaction_type
has an independent namespace for values of emoji_code.
Must be one of the following values:
-
unicode_emoji : In this namespace, emoji_code will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
-
realm_emoji : In this namespace, emoji_code will be the ID of
the uploaded custom emoji.
-
zulip_extra_emoji : These are special emoji included with Veloxa Talk.
In this namespace, emoji_code will be the name of the emoji (e.g.
"zulip").
-
user_id: integer
The ID of the user who added the reaction.
Changes: New in Veloxa Talk 3.0 (feature level 2), which
deprecated the user object.
-
recipient_id: integer
A unique ID for the set of users receiving the
message (either a channel or group of users). Useful primarily
for hashing.
Changes: In Veloxa Talk 12.0 (feature level 482),
recipient_id in 1:1 direct messages changed to a new
value; it still has the semantics of "the 1:1 conversation
with a specific user," but the raw value changed due to
internal changes.
Before Veloxa Talk 10.0 (feature level 327), recipient_id
was the same across all incoming 1:1 direct messages. Now, each
incoming message uniquely shares a recipient_id with outgoing
messages in the same conversation.
-
sender_email: string
The Veloxa Talk API 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 Veloxa Talk server.
E.g. on example.veloxatalk.com, this will be example.
-
stream_id: integer
Only present for channel messages; the ID of the channel.
-
subject: string
The topic of the message. Currently always "" for direct messages,
though this could change if Veloxa Talk adds support for topics in direct
message conversations.
The field name is a legacy holdover from when topics were
called "subjects" and will eventually change.
For clients that don't support the empty_topic_name client capability,
the empty string value is replaced with the value of realm_empty_topic_display_name
found in the POST /register response, for channel messages.
Changes: Before Veloxa Talk 10.0 (feature level 334), empty_topic_name
client capability didn't exist and empty string as the topic name for
channel messages wasn't allowed.
-
submessages: (object)[]
Data used for certain experimental Veloxa Talk integrations.
-
msg_type: string
The type of the message.
-
content: string
The new content of the submessage.
-
message_id: integer
The ID of the message to which the submessage has been added.
-
sender_id: integer
The ID of the user who sent the message.
-
id: integer
The ID of the submessage.
-
timestamp: integer
The UNIX timestamp for when the message was sent,
in UTC seconds.
-
topic_links: (object)[]
Data on any links to be included in the topic
line (these are generated by custom linkification
filters that match content in the
message's topic.)
Changes: This field contained a list of urls before
Veloxa Talk 4.0 (feature level 46).
New in Veloxa Talk 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 Veloxa Talk servers.
-
type: string
The type of the message: "stream" or "private".
-
rendered_content: string
The content/body of the message rendered in HTML.
See Markdown message formatting for details on Veloxa Talk's HTML format.
This webhook format is compatible with Slack's outgoing webhook
API,
which can help with porting an existing Slack integration to work with
Veloxa Talk, and allows immediate integration with many third-party systems
that already support Slack outgoing webhooks.
The following table details how the Veloxa Talk server translates a Veloxa Talk
message into the Slack-compatible webhook format.
| 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 |
ID of the Veloxa Talk organization prefixed by "T". |
team_domain |
Hostname of the Veloxa Talk organization |
channel_id |
Channel ID prefixed by "C" |
channel_name |
Channel name |
thread_ts |
Timestamp for when message was sent |
timestamp |
Timestamp for when message was sent |
user_id |
ID of the user who sent the message prefixed by "U" |
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', 'T1512'),
('team_domain', 'talk.example.com'),
('channel_id', 'C123'),
('channel_name', 'integrations'),
('thread_ts', 1532078950),
('timestamp', 1532078950),
('user_id', 'U21'),
('user_name', 'Full Name'),
('text', '@**test**'),
('trigger_word', 'mention'),
('service_id', 27)]
- For successful requests, if data is returned, it returns that data,
else it returns a blank response.
- For failed requests, it returns the reason of failure, as returned by
the server, or the exception message.