{"id":28855959,"url":"https://github.com/rasahq/helpdesk-assistant","last_synced_at":"2025-07-15T10:07:55.228Z","repository":{"id":41955246,"uuid":"234098947","full_name":"RasaHQ/helpdesk-assistant","owner":"RasaHQ","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-20T15:33:06.000Z","size":2698,"stargazers_count":191,"open_issues_count":17,"forks_count":154,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-06-20T00:09:43.921Z","etag":null,"topics":["bot","chatbot-example","conversation-driven-development","helpdesk","python","rasa","rasa-chatbot","rasa-starter-pack","servicenow-integration"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RasaHQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-15T14:32:07.000Z","updated_at":"2025-06-04T15:22:50.000Z","dependencies_parsed_at":"2024-11-16T02:31:23.192Z","dependency_job_id":"350787a3-b6b8-491f-827b-173fdc8d6cea","html_url":"https://github.com/RasaHQ/helpdesk-assistant","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RasaHQ/helpdesk-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RasaHQ%2Fhelpdesk-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RasaHQ%2Fhelpdesk-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RasaHQ%2Fhelpdesk-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RasaHQ%2Fhelpdesk-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RasaHQ","download_url":"https://codeload.github.com/RasaHQ/helpdesk-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RasaHQ%2Fhelpdesk-assistant/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265427411,"owners_count":23763313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","chatbot-example","conversation-driven-development","helpdesk","python","rasa","rasa-chatbot","rasa-starter-pack","servicenow-integration"],"created_at":"2025-06-20T00:09:43.314Z","updated_at":"2025-07-15T10:07:55.220Z","avatar_url":"https://github.com/RasaHQ.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rasa Helpdesk Assistant Example\n\nThis is a Rasa chatbot example demonstrating how to build an AI assistant for an IT Helpdesk. It includes an integration with the Service Now API to open incident reports and check on incident report statuses. Below is an example conversation, showing the bot helping a user open a support ticket and query its status. You can use this chatbot as a starting point for building customer service assistants or as a template for collecting required pieces of information from a user before making an API call.\n\nHere is an example of a conversation you can have with this bot:\n\n![Screenshot](./screenshots/demo_ss.png?raw=true)\n\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**\n\n- [Rasa Helpdesk Assistant Example](#rasa-helpdesk-assistant-example)\n  - [Setup](#setup)\n    - [Install the dependencies](#install-the-dependencies)\n    - [Optional: Connect to a ServiceNow instance](#optional-connect-to-a-servicenow-instance)\n  - [Running the bot](#running-the-bot)\n  - [Things you can ask the bot](#things-you-can-ask-the-bot)\n  - [Example conversations](#example-conversations)\n  - [Handoff](#handoff)\n    - [Try it out](#try-it-out)\n    - [How it works](#how-it-works)\n    - [Bot-side configuration](#bot-side-configuration)\n  - [Testing the bot](#testing-the-bot)\n  - [Rasa X Deployment](#rasa-x-deployment)\n    - [Action Server Image](#action-server-image)\n  - [Notes on Chatroom](#notes-on-chatroom)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Setup\n\n### Install the dependencies\n\nIn a Python3 virtual environment run:\n\n```bash\npip install -r requirements.txt\n```\n\nTo install development dependencies, run:\n\n```bash\npip install -r requirements-dev.txt\npre-commit install\n```\n\n\u003e With pre-commit installed, the `black` and `doctoc` hooks will run on every `git commit`.\n\u003e If any changes are made by the hooks, you will need to re-add changed files and re-commit your changes.\n\n### Optional: Connect to a ServiceNow instance\n\nYou can run this bot without connecting to a ServiceNow instance, in which case it will\nsend responses without creating an incident or checking the actual status of one.\nTo run the bot  without connecting ServiceNow,\nyou don't need to change anything in `actions/snow_credentials.yml`; `localmode` should already be set\nto `true`\n\nIf you do want to connect to ServiceNow, you can get your own free Developer instance\nto test this with [here](https://developer.servicenow.com/app.do#!/home)\n\nTo connect to your ServiceNow developer instance, configure the following in `actions/snow_credentials.yml`:\n\n- `snow_instance` - This is the address of the ServiceNow developer instance, you don't need the leading https.\n\n- `snow_user` - The username of the service account for the ServiceNow developer instance\n\n- `snow_pw` - The password of the service account for the ServiceNow developer instance\n\n- `localmode` -  Whether the action server should **not** try to reach out to a `snow_instance` based on the credentials in `actions/snow_credentials.yml`. When set to `True` (default in the code), it will just take all the data in and message out the information that would normally be sent.\n\n## Running the bot\n\nUse `rasa train` to train a model.\n\nThen, to run, first set up your action server in one terminal window:\n\n```bash\nrasa run actions\n```\n\nIn another window, run the duckling server (for entity extraction):\n\n```bash\ndocker run -p 8000:8000 rasa/duckling\n```\n\nThen to talk to the bot, run:\n\n```bash\nrasa shell --debug\n```\n\nNote that `--debug` mode will produce a lot of output meant to help you understand how the bot is working\nunder the hood. You can also add this flag to the action server command. To simply talk to the bot, you can remove this flag.\n\nYou can also try out the bot locally using Rasa X by running\n\n```bash\nrasa x\n```\n\nRefer to our guided workflow in the [Wiki page](https://github.com/RasaHQ/helpdesk-assistant/wiki/Using-Rasa-X-with-the-Helpdesk-Assistant) for how to get started with Rasa X in local mode.\n\n## Things you can ask the bot\n\nThe bot has two main skills:\n1. Opening an incident in ServiceNow.\n2. Checking the status of incidents in ServiceNow by email address of the caller. It will prompt the user to re-use previously provided (during the chat session) email addresses, if any exist.\nFor the purposes of illustration, the bot recognizes the following as requests to open an incident:\n\n1. Asking to open an incident directly e.g. \"I want to open an incident\"\n2. Asking about a problem resetting their password e.g. \"I can't reset my password\"\n3. Asking about a problem with outlook/email e.g. \"I can't log in to my outlook\"\n\nTake a look at `data/nlu.md` to see what the bot is currently trained to recognize.\n\nIt can also respond to requests for help (e.g. \"help me\").\n\nIf configured, the bot can also hand off to another bot in response to the user asking for handoff. More [details on handoff](#handoff) below.\n\n## Example conversations\n\nWith `localmode=true`:\n\n```\nBot loaded. Type a message and press enter (use '/stop' to exit):\nYour input -\u003e  hi\n    Hello!\n    I can help you open a service request ticket, or check the status of your open incidents.\n    You can ask me things like:\n    - Open an incident\n    - Help me reset my password\n    - I'm having a issue with my email\n    - What's the status of the ticket I opened?\nYour input -\u003e  i have a problem with my email\n    What is your email address?\nYour input -\u003e  anything@example.com\n    ? What is the priority of this issue?\nYour input -\u003e 1: low (/inform{\"priority\":\"low\"})\n    What is the problem description for the issue?\nYour input -\u003e  Can't log in to my email\n    ? Should I open an incident with the following details?\n    email: anything@example.com\n    problem description: Can't log in to my email\n    title: Problem with email\nYour input -\u003e priority: low  1: Yes (/affirm)\n    An incident with the following details would be opened if ServiceNow was connected:\n    email: anything@example.com\n    problem description: Can't log in to my email\n    title: Problem with email\n    priority: low\nYour input -\u003e  thanks. Can i check the status of my other tickets?\n    Would you like to use the last email address you used, anything@example.com?\nYour input -\u003e  Yes please\n    Since ServiceNow isn't connected, I'm making this up!\n    The most recent incident for anything@example.com is currently awaiting triage\n```\n\nWith `localmode=false`:\n\nWith a Service Now instance connected, it will check if the email address is in the instance database and provide an incident number for the final response:\n\n```\nYour input -\u003e  help me reset my password\n    What is your email address?\nYour input -\u003e  idontexist@example.com\n    Sorry, \"idontexist@example.com\" isn't in our incident management system. Please try again.\n    What is your email address?\nYour input -\u003e  abraham.lincoln@example.com\n    ? What is the priority of this issue?\nYour input -\u003e 3: high (/inform{\"priority\":\"high\"})\n    What is the problem description for the issue?\nYour input -\u003e  Password stuck in a loop\n    ? Should I open an incident with the following details?\n    email: abraham.lincoln@example.com\n    problem description: Password stuck in a loop\n    title: Problem resetting password\n    priority: high\nYour input -\u003e  1: Yes (/affirm)\n    Successfully opened up incident INC0010008 for you.  Someone will reach out soon.\nYour input -\u003e  Can I check the status of my tickets?\n    Would you like to use the last email address you used, abraham.lincoln@example.com?\nYour input -\u003e  Yes please\n    Incident INC0010002: \"Email Log in problem\", opened on 2020-05-21 09:57:06 is currently in progress\n    Incident INC0010008: \"Problem resetting password\", opened on 2020-05-21 12:12:49 is currently awaiting triage\nYour input -\u003e  thanks\n    You're welcome!\n```\n\n\n## Handoff\n\nThis bot includes a simple skill for handing off the conversation to another bot or a human.\nThis demo relies on [this fork of chatroom](https://github.com/RasaHQ/chatroom) to work, however you\ncould implement similar behaviour in another channel and then use that instead. See the chatroom README for\nmore details on channel-side configuration.\n\n\nUsing the default set up, the handoff skill enables this kind of conversation with two bots:\n\n\u003cimg src=\"./handoff.gif\" width=\"200\"\u003e\n\n### Try it out\n\nThe simplest way to use the handoff feature is to do the following:\n\n1. Clone [chatroom](https://github.com/RasaHQ/chatroom) and [Financial-Demo](https://github.com/RasaHQ/Financial-Demo) alongside this repo\n2. In the chatroom repo, install the dependencies:\n```bash\nyarn install\n```\n3. In the chatroom repo, build and serve chatroom:\n```bash\nyarn build\nyarn serve\n```\n4. In the Financial-Demo repo, install the dependencies and train a model (see the Financial-Demo README)\n5. In the Helpdesk-Assistant repo (i.e. this repo), run the rasa server and action server at the default ports (shown here for clarity)\n   In one terminal window:\n    ```bash\n    rasa run --enable-api --cors \"*\" --port 5005 --debug\n    ```\n    In another terminal window:\n    ```bash\n    rasa run actions --port 5055 --debug\n    ```\n6. In the Financial-Demo repo, run the rasa server and action server at **the non-default ports shown below**\n   In one terminal window:\n    ```bash\n    rasa run --enable-api --cors \"*\" --port 5006 --debug\n    ```\n    In another terminal window:\n    ```bash\n    rasa run actions --port 5056 --debug\n    ```\n7. Open `chatroom_handoff.html` in a browser to see handoff in action\n\n\n### How it works\n\nUsing chatroom, the general approach is as follows:\n\n1. User asks original bot for a handoff.\n2. The original bot handles the request and eventually\n   sends a message with the following custom json payload:\n    ```\n        {\n            \"handoff_host\": \"\u003curl of handoff host endpoint\u003e\",\n            \"title\": \"\u003ctitle for bot/channel handed off to\u003e\"\n            }\n    ```\n    This message is not displayed in the Chatroom window.\n3. Chatroom switches the host to the specified `handoff_host`\n4. The original bot no longer receives any messages.\n5. The handoff host receives the message `/handoff{\"from_host\":\"\u003coriginal bot url\"\u003e}`\n6. The handoff host should be configured to respond to this message with something like,\n   \"Hi, I'm \u003cso and so\u003e, how can I help you??\"\n7. The handoff host can send a message in the same format as specified above to hand back to the original bot.\n   In this case the same pattern repeats, but with\n   the roles reversed. It could also hand off to yet another bot/human.\n\n### Bot-side configuration\n\nThe \"try it out\" section doesn't require any further configuration; this section is for those\nwho want to change or further understand the set up.\n\nFor this demo, the user can ask for a human, but they'll be offered a bot (or bots) instead,\nso that the conversation looks like this:\n\n\nFor handoff to work, you need at least one \"handoff_host\". You can specify any number of handoff hosts in the file `actions/hanodff_config.yml`.\n```\nhandoff_hosts:\n    financial_demo:\n      title: \"Financial Demo\"\n      url: \"http://localhost:5006\"\n    ## you can add more handoff hosts to this list e.g.\n    # moodbot:\n    #   title: \"MoodBot\"\n    #   url: \"http://localhost:5007\"\n```\n\nHandoff hosts can be other locally running rasa bots, or anything that serves responses in the format that chatroom\naccepts. If a handoff host is not a rasa bot, you will of course want to update the response text to tell the user\nwho/what they are being handed off to.\n\nThe [Financial-Demo](https://github.com/RasaHQ/Financial-Demo) bot has been set up to handle handoff in exactly the same way as Helpdesk-Assistant,\nso the simplest way to see handoff in action is to clone Financial-Demo alongside this repo.\n\nIf you list other locally running bots as handoff hosts, make sure the ports on which the various rasa servers \u0026 action servers are running do not conflict with each other.\n\n\n## Testing the bot\n\nYou can test the bot on the test conversations by running  `rasa test`.\nThis will run [end-to-end testing](https://rasa.com/docs/rasa/user-guide/testing-your-assistant/#end-to-end-testing) on the conversations in `tests/conversation_tests.md`.\n\n## Rasa X Deployment\n\nTo [deploy helpdesk-assistant](https://rasa.com/docs/rasa/user-guide/how-to-deploy/), it is highly recommended to make use of the\n[one line deploy script](https://rasa.com/docs/rasa-x/installation-and-setup/one-line-deploy-script/) for Rasa X. As part of the deployment, you'll need to set up [git integration](https://rasa.com/docs/rasa-x/installation-and-setup/integrated-version-control/#connect-your-rasa-x-server-to-a-git-repository) to pull in your data and\nconfigurations, and build or pull an action server image.\n\n### Action Server Image\n\nYou will need to have docker installed in order to build the action server image. If you haven't made any changes to the action code, you can also use\nthe [public image on Dockerhub](https://hub.docker.com/r/rasa/helpdesk-assistant) instead of building it yourself.\n\n\nSee the Dockerfile for what is included in the action server image,\n\nTo build the image:\n\n```bash\ndocker build . -t \u003cname of your custom image\u003e:\u003ctag of your custom image\u003e\n```\n\nTo test the container locally, you can then run the action server container with:\n\n```bash\ndocker run -p 5055:5055 \u003cname of your custom image\u003e:\u003ctag of your custom image\u003e\n```\n\nOnce you have confirmed that the container works as it should, you can push the container image to a registry with `docker push`\n\nIt is recommended to use an[automated CI/CD process](https://rasa.com/docs/rasa/user-guide/setting-up-ci-cd) to keep your action server up to date in a production environment.\n\n## Notes on Chatroom\n\nIf you want to try the transfer to another bot feature, you'll need to use Chatroom.  As of this writing, the main Scalable Minds chatroom [project](https://github.com/scalableminds/chatroom) has not included this feature so you will need to build from a fork. The following docker commands will build an image from the adapted Chatroom and run it.\n\n```\ndocker build -t chatroom -f Dockerfile.chatroom .\ndocker run --name chatroom -p 8080:8080 -d chatroom\n```\n\nFrom the `docker-compose.yml` below, you can start chatroom with `docker-compose up -d`\n\nHere's an example docker-compose.yml for this image. Note that the initial Rasa endpoint URL is hard coded in `chatroom_handoff.html`; to use your locally running bot, point it to `http://localhost:5005`.\n\n```\nversion: \"3.4\"\n\nservices:\n  chatroom:\n    image: chatroom\n    build:\n      context: ./\n      dockerfile: Dockerfile.chatroom\n    ports:\n      - \"8080:8080\"\n    command: [ \"yarn\", \"serve\" ]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frasahq%2Fhelpdesk-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frasahq%2Fhelpdesk-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frasahq%2Fhelpdesk-assistant/lists"}