{"id":13764614,"url":"https://github.com/akalsey/zbot","last_synced_at":"2026-01-19T01:06:37.730Z","repository":{"id":136714875,"uuid":"76758356","full_name":"akalsey/zbot","owner":"akalsey","description":"Play Zork or other Interactive Fiction games over SMS with Tropo or in Cisco Spark rooms.","archived":false,"fork":false,"pushed_at":"2017-12-16T00:53:08.000Z","size":4804,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-10T19:36:11.436Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akalsey.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}},"created_at":"2016-12-18T02:22:01.000Z","updated_at":"2017-10-02T04:19:54.000Z","dependencies_parsed_at":"2023-07-03T09:00:21.773Z","dependency_job_id":null,"html_url":"https://github.com/akalsey/zbot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/akalsey/zbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akalsey%2Fzbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akalsey%2Fzbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akalsey%2Fzbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akalsey%2Fzbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akalsey","download_url":"https://codeload.github.com/akalsey/zbot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akalsey%2Fzbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28556066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T00:46:33.223Z","status":"ssl_error","status_checked_at":"2026-01-19T00:46:32.754Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-08-03T16:00:23.950Z","updated_at":"2026-01-19T01:06:37.702Z","avatar_url":"https://github.com/akalsey.png","language":"JavaScript","funding_links":[],"categories":["Code samples"],"sub_categories":["Bot samples"],"readme":"# zbot - To the south is a readme\n\nPlay Zork or other Interactive Fiction games over SMS with Tropo or in Cisco Spark\nrooms. Released under the MIT License. See LICENSE for details.\n\nThis bot can play any zcode encoded interactive fiction games, including the\npopular Zork.\n\n## Spark Room\n\n*You're in a [Cisco Spark](https://ciscospark.com) Room. There's a bot here that\nplays text adventure games. The game that's installed right now is Zork I.*\n\nAdd the bot to your own rooms by adding textadventure@sparkbot.io to your Spark\nroom.\n\nYou can also start a direct conversation with the bot by sending a Spark message\nto textadventure@sparkbot.io.\n\n## SMS Conversation\n\n*You're in an SMS client. There's a phone number here.*\n\nIf you're in the US or Canada, you can send a text message to +1-844-373-9675 to\nplay Zork over SMS, powered by [Tropo](https://www.tropo.com). Outside the US,\ntry +1-541-936-9675, but this has a lower capacity and may not work as well during\nbusy times.\n\nIn either case, your carrier's normal text or data rates apply.\n\n## Configuring your own\n\nFirst, [create a bot on Cisco Spark](https://developer.ciscospark.com/bots.html) and note\nthe bot's Access Token.\n\n### Starting the app, the easy way\n\n*There are two Containers here.*\n\nThe zbot has a Dockerfile and uses docker-compose to config and deploy docker\ncontainers with all of the required components. If you're not using Docker, find\n*Starting the app, the hard way* later on in this document for details on how to\nstart the application and components.\n\nThe zbot-api container relies on two Docker Volumes for storing saved games and\nthe zcode that makes up each game. Create a Volume called `zsaves` and a Volume\ncalled zcode:\n\n```\ndocker volume create --name zsaves\ndocker volume create --name zcode\n```\n\nCopy a zcode file (see *Where are the games?*) into the `zcode` volume.\n\nCopy `docker-compose.yml.example` to `docker-compose.yml`. Change the access token\nin `CISCOSPARK_ACCESS_TOKEN=YOUR-BOT-ACCESS-TOKEN` to your own access token. By\ndefault, zbot tries to start a zcode file called *zork.z5*. If you've installed\na different game, change `DEFAULT_GAME=Zork` to your game file, without the .z5\nfile extension.\n\nThen run\n\n```\ndocker-compose up -d\n```\n\nYou'll have the bot's web services running on port 3000.\n\n### Setting up Spark\n\nUsing your bot's access token, [Create a Spark Webhook](https://developer.ciscospark.com/endpoint-webhooks-post.html)\nwith the `name` \"zbot messages\", a `resource` of \"messages\", and an `event` of \"created.\"\nSet the `targetUrl` to *http://your-docker-container:3000/spark*\n\nCreate another Spark Webhook with your bot's access token. Call this one \"zbot membership\"\nand set the `resource` to \"memberships\", and the `event` to \"created.\" Set the\n`targetUrl` to *http://your-docker-container:3000/sparkroom*\n\nSpark is now set up and you can add your bot to a room by it's email address. Or\nstart a direct conversation with the bot.\n\n### Setting up SMS\n\nCreate a new [Tropo](https://www.tropo.com) application. Set the application type\nto *WebAPI* and the application URL to *http://your-docker-container:3000/tropo*\n\nChoose an SMS-enabled phone number for the Tropo application. Save your application.\n\nSend a text message to your number. You might need to wait a minute or two for the\nnumber to become completely provisioned in Tropo.\n\n### Starting the app, the hard way\n\nTo set up your own bot, you'll need [zmachine-api](https://github.com/akalsey/zmachine-api/tree/deploy).\nThat link points to a forked version of the [original](https://github.com/opendns/zmachine-api/)\nthat has a few more features.\n\nRun zmachine-api as a node app. Then start zbot using an environment variable called\nAPIHOST to tell zbot what URL the API is located at:\n\n```\nAPIHOST=http://zmachine-api.example.com:8000/ node index.js\n```\n\nOther application configuration can also be done through environment variables as\nwell. If you want to host a Cisco Spark bot, you'll need to set CISCOSPARK_ACCESS_TOKEN\nto your bot's access token. If you want to run a different zcode game (other than\nZork), you can specify the zcode filename, without extension, in DEFAULT_GAME.\nAnd to choose which port the bot listens on, set PORT.\n\nTo install a game, put it in the \"games\" directory of the z-machine API application.\n\n## Where are the games?\n\n*There's a zcode file on the table.*\n\nThe bot can play any [Z-Machine game](https://en.wikipedia.org/wiki/Z-machine),\nbut because most are copyrighted (even ones that are free to download and play),\nthe bot doesn't come with any games. You'll need to download some yourself and copy\nthem to the zcode Volume (if using Docker) or the \"games\" directory of the z-machine\nAPI application (if not using Docker).\n\nYou can find games to install in a number of places online. Try [IFDB](http://ifdb.tads.org/)\nor [Interactive Fiction Archive](http://www.ifarchive.org/) to get started.\n\nInfocom has also made [Zork 1-3 available for free](http://www.infocom-if.org/downloads/downloads.html)\nonline. When you download and uzip these games (don't download the Mac version,\nit's just a compiled Mac Classic application), you'll find a directory called\n`DATA` and inside that directory is the zcode file, with a *.DAT* file extension.\n\nRename whatever zcode files you download to have a .z5 extension, since that's\nthe extension expected by the z-machine API. For example, in the textadventure Spark\nbot, Zork runs from a zcode file called \"zork.z5\".\n\n## Acknowledgements\n\nThe z-machine interpreter that the game relies on is the excellent\n[Dumb Frotz](https://github.com/DavidGriffith/frotz). Frotz does all the heavy\nlifting for the bot.\n\nThe bot relies on a REST API frontend to frotz called\n[zmachine-api](https://github.com/opendns/zmachine-api/). The version used by zbot\nis modified to add a couple of new APIs and improve logging. The modified version\ncan be found in the [\"deploy\" branch of my forked Github repo](https://github.com/akalsey/zmachine-api/). Pull requests have been sent, so\nhopefully this modified branch can go away eventually.  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakalsey%2Fzbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakalsey%2Fzbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakalsey%2Fzbot/lists"}