{"id":13639704,"url":"https://github.com/robkorn/urbit-chatbot-framework","last_synced_at":"2025-04-19T22:33:42.721Z","repository":{"id":54063134,"uuid":"336103174","full_name":"robkorn/urbit-chatbot-framework","owner":"robkorn","description":"A framework that allows anyone to create an Urbit Chatbot with only a few lines of code.","archived":false,"fork":false,"pushed_at":"2021-07-06T12:07:42.000Z","size":94,"stargazers_count":25,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-11T16:38:20.776Z","etag":null,"topics":["chatbot","framework","rust","urbit"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/robkorn.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}},"created_at":"2021-02-04T22:48:14.000Z","updated_at":"2023-11-01T22:11:16.000Z","dependencies_parsed_at":"2022-08-13T06:20:59.506Z","dependency_job_id":null,"html_url":"https://github.com/robkorn/urbit-chatbot-framework","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkorn%2Furbit-chatbot-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkorn%2Furbit-chatbot-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkorn%2Furbit-chatbot-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkorn%2Furbit-chatbot-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robkorn","download_url":"https://codeload.github.com/robkorn/urbit-chatbot-framework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223810665,"owners_count":17206806,"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":["chatbot","framework","rust","urbit"],"created_at":"2024-08-02T01:01:03.600Z","updated_at":"2024-11-09T09:31:33.543Z","avatar_url":"https://github.com/robkorn.png","language":"Rust","funding_links":[],"categories":["Archive"],"sub_categories":["Tools"],"readme":"# Urbit Chatbot Framework\n\nA framework that allows anyone to create an Urbit Chatbot with only a few lines of code.\n\nThe Urbit Chatbot Framework takes care of all the complexities of connecting to a ship, subscribing to a chat, parsing messages, and sending messages automatically for you. All you have to do is simply write the message handling/response logic and everything else will just work.\n\nThis crate is [available on crates.io](https://crates.io/crates/urbit-chatbot-framework).\n\n[![awesome urbit badge](https://img.shields.io/badge/~-awesome%20urbit-lightgrey)](https://github.com/urbit/awesome-urbit)\n\n## Basic Design\n\nAt its core, the framework revolves around the `Chatbot` struct. It is defined as:\n\n```rust\n/// This struct represents a chatbot that is connected to a given `ship`,\n/// is watching/posting to a specific `chat_ship`/`chat_name`\n/// and is using the function `respond_to_message` to process any messages\n/// which are posted in said chat.\npub struct Chatbot {\n    /// `respond_to_message` is a function defined by the user of this framework.\n    /// This function receives any messages that get posted to the connected chat,\n    /// and if the function returns `Some(message)`, then `message` is posted to the\n    /// chat as a response. If it returns `None`, then no message is posted.\n    respond_to_message: fn(AuthoredMessage) -\u003e Option\u003cMessage\u003e,\n    ship: ShipInterface,\n    chat_ship: String,\n    chat_name: String,\n}\n```\n\nTo create a chatbot, one simply must instantiate a `Chatbot` struct with:\n\n- A `ShipInterface` to connect to to interact with the Urbit network\n- The `chat_ship` that the chat is running on\n- The `chat_name`\n- A function (optionally named respond_to_message) which takes an `AuthoredMessage` as input, and returns an `Option\u003cMessage\u003e` as output\n\n## Creating A Chatbot\n\nA `Chatbot` is most easily created using the `new_with_local_config` method:\n\n```rust\n/// Create a new `Chatbot` with a `ShipInterface` derived automatically\n/// from a local config file. If the config file does not exist, the\n/// `Chatbot` will create the config file, exit, and prompt the user to\n/// fill it out.\npub fn new_with_local_config(\n    respond_to_message: fn(AuthoredMessage) -\u003e Option\u003cMessage\u003e,\n    chat_ship: \u0026str,\n    chat_name: \u0026str,\n) -\u003e Self {\n```\n\nThis automatically deals with creating a local ship config file for the user to edit if none available, and then on rerun, reading said config to connect to a ship.\n\nIn order to use this method, we need to define a `respond_to_message` function which we can supply as an argument. Here is an example of one of the simplest possible implementations:\n\n```rust\nfn respond_to_message(authored_message: AuthoredMessage) -\u003e Option\u003cMessage\u003e {\n    // Any time a message is posted in the chat, respond in chat with a static message.\n    Some(Message::new().add_text(\"Calm Computing ~\"))\n}\n```\n\nDo note, that if this function returns `None`, then the `Chatbot` will not reply to the message, and simply continue forward processing the next one.\n\nWith this function defined, you can now easily call `Chatbot::new_with_local_config()` and acquire an instantiated `Chatbot`.\n\n## Running The Chatbot\n\nOnce the `Chatbot` struct is defined, all one needs to do is:\n\n```\nchat_bot.run();\n```\n\nThis will automatically perform all messaging, parsing, and interfacing with the connected Urbit ship without any further code required.\n\nAnd just like that you have an Urbit chatbot ready to go.\n\n# Example Projects\n\nThe projects linked below are example Urbit Chatbot projects. They link directly to the `main.rs` so you can immediately see the implementation of said chatbot.\n\nYou can also easily run any of these examples by:\n\n1. Cloning this repo.\n2. Changing directory into the example project folder in your terminal.\n3. Editing `main.rs` with the `chat_ship` and `chat_name` which you wish to run the bot in.\n4. Running `cargo run` the first time to create the ship config file.\n5. Editing the `ship_config.yaml` with your ship information (Moons or comets typically work best. Do not use your daily-driver ship because messages from the ship the chatbot is connected to are all ignored.)\n6. Running `cargo run` to run the chatbot with the ship config info provided.\n\n### Simple Chatbot\n\n[The Simple Chatbot](examples/simple-chatbot/src/main.rs) is the simplest chatbot possible which replies to all messages in a chat with a static message. Approximately 4 lines of real code, showing off how simple it is to create a chatbot.\n\nThe point of this project is to display the bare minimum requirements for setting up a chatbot.\n\n### Anti Comet Chatbot\n\n[The Anti Comet Chatbot](examples/anti-comet-chatbot/src/main.rs) is a slightly more advanced chatbot which takes a look at the ship that authored the latest message. If the ship has a name long enough to be classified a comet, then it responds with a message. Otherwise, it returns `None`, meaning no message is sent by the chatbot to the chat in reply (if they aren't a comet).\n\n### Crypto Prices Chatbot\n\n[The Crypto Prices Chatbot](examples/crypto-prices-chatbot/src/main.rs) is a real world example of a useful chatbot that implements a command for everyone in a chat to use.\n\nIn effect, if anyone types:\n\n```\n|price {crypto_name_here}\n```\n\nsuch as\n\n```\n|price bitcoin\n```\n\nThen the bot will fetch the bitcoin price via coingecko API, and return it:\n\n```\nUSD $37167\n```\n\nThis is the first chatbot implemented via the Urbit Chatbot Framework which has real utility, and is a great example of how to go about building chatbots for use cases which need to reply based off of commands and make calls to external APIs.\n\n### Bible Chatbot\n\n[The Bible Chatbot](examples/bible-chatbot/src/main.rs) is another real world example of a useful chatbot that implements a command for everyone in a chat to use.\n\nThis chatbot allows anyone to use the `!bible` command and request one or more verses from the bible (KJV):\n\n```\n!bible John 1:1-5\n```\n\n### Poll Chatbot\n\n[The Poll Chatbot](examples/poll-bot) is the most complex chatbot example enabling anyone to run votes/polls inside of their chats. Every poll is saved into a `.json` file and ensured that every ship only gets a single vote.\n\nTo start a poll with any given amount of options:\n\n```\n!poll [option1] [option2] ...\n```\nor\n```\n!poll -t [title] [option1] [option2] ...\n```\nThe title of a poll acts as its ID, so don't use the same one multiple times yet.\n\nOnce a poll is running any ship can vote (precisely once):\n\n```\n!vote [pollid] [option]\n```\n\nResults of a poll can be accessed via:\n\n```\n!results [pollid]\n```\nor\n```\n!results all\n```\nto view all active polls.\n\nThe creator of a poll can end the poll via:\n\n```\n!endpoll [pollid]\n```\n\nPolls without titles have a numerical ID generated at creation and are stored in a json file in the directory that the bot is run from.\n\n(Credits to [~hodzod-walrus](https://github.com/benmcc100) for creating the Poll Chatbot)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobkorn%2Furbit-chatbot-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobkorn%2Furbit-chatbot-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobkorn%2Furbit-chatbot-framework/lists"}