{"id":29586647,"url":"https://github.com/basecamp/campfire-bot-kit","last_synced_at":"2025-07-20T03:31:15.926Z","repository":{"id":222831999,"uuid":"756460704","full_name":"basecamp/campfire-bot-kit","owner":"basecamp","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-05T05:24:51.000Z","size":2019,"stargazers_count":64,"open_issues_count":3,"forks_count":5,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-07-18T05:34:43.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basecamp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-02-12T17:54:43.000Z","updated_at":"2025-07-02T19:05:44.000Z","dependencies_parsed_at":"2024-11-20T23:26:57.994Z","dependency_job_id":"ce7dad6a-9dcd-4ada-b248-aedbed9e3d9c","html_url":"https://github.com/basecamp/campfire-bot-kit","commit_stats":null,"previous_names":["basecamp/campfire-bot-kit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/basecamp/campfire-bot-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fcampfire-bot-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fcampfire-bot-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fcampfire-bot-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fcampfire-bot-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basecamp","download_url":"https://codeload.github.com/basecamp/campfire-bot-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fcampfire-bot-kit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266063099,"owners_count":23870716,"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":[],"created_at":"2025-07-20T03:30:56.816Z","updated_at":"2025-07-20T03:31:15.920Z","avatar_url":"https://github.com/basecamp.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Campfire Bot Kit\n\nCreating a Campfire bot is as simple as replying to a request with either text\nor an image. This reply will be posted directly into the room from which the bot\nwas either mentioned or pinged. Alternatively, you can have your bot post to a\nroom on its own accord by using the bot-specific URLs that are listed in\nCampfire in the bot section.\n\nThis repository contains a simple Ruby bot that can be used as a starting point\nfor your own bot.\n\n## Developing with Ruby\n\nYou'll need a working Ruby environment to build the example bot. We recommend\nusing [rbenv](https://github.com/rbenv/rbenv) to install and manage your Ruby\nversions.\n\nIf you're using macOS, you can install rbenv using Homebrew:\n\n```sh\nbrew install rbenv\n```\n\nInstallation instructions for other platforms are available on the [rbenv GitHub\npage](https://github.com/rbenv/rbenv).\n\nOnce you have rbenv installed, you can install the required Ruby version by\nrunning:\n\n```sh\nrbenv install\n```\n\n## The sample bot\n\nOur sample actually implements two bots, so we can demonstrate both text and\nimage responses. We've defined two endpoints, one for each bot:\n\n- `/hello` responds to its messages with a text greeting\n- `/cat` responds to any messages it receives with a random cat image\n\nThe `/hello` endpoint also shows how to access the content of the message that\nwas sent to the bot.\n\n## How Campfire bots work\n\nCampfire bots can receive and respond to messages sent by other users, and they\ncan also post messages to rooms on their own accord.\n\n### Receiving and responding to messages\n\nWhen a user mentions or pings a bot, Campfire sends a POST request to the bot's\nwebhook URL. That request includes a JSON payload with the details of the\nmessage content, the room it was sent from, and the user who sent it.\n\nHere's an example of a valid message payload:\n\n```json\n{\n  \"room\": {\n    \"id\": 23,\n    \"name\": \"All Talk\"\n  },\n  \"user\": {\n    \"id\": 42,\n    \"name\": \"Kevin\"\n  },\n  \"message\": {\n    \"id\": 100,\n    \"body\": {\n      \"html\": \"\u003cp\u003ehello\u003c/p\u003e\",\n      \"plain\": \"hello\"\n    }\n  }\n}\n```\n\nThe bot should return a successful HTTP status code to acknowledge that it\nreceived the message. It can also include a response, which will be posted to\nthe room the message was sent from.\n\nTo respond with a text message, simply return the text. This is what the\n`/hello` endpoint does in our example bot.\n\nTo respond with an attachment, like an image, return its content, and make sure\nto set the `Content-Type` header to the appropriate MIME type. This is what our\n`/cat` endpoint does.\n\n### Posting messages to rooms\n\nTo send messages to a room that aren't in response to a message, make an HTTP\nrequest to the bot's room-specific URL.  Each bot gets unique URLs for every\nroom that it's a member of. The authentication token is included in the URL, so\nall you need to do is make the request.\n\nTo send a text message, make a POST request to the room's URL with the message\nin the request body. To send an attachment, use a `multipart/form-data` request\nwith the attachment as the `attachment` field.\n\nIn the bot section of the Campfire UI you'll see example `curl` commands for\nsending to each room in both text and attachment format.\n\n## Deploying your bot\n\nYou can deploy the sample bot to try it out. We've added some\n[Kamal](https://kamal-deploy.org) configuration to the repo, so all that's left\nto do is provide the details of your server and Docker registry credentials. You\ncan use an existing server to deploy to, or you can create one with a cloud\nprovider like Digital Ocean or Hetzner.\n\nMost of the deployment details will go into the `config/deploy.yml` file. The\nregistry credentials should be kept separate though, to make sure they don't end\nup in the repository; those can be added to a `.env` file instead.\n\nFor a typical setup, the steps you'll need to do are:\n\n- Add your server's IP address or DNS name to the `servers` section of `config/deploy.yml`\n- Put your Docker username in the `registry` section. If you're using a registry\n  other than Docker Hub, you'll need to add the registry's URL as well.\n- Create a `.env` file to hold your registry password. You can use an access\n  token here if you have one. Your `.env` file should look something like this:\n\n```\nKAMAL_REGISTRY_PASSWORD=yourpassword\n```\n\nYou can now run `kamal setup` to set up your server. Each time you want to\ndeploy your bot, just run `kamal deploy`.\n\nDepending on your particular setup you might need some other configuration. For\nexample, to use a different port, or to use a user other than `root` to connect.\nYou can find all the available options in the\n[Kamal documentation](https://kamal-deploy.org/docs/configuration).\n\nOnce your bot has been deployed, add it to your Campfire instance. In the bot\nsection of the Campfire UI you can give your bot a name, and set its webhook URL\nto be an endpoint of your bot (like `http://mybot.example.com/cats`). Then try\nsending a message to your bot to see it respond.\n\n## Exploring other examples\n\nCheck the [examples](./examples) directory for some more examples that use\ndifferent languages, libraries or frameworks.\n\n## Share your bots!\n\nIf you create a bot that you think others might find useful, we'd love to see\nit! Feel free to open a pull request to add it to a `community` directory in\nthis repo so we can include it for others to use.\n\n## License\n\nThe Campfire Bot Kit is licensed under the MIT license.\n\nCampfire itself uses a commercial license: https://once.com/license\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasecamp%2Fcampfire-bot-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasecamp%2Fcampfire-bot-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasecamp%2Fcampfire-bot-kit/lists"}