- First, create the stream you'd like to use for Desk.com notifications,
- and subscribe all interested parties to this stream. We recommend the
- stream name desk. Keep in mind you still need to
- create the stream first even if you are using this recommendation.
-
- Next, in Desk.com, open your Admin view via the top-left corner - dropdown. In the Admin view, click on Apps, then click Install under - "Custom Action": -
-
-
-- From there, click "Install Custom Action" and accept the terms. Fill - in the form like this: -
-{{ external_api_uri_subdomain }}/v1/external/deskdotcomdesk-bot@yourdomain.com
-
-- Click Create to save your settings. From the next screen, click Add - Action add a new action. You'll do this for every action you want a - notification on Zulip for. (To add another action later, look for your - custom action on the Apps page under "Installed Apps." -
- -
-
-- Let's say you want a notification each time a case is updated. Put - in a descriptive name like "Announce case update", select "POST a string to a URL" - for Action Type, and copy-paste this to the "Appended URL path": -
-{% raw %} -?stream=desk&topic={{ case.id }}:+{{ case.subject }}
- The "appended URL path" will be the same for every notification — - it makes sure the notification goes to the appropriate stream and topic - within Zulip. -
- -- Next, copy this template Zulip message into "Message to - POST": -
-{% raw %} -
-Case [{{ case.id }}, {{ case.subject }}]({{ case.direct_url }}), was updated.
-
-* Status: {{ case.status.name }}
-* Priority: {{ case.priority }}
-* Customer: {{ customer.name }}
-* Company: {{ customer.company }}
-* Description: {{ case.description }}
-
-
- You don't need to edit that, although you may if you wish. All
- the funny-looking stuff inside {{ and }}
- will be filled in by Desk.com for each event. The dialog should look
- like this:
-
-
-- Click Add Action to save, and then on the next screen click the slider - next to the action to enable it. This is important — actions are turned off - by default! -
- -
-
-- Now you need to create a rule that triggers this action. Desk.com's - support center has a - lengthy - article on rules, but in short, click on "Cases" up at the top, - "Rules" on the left side, and then the specific event you want to notify - on — in our example, "Inbound Interaction". -
- -
-
-- Select the types of interaction you want your rule to apply to, - such as Chat. Specify the name and click on "Add Rule." -
- -
-
-- In the next screen, provide the details. First, click Add Actions to - display the rule actions. Select "Trigger an App Action" in the dropdown, and - then the name of the custom action you created earlier when the second - dropdown appears. You can add additional "All" or "Any" conditions if desired. - Also select when the rule should run (if not "Anytime") and enable it. -
- -
-
-Finally, click Update.
- -
- Congratulations! You're done!
When a case is updated,
- you'll see a notification like the following, to the stream
- desk, with a topic that matches the case's subject name:
-
diff --git a/zerver/webhooks/deskdotcom/doc.md b/zerver/webhooks/deskdotcom/doc.md
new file mode 100644
index 0000000000..53789944c3
--- /dev/null
+++ b/zerver/webhooks/deskdotcom/doc.md
@@ -0,0 +1,105 @@
+{!create-stream.md!}
+
+Keep in mind you still need to create the stream first even
+if you are using this recommendation.
+
+Next, on your {{ settings_html|safe }}, create a bot and
+note its email and API key.
+
+Next, in Desk.com, open your **Admin** view via the top-left
+corner dropdown. In the **Admin** view, click on **Apps**, then
+click **Install** under **Custom Action**:
+
+
+
+From there, click **Install Custom Action** and accept the terms.
+Fill in the form like this:
+
+* **Name**: Zulip
+* **Authentication Method**: Basic Auth
+* **URL**: `{{ external_api_uri_subdomain }}/v1/external/deskdotcom`
+* **User name**: *your bot's user name, e.g.* `desk-bot@yourdomain.com`
+* **Password**: *your bot's API key*
+
+
+
+Click **Create** to save your settings. From the next screen, click
+**Add Action** to add a new action. You'll do this for every action
+you want a notification on Zulip for. (To add another action later,
+look for your custom action on the **Apps** page under
+**Installed Apps.**
+
+
+
+Let's say you want a notification each time a case is updated. Put
+in a descriptive name like **Announce case update**, select
+**POST a string to a URL** for **Action Type**, and copy-paste this
+to the **Appended URL path**:
+
+{% raw %}
+`?stream=desk&topic={{ case.id }}:+{{ case.subject }}`
+{% endraw %}
+
+The "appended URL path" will be the same for every notification —
+it makes sure the notification goes to the appropriate stream and topic
+within Zulip.
+
+Next, copy this template Zulip message into **Message to POST**:
+
+{% raw %}
+```
+Case [{{ case.id }}, {{ case.subject }}]({{ case.direct_url }}), was updated.
+
+* Status: {{ case.status.name }}
+* Priority: {{ case.priority }}
+* Customer: {{ customer.name }}
+* Company: {{ customer.company }}
+* Description: {{ case.description }}
+```
+{% endraw %}
+
+You don't need to edit that, although you may if you wish. All
+the funny-looking stuff inside {% raw %}`{{` and `}}`{% endraw %}
+will be filled in by Desk.com for each event. The dialog should
+look like this:
+
+
+
+Click **Add Action** to save, and then on the next screen, click the
+slider next to the action to enable it. This is important — actions are
+turned off by default!
+
+
+
+Now you need to create a rule that triggers this action. Desk.com's
+support center has a [lengthy article on rules][1], but in short,
+click on **Cases** up at the top, **Rules** on the left side, and
+then the specific event you want to notify on — in our example,
+**Inbound Interaction**.
+
+[1]: https://support.desk.com/customer/portal/articles/1376
+
+
+
+Select the types of interaction you want your rule to apply to,
+such as **Chat**. Specify the name and click on **Add Rule**.
+
+
+
+In the next screen, provide the details. First, click **Add Actions**
+to display the rule actions. Select **Trigger an App Action** in the
+dropdown, and then the name of the custom action you created earlier
+when the second dropdown appears. You can add additional **All** or
+**Any** conditions if desired. Also select when the rule should run
+(if not **Anytime**) and enable it.
+
+
+
+Finally, click **Update**.
+
+{!congrats.md!}
+
+
+
+When a case is updated, you'll see a notification like the one above,
+to the stream `desk`, with a topic that matches the case's subject name.