Building a marketplace bot

Becoming a Zendesk Technology Partner

As an official Zendesk Technology Partner, you will be able to offer an OAuth flow in your application allowing your customers to provision you with access to their Zendesk messaging data. The first step in becoming a partner is to list your app, integration, or bot on the Zendesk Marketplace. See Publishing your bot on the Zendesk Marketplace for more information on the steps required.

Implementing the OAuth flow

Once accepted as a Zendesk Technology Partner, you will be provisioned with a client_id and client_secret which you can use to implement an OAuth flow allowing your customers to grant you limited access to their Zendesk account's messaging data. The content below assumes that you are already familiar with the OAuth 2.0 standard. To learn more, see the OAuth getting started guide.

Note: Marketplace bots are specifically granted access to messaging data with the Sunshine Conversations API. If you're building an integration that requires access to non-messaging data like tickets, see Using OAuth authentication with your application instead.

Initiating the OAuth flow

To begin the OAuth flow, redirect the customer's browser to the following URL:

https://oauth-bridge.zendesk.com/sc/oauth/authorize?response_type=code&client_id={client_id}

The customer will need to select their Zendesk subdomain and accept the prompt to grant access to their data. For more options and details, such as how to specify a custom state parameter or redirect url, see Authorize in the API reference.

Redirect and acquiring an OAuth token

Once authorized, the browser will be redirected to one of your OAuth client's configured redirect URLs, including a code query parameter. Use the Get Token API to exchange the code for a bearer token. You will also need to supply the client_id and client_secret provided to you after the Request OAuth credentials for your bot step of your Zendesk Markeplace bot listing has been submitted and processed.

curl https://oauth-bridge.zendesk.com/sc/oauth/token \
    -X POST \
    -H 'content-type: application/json' \
    -d '{
        "grant_type": "authorization_code",
        "code": "{code}",
        "client_id": "{client_id}",
        "client_secret": "{client_secret}"
    }'

The response to this call will include your bearer token (in the form of an integration-scoped JWT), which can be used to call the API. For more information on how to use this JWT, see API authentication.

Sample app

As a demonstration of a working OAuth flow, we've built a simple sample app called Shoplifter. You can try it out on the Shoplifter demo site.

Once you've run through the demo, take a look at the Shoplifter source code to see how it works under the hood.

Token info

After you've acquired a bearer token, the Get Token Info endpoint can be used to retrieve information about the app where the new integration was created:

curl https://oauth-bridge.zendesk.com/sc/v2/tokenInfo \
    -X GET \
    -H 'content-type: application/json' \
    -H 'authorization: Bearer {token}'

Take note of the returned app's id, which will be needed for most calls your integration will be making. If a subdomain property is returned, you should also use this for future API calls (see regions for more information).

Webhook setup

Using the app id and subdomain obtained from the token info endpoint, you can now create webhooks to subscribe for incoming events as explained in receiving messages. Use the Create Webhook API endpoint to subscribe to the desired set of triggers, supplying the special me alias for the required integrationId path parameter:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{appId}/integrations/me/webhooks \
    -X POST \
    -H 'content-type: application/json' \
    -H 'authorization: Bearer {token}' \
    -d '{
        "target": "http://example.com/callback",
        "triggers": ["conversation:message"]
    }'

As an OAuth integration, you can create up to 3 such webhooks. Typically, only one should be necessary. You can check what is already configured for your integration using the List Webhooks API.

Revoking access

To uninstall your integration and revoke your bearer token, use the Revoke Access API:

curl https://{subdomain}.zendesk.com/sc/oauth/authorization \
    -X DELETE
    -H 'content-type: application/json' \
    -H 'authorization: Bearer {token}'

This action will also remove any previously configured webhooks for your integration.

Integration removed callback

When registering as a Zendesk Technology Partner, a remove URL can be supplied as part of the process, which will be used to notify your backend whenever one of your integrations is uninstalled. This can be a result of your customer uninstalling the integration manually from within Zendesk, or when you invoke the revoke access API yourself. Zendesk will send a POST request to the configured URL including the appId and integrationId of the now-deleted integration in the request body:

{
    "appId": "{appId}",
    "integrationId": "{integrationId}"
}

You can use this callback to perform any required cleanup on your end.

Warning: Zendesk does not supply any authentication when invoking the remove URL for your OAuth client. To be sure the request is legitimate, you can use the token info endpoint to confirm that your bearer token has indeed been revoked.

Next steps

• Now that you can request bearer tokens from your customers and make API calls on their behalf, see receiving messages and sending messages for more details on how to build the rest of your integration.