After building the integration service and admin interface, the next step is to deploy the channel so your support team can start using it.

Here are the steps for deploying the channel:

This is the final part of a project to build a channel from scratch:

Disclaimer: Zendesk provides this article for demonstration and instructional purposes only. The channel developed in the article should not be used in a production environment. Zendesk does not provide support for developing a channel. Please post any issue in the comments section below or search for a solution online.

Deploying the integration service on the web

You need to deploy your channel's integration service on the web to make it accessible to Zendesk. You can use any hosting service you like so long as it supports Python web apps. The tutorial describes how to use Heroku, a service that lets you host and run web applications in the cloud. If you don't already have a Heroku account, you can sign up for a free one.

You can skip this section if you have another hosting solution for Python web apps.

Deploying the integration service on Heroku consists of the following steps:

Most Heroku deployments are done with Git. Install Git if it's not already installed. If it is, update it to the latest version. To get Git, see Downloads on the Git website.

Getting access to Heroku

  1. Go to the Heroku sign up page to create an account.
  2. Install the Heroku CLI.

    See the install instructions on the Heroku website.

  3. At the command line, log in to Heroku:

    heroku login

    A page will open in your browser to log in to your account.

    If you prefer logging in at the command line, add the -i option to the command:

    heroku login -i

Creating an app instance on Heroku

  1. Open your command-line interface and log in to Heroku:

    heroku login

  2. Run the following command:

    heroku create community-channel-service

    This creates an app instance named community-channel-service. You can use any name you like. If others have found this tutorial helpful and made it this far, the name will probably already be taken. You can try another name of up to 30 characters, or you can omit the name and let Heroku generate a random name that you can change later. Example:

    heroku create

    You should get the following response:

    Creating ⬢ community-channel-service... donehttps://community-channel-service.herokuapp.com/ |https://git.heroku.com/community-channel-service-cn.git

    Jot down the new URL of your web app (the first URL in the example above).

  3. Replace the placeholder host names in the integration_manifest.json file in your integration service.

    Replace the host name placeholder in each URL with your new Heroku host name, which should look like 'community-channel-service.herokuapp.com' from the response you received in step 2.

    Your integration_manifest.json file should look like this:

    {  "name": "Community Channel",  "id": "my-community-channel-abc123",  "version": "1.0.0",  "urls": {    "admin_ui": "https://community-channel-service.herokuapp.com/channels/community/admin_ui",    "pull_url": "https://community-channel-service.herokuapp.com/channels/community/pull",    "channelback_url": "https://community-channel-service.herokuapp.com/channels/community/channelback"  }}

Setting up deploys

Deploying your integration service to the web consists of pushing the files from a local Git repo to a remote Git repo on Heroku. This section describes how to set up the local and remote repos.

If you're using a virtual environment, you might want to create a .gitignore file in the root folder to exclude your venv folder.

  1. In your command-line interface, navigate to the local folder that contains your integration service files.
  2. Run the following three commands sequentially to create a local Git repository and add your files to it:

    git init

    git add .

    git commit -m "initial commit"

  3. Make sure you're logged in to Heroku, then run the following command to set your Heroku app instance as a remote repo for your local repo:

    heroku git:remote -a your-app-name

    Change "your-app-name" to the name of the app you specified in Creating the app on Heroku. In this tutorial, the app name is "community-channel-service".

  4. To verify you set the remote repo successfully, run:

    git remote -v

Configuring the integration service for deployment

To deploy to Heroku, you must include the following configuration files in the project's root folder:

  • Procfile
  • runtime.txt
  • requirements.txt
  • In a text editor, create a file named Procfile in your project's root folder and make sure it contains the following line:

    web: python service.py

    The Procfile specifies the app's process type (web) and the command to start the process (python service.py).

  • Create a file named runtime.txt in the project's root folder and make sure it contains the following line, adjusted for your version number:

    python-3.7.8

    The runtime.txt file tells Heroku what Python version to use for your app. The setting ensures Heroku runs your app in the same runtime environment you used locally to develop and test the app.

    See Python support on the Heroku website for currently supported runtimes.

    The Python app in this tutorial should run on Python 3.7.x or later.

  • Create a file named requirements.txt in the project's root folder and make sure it lists the following libraries:

    bottle==0.12.18requests==2.24.0arrow==0.15.7

    The file lists the libraries Heroku needs to install to run the app. Update the version number of each library to the version you're using. To find out the version, run the following commands:

    pip3 show bottle

    pip3 show requests

    pip3 show arrow

  • Add the new config files to your local repo:

    git add .

    git commit -a -m "Add config files"

Deploying the integration service

