paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 04:52:12 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f317af2e1d07efa51f2ffa16cb8d7f1f4a7a1890
zulip/api_docs/non-webhook-integrations.md
David Rosa 3c0cb4c6a2 api-docs: Use start_tabs formatting and add "Related articles". 
- Updates API docs that have numbered instructions to use the
  `{start_tabs}` formatting we use in the help center.
- Cleans up formatting and revises documentation that shouldn't
  be formatted as a numbered instructions block.
- Cross-links related articles.

Fixes #28876.
2024-02-24 08:14:32 -08:00

2.4 KiB
Raw Blame History

Non-webhook integrations

Incoming webhook integrations are the fastest to write, but sometimes a third-party product just doesn't support them. Zulip supports several other types of integrations.

  • Python script integrations (examples: SVN, Git), where we can get the service to call our integration (by shelling out or otherwise), passing in the required data. Our preferred model for these is to ship these integrations in the Zulip Python API distribution, within the integrations directory there.

  • Plugin integrations (examples: Jenkins, Hubot, Trac) where the user needs to install a plugin into their existing software. These are often more work, but for some products are the only way to integrate with the product at all.

    For plugin integrations, usually you will need to consult the documentation for the third party software in order to learn how to write the integration.

  • Interactive bots. See Writing bots.

A few notes on how to do these:

  • You should always send messages by POSTing to URLs of the form https://zulip.example.com/v1/messages/.

  • We usually build Python script integrations with (at least) 2 files: zulip_foo_config.py containing the configuration for the integration including the bots' API keys, plus a script that reads from this configuration to actually do the work (that way, it's possible to update the script without breaking users' configurations).

  • Be sure to test your integration carefully and document how to install it.

  • You should specify a clear HTTP User-Agent for your integration. The user agent should at a minimum identify the integration and version number, separated by a slash. If possible, you should collect platform information and include that in ()s after the version number. Some examples of ideal UAs are:

    ZulipDesktop/0.7.0 (Ubuntu; 14.04)
ZulipJenkins/0.1.0 (Windows; 7.2)
ZulipMobile/0.5.4 (Android; 4.2; maguro)

  • The general advice for webhook integrations applies here as well.

Related articles