zulip/zerver/webhooks/deskdotcom/doc.html

<p>
    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 <code>desk</code>. Keep in mind you still need to
    create the stream first even if you are using this recommendation.
</p>

<p>
    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":
</p>
<img src="/static/images/integrations/desk/001.png"/>

<p>
    From there, click "Install Custom Action" and accept the terms. Fill
    in the form like this:
</p>
<ul>
    <li><b>Name</b>: Zulip</li>
    <li><b>Authentication Method</b>: Basic Auth</li>
    <li><b>URL</b>: <code>{{ external_api_uri_subdomain }}/v1/external/deskdotcom</code></li>
    <li><b>User name</b>: <em>your bot's user name, e.g.</em> <code>desk-bot@yourdomain.com</code></li>
    <li><b>Password</b>: <em>your bot's API key</em></li>
</ul>

<img src="/static/images/integrations/desk/002.png"/>

<p>
    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."
</p>

<img src="/static/images/integrations/desk/003.png"/>

<p>
    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":
</p>
{% raw %}
    <p><code>?stream=desk&amp;topic={{ case.id }}:+{{ case.subject }}</code></p>
{% endraw %}
<p>
    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.
</p>

<p>
    Next, copy this template Zulip message into "Message to
    POST":
</p>
{% raw %}
    <pre>
<code>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 }}
</code></pre>
    <p>
        You don't need to edit that, although you may if you wish. All
        the funny-looking stuff inside <code>{{</code> and <code>}}</code>
        will be filled in by Desk.com for each event. The dialog should look
        like this:
    </p>
{% endraw %}

<img src="/static/images/integrations/desk/004.png"/>

<p>
    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!
</p>

<img src="/static/images/integrations/desk/005.png"/>

<p>
    Now you need to create a rule that triggers this action. Desk.com's
    support center has a
    <a href="https://support.desk.com/customer/portal/articles/1376">lengthy
        article on rules</a>, 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".
</p>

<img src="/static/images/integrations/desk/006.png"/>

<p>
    Select the types of interaction you want your rule to apply to,
    such as Chat. Specify the name and click on "Add Rule."
</p>

<img src="/static/images/integrations/desk/007.png"/>

<p>
    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.
</p>

<img src="/static/images/integrations/desk/008.png"/>

<p>Finally, click Update.</p>

<p>
    <b>Congratulations! You're done!</b><br/> When a case is updated,
    you'll see a notification like the following, to the stream
    <code>desk</code>, with a topic that matches the case's subject name:
</p>

<img class="screenshot" src="/static/images/integrations/desk/009.png"/>