{"id":13880465,"url":"https://github.com/muffinista/chatterbot","last_synced_at":"2025-07-16T16:32:04.154Z","repository":{"id":1474398,"uuid":"1716726","full_name":"muffinista/chatterbot","owner":"muffinista","description":"A straightforward ruby-based Twitter Bot Framework, using OAuth to authenticate.","archived":true,"fork":false,"pushed_at":"2023-03-06T17:55:43.000Z","size":645,"stargazers_count":492,"open_issues_count":0,"forks_count":104,"subscribers_count":32,"default_branch":"main","last_synced_at":"2024-11-10T12:09:47.809Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://muffinlabs.com/","language":"Ruby","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/muffinista.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2011-05-07T20:59:50.000Z","updated_at":"2024-07-25T15:07:42.000Z","dependencies_parsed_at":"2023-07-05T15:45:43.210Z","dependency_job_id":null,"html_url":"https://github.com/muffinista/chatterbot","commit_stats":{"total_commits":318,"total_committers":15,"mean_commits":21.2,"dds":"0.34905660377358494","last_synced_commit":"f60a269f28057eeff5eb98931ba1672c5dd95228"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muffinista%2Fchatterbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muffinista%2Fchatterbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muffinista%2Fchatterbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muffinista%2Fchatterbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muffinista","download_url":"https://codeload.github.com/muffinista/chatterbot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226148891,"owners_count":17581048,"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":"2024-08-06T08:03:03.445Z","updated_at":"2024-11-24T09:31:36.952Z","avatar_url":"https://github.com/muffinista.png","language":"Ruby","funding_links":[],"categories":["Ruby","WebSocket","Dialog Agents, Assistants, and Chatbots"],"sub_categories":["Text-to-Speech-to-Text"],"readme":"Chatterbot\n===========\n\nHi friends, I'm finally archiving this project as of March 2023. I really enjoyed using and maintaining Chatterbot, and I hope it was helpful for other people too. ❤️\n\n\n\n\n\n\nHey! This is Chatterbot 2.0. There have been some breaking changes\nfrom older versions of the library, and it doesn't support MySQL\nanymore. If you are looking for the old version, \nyou can try the [1.0 branch](https://github.com/muffinista/chatterbot/tree/1.0.2)\n\nChatterbot is a Ruby library for making bots on Twitter.  It's\ngreat for rapid development of bot ideas. It handles all of the basic\nTwitter API features -- searches, replies, tweets, retweets, etc. and has\na simple blacklist/whitelist system to help minimize spam and unwanted\ndata.\n\n[![Build Status](https://secure.travis-ci.org/muffinista/chatterbot.png?branch=master)](http://travis-ci.org/muffinista/chatterbot)\n\nFeatures\n--------\n* Handles search queries and replies to your bot\n* Use a simple scripting language, or extend a Bot class if you need it\n* Wraps the Twitter gem so you have access to the entire Twitter API\n* Simple blocklist system to limit your annoyance of users\n* Avoid your bot making a fool of itself by ignoring tweets with\n  certain bad words\n\n\nUsing Chatterbot\n================\n\nChatterbot has a [documentation\nwebsite](http://muffinista.github.io/chatterbot/). It's a\nwork-in-progress. You can also read the [gem\ndocumentation](http://www.rubydoc.info/gems/chatterbot/).\n\n\n\nMake a Twitter account\n----------------------\n\nFirst thing you'll need to do is create an account for your bot on\nTwitter.  That's the easy part.\n\nRun the generator\n-----------------\n\nChatterbot comes with a script named `chatterbot-register` which will\nhandle two tasks -- it will authorize your bot with Twitter and it\nwill generate a skeleton script, which you use to implement your\nactual bot.\n\nWrite your bot\n--------------\n\nA bot using chatterbot can be as simple as this:\n\n```\nexclude \"http://\"\nblocklist \"mean_user, private_user\"\n\nputs \"checking my timeline\"\nhome_timeline do |tweet|\n    # i like to favorite things\n    favorite tweet\nend\n\nputs \"checking for replies to my tweets and mentions of me\"\nreplies do |tweet|\n  text = tweet.text\n  puts \"message received: #{text}\"\n  src = text.gsub(/@echoes_bot/, \"#USER#\")  \n\n  # send it back!\n  reply src, tweet\nend\n```\n\nOr you can write a bot using more traditional ruby classes, extend it if needed, and use it like so:\n```\n  class MyBot \u003c Chatterbot::Bot\n     def do_stuff\n       home_timeline do |tweet|\n         puts \"I like to favorite things\"\n         favorite tweet\n       end\n    end\n  end\n```\n\nChatterbot can actually generate a template bot file for you, and will\nwalk you through process of getting a bot authorized with Twitter.\n\nThat's it!\n\nChatterbot uses the the Twitter gem\n(https://github.com/sferik/twitter) to handle the underlying API\ncalls. Any calls to the search/reply methods will return\nTwitter::Status objects, which are basically extended hashes. If you\nfind yourself pushing the limits of Chatterbot, it's very possible\nthat you should just be using the Twitter gem directly.\n\nStreaming\n---------\n\nChatterbot used to have some basic support for the Streaming API, but\nI've removed it because Twitter is removing and/or restricting access\nto those APIs. If you need the Streaming API, I highly recommend using\nthe the [Twitter\ngem](https://github.com/sferik/twitter#streaming). Chatterbot is built\non the Twitter gem, it works great, and has support for streaming.\n\n\nWhat Can I Do?\n--------------\n\nHere's a list of the important methods in the Chatterbot DSL:\n\n**search** -- You can use this to perform a search on Twitter:\n\n    search(\"pizza\") do |tweet|\n      tweet \"I just read another tweet about pizza\"\n    end\n\n**replies** -- Use this to check for replies and mentions:\n\n    replies do |tweet|\n      reply \"#USER# Thanks for contacting me!\", tweet\n    end\n\nNote that the string #USER# will be replaced with the username of the\nperson who sent the original tweet.\n\n**home_timeline** -- This call will return tweets from the bot's home\n  timeline -- this will include tweets from accounts the bot follows,\n  as well as the bot's own tweets:\n  \n    home_timeline do |tweet|\n      puts tweet.text # this is the actual tweeted text\n      favorite tweet # i like to fave tweets\n    end\n\n**direct_messages** -- This will return any DMs for the bot:\n\n    direct_messages do |dm|\n      puts dm.text\n\n      # send a DM back to the user\n      direct_message \"Hey, I got your message at #{Time.now.to_s}\", dm.sender\n    end\n\n\n**tweet** -- send a Tweet out for this bot:\n\n    tweet \"I AM A BOT!!!\"\n\n**reply** -- reply to another tweet:\n\n    reply \"THIS IS A REPLY TO #USER#!\", original_tweet\n\n**retweet** -- Chatterbot can retweet tweets as well:\n\n```rb\n  search \"xyzzy\" do |tweet|\n    retweet(tweet.id)\n  end\n```\n\n**direct_message** -- send a DM to a user:\n\n    direct_message \"I am a bot sending you a direct message\", user\n\n(NOTE: you'll need to make sure your bot has permission to send DMs)\n\n**blocklist** -- you can use this to specify a list of users you don't\n  want to interact with. If you put the following line at the top of\n  your bot:\n  \n    blocklist \"user1, user2, user3\"\n    \nNone of those users will trigger your bot if they come up in a\nsearch. However, if a user replies to one of your tweets or mentions\nyour bot in a tweet, you will receive that tweet when calling the\nreply method.\n\n**exclude** -- similarly, you can specify a list of words/phrases\n  which shouldn't trigger your bot. If you use the following:\n  \n    exclude \"spam\"\n    \nAny tweets or mentions with the word 'spam' in them will be ignored by\nthe bot. If you wanted to ignore any tweets with links in them (a wise\nprecaution if you want to avoid spreading spam), you could call:\n\n    exclude \"http://\"\n\n**followers** -- get a list of your followers. This is an experimental\n  feature but should work for most purposes.\n\nFor more details, check out\n[dsl.rb](https://github.com/muffinista/chatterbot/blob/master/lib/chatterbot/dsl.rb)\nin the source code.\n\n\n\nDirect Client Access\n--------------------\n\nIf you want to do something not provided by the DSL, you have access\nto an instance of Twitter::Client provided by the **client** method.\nIn theory, you can do something like this in your bot to unfollow\nusers who DM you:\n\n    client.direct_messages_received(:since_id =\u003e since_id).each do |m|\n        client.unfollow(m.user.name)\n    end\n\n\nAuthorization\n-------------\n\nBefore you setup a bot for the first time, you will need to register an\napplication with Twitter.  Twitter requires all API communication to be via an\napp which is registered on Twitter. I would set one up and make it\npart of Chatterbot, but unfortunately Twitter doesn't allow developers\nto publicly post the OAuth consumer key/secret that you would need to\nuse.  If you're planning to run more than one bot, you only need to do\nthis step once -- you can use the same app setup for other bots too.\n\nThe helper script `chatterbot-register` will walk you through most of\nthis without too much hand-wringing. And, if you write a bot without\n`chatterbot-register`, you'll still be sent through the authorization\nprocess the first time you run your script.  But if you prefer, here's\nsthe instructions if you want to do it yourself:\n\n1. [Setup your own app](https://twitter.com/apps/new) on Twitter.\n\n2. Put in whatever name, description, and website you want.\n\n3. Take the consumer key/consumer secret values, and either run your bot, and enter them\nin when prompted, or store them in a config file for your bot. (See\nbelow for details on this).  It should look like this:\n\n \t\t ---\n         :consumer_secret: CONSUMER SECRET GOES HERE\n         :consumer_key: CONSUMER KEY GOES HERE\n\n\nWhen you do this via the helper script, chatterbot will point you at\nthe URL in Step #1, then ask you to paste the same values as in Step #4.\n\nOnce this is done, you will need to setup authorization for the actual\nbot with Twitter. At the first run, you'll get a message asking you to go\nto a Twitter URL, where you can authorize the bot to post messages for\nyour account or not.  If you accept, you'll get a PIN number back.\nYou need to copy this and paste it back into the prompt for the\nbot. Hit return, and you should be all set.\n\nThis is obviously a bunch of effort, but once you're done, you're\nready to go!\n\nConfiguration\n-------------\n\nChatterbot offers a couple different methods of storing the config for\nyour bot:\n\n1. Your credentials can be stored as variables in the script itself.\n   `chatterbot-register` will do this for you. If your bot is using\n   replies or searches, that data will be written to a YAML file.\n   **NOTE** this is a bad practice for scripts that are stored in a\n   source control system such as git, or are publicly available on a\n   site like github.\n2. In a YAML file with the same name as the bot, so if you have\n   botname.rb or a Botname class, store your config in botname.yaml\n3. In a global config file at `/etc/chatterbot.yml` -- values stored here\n   will apply to any bots you run.\n4. In another global config file specified in the environment variable\n   `'chatterbot_config'`.\n5. In a `global.yml` file in the same directory as your bot.  This\n   gives you the ability to have a global configuration file, but keep\n   it with your bots if desired.\n\nRunning Your Bot\n----------------\n\nThere's a couple ways of running your bot:\n\nRun it on the command-line whenever you like. Whee!\n\nRun it via cron.  Here's an example of running a bot every two minutes\n\n    */2 * * * * . ~/.bash_profile; cd /path/to/bot/;  ./bot.rb\n\n\n\n\nRun it as a background process.  Just put the guts of your bot in a loop like this:\n\n```rb\nloop do\n  search \"twitter\" do |tweet|\n    # here you could do something with a tweet\n    # if you want to retweet\n    retweet(tweet.id)\n  end\n\n  replies do |tweet|\n    # do stuff\n  end\n\n  sleep 60\nend\n```\n\n\nBlocklists\n----------\n\nNot everyone wants to hear from your bot.  To keep annoyances to a\nminimum, Chatterbot has a simple blocklist tool. Using it is as simple as:\n\n    blocklist \"mean_user, private_user\"\n\nYou should really respect the wishes of users who don't want to hear\nfrom your bot, and add them to your blocklist whenever requested.\n\nThere's also an 'exclude' method which can be used to add\nwords/phrases you might want to ignore -- for example, if you wanted\nto ignore tweets with links, you could do something like this:\n\n    exclude \"http://\"\n\nContributing to Chatterbot\n--------------------------\n\nPull requests for bug fixes and new features are eagerly accepted.\nSince this code is based off of actual Twitter bots, please try and\nmaintain compatability with the existing codebase. If you are\ncomfortable writing a spec for any changed code, please do so. If not,\nI can work with you on that.\n\nCopyright/License\n-----------------\n\nCopyright (c) 2018 Colin Mitchell. Chatterbot is distributed under the\nMIT licence -- Please see LICENSE.txt for further details.\n\nhttp://muffinlabs.com\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuffinista%2Fchatterbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuffinista%2Fchatterbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuffinista%2Fchatterbot/lists"}