In this step, you deploy the app to Heroku for the first time.

  1. If not already done, log in to Heroku:

    heroku login

  2. Deploy the app:

    git push heroku master

    The command uploads the app files to the remote git repository on Heroku. Heroku then builds and deploys the app.

    Important: Make sure to commit all changes before pushing to Heroku. You can run git status to check.

  3. Enter the following command to set an APP_LOCATION environment variable in Heroku:

    heroku config:set APP_LOCATION=heroku

    This is a one-time-only requirement. The code in service.py has two different run statements: one for the local server and one for the Heroku server. At runtime, the app checks for the APP_LOCATION environment variable to decide which one to run:

    if os.environ.get('APP_LOCATION') == 'heroku':    run(host="0.0.0.0", port=int(os.environ.get("PORT", 5000)))else:    run(debug=True)
  4. Test your service's endpoints using cURL or Postman.

If something goes wrong, go back to your command-line interface and enter heroku logs --tail. Check the entries for clues of what went wrong.

Pushing updates to the integration service

Inevitably you'll need to fix bugs and redeploy the service. Test your changes locally before pushing the changes to Heroku as described next.

To push updates to Heroku

  1. In your command-line interface, navigate to your app folder.
  2. Commit all the changes in Git:

    git commit -a -m "Various updates"

  3. If not already done, log in to Heroku:

    heroku login

  4. Push the files:

    git push heroku master

  5. Re-test the service's endpoints using cURL or Postman.

Creating a channel installer

You install your new channel in a Zendesk Support account with a Zendesk app.

To create the channel installer

  1. Create a folder called installer in the same folder as your service.py file.
  2. Open your command-line interface (the command prompt in Windows or Terminal on the Mac) and navigate to the installer folder.

    Tip: On a Mac, you can right-click the folder in Finder and select Services > New Terminal at Folder.

  3. Run the following command at the prompt:

    zat new

  4. When prompted, enter the following information:

    • author's name - your name
    • author's email - your email
    • author's url - your website url if you have one, or press Enter to leave it blank
    • app name - Community Channel Installer
    • iFrame URI - Press Enter to leave it to the default
    • directory name - Press Enter to create the files in the installer folder.

    After you're done, the tool creates the required files for a new app.

    The properties of the app are recorded in a file named manifest.json, which should not be confused with the channel's integration_manifest.json file. By default the manifest.json file defines a sidebar app in Support. However, the only job your app has is to create a channel in a Zendesk Support instance. This kind of app is known as a requirements-only app. It doesn't display anything or do anything else. You'll change this in the next step.

  5. Open the manifest.json file in the installer folder (not the channel's integration_manifest.json file in your project folder) and make the following changes:

    • Add "requirementsOnly": true to the manifest properties
    • Add "singleInstall": true to the manifest properties
    • Delete the "locations" property
    • Delete the "frameworkVersion" property

    The updated manifest file should look like this:

    {  "name": "Community Channel Installer",  "requirementsOnly": true,  "singleInstall": true,  "author": {    "name": "J Doe",    "email": "[email protected]",    "url": ""  },  "defaultLocale": "en",  "private": true,  "version": "1.0"}
  6. Create a file named requirements.json with the other app files in the installer folder.
  7. Add the following JSON object to the requirements.json file and save it:

    {  "channel_integrations": {    "my-community-channel-abc123": {      "manifest_url": "https://{host_name}/channels/community/manifest"    }  }}

    Specify the id in your channel manifest.json file as the name of the integration. In this tutorial, the id is "my-community-channel-abc123".

    Replace {host_name} with the host name of your deployed service. In this tutorial, the host name is "community-channel-service.herokuapp.com".

  8. Run zat validate on the command line to make sure everything checks out.
  9. Run zat package to package your files for upload.

    ZAT will create a ZIP file containing your app in a subfolder named tmp.

Note: You don't have to host these files with your integration service on the web. If you're using a .gitignore file for your local repo, you can add the installer folder to it:

installer/

Installing and testing the channel in Support

  1. Sign in as an admin in your Zendesk Support instance, go to Admin > Apps > Manage, then follow the instructions to upload and install a private app. For details, see Uploading and installing your private app in Zendesk Support.

    Make sure your channel installer app is enabled in the account.

  2. In Zendesk Support, go to Admin > Channels > Channel Integrations, and select your channel integration from the list.

    If you don't see your integration, make sure the channel installer app is enabled in the account.

  3. Click the Accounts tab, then click the Add Account button.

    Zendesk displays your admin interface:

  4. Enter an id for a community topic and click Save.

    Your channel is activated.

  5. Test the channel.

    See Understanding the user experience in part 1 of the project.

    Check the Heroku logs for issues. In your command-line interface, enter heroku logs --tail. Check the entries for clues of what went wrong. Add logging statements in the Python files to diagnose problems. See https://docs.python.org/3/howto/logging.html.

    Create posts in the community.

    Wait a few minutes for Zendesk to make its first pull request and verify that corresponding tickets are created in Support.

    Add a comment to a ticket and verify that the comment is added to the corresponding community post.

    Verify that subsequent pull requests pull only new posts.

In this tutorial, you deployed a community channel for Zendesk Support. You can keep tweaking and making enhancements to the channel if you like. For example, you could track more than one community topic.