How will can respond

Will can respond in a variety of ways, and since he's pure python, your imagination is the limit.

Talk to the room

Like any normal person, will can talk to the chat room, or in 1-1 chats. To talk to the room in your plugins, you'll want to use the self.say() method.

def say_bonjour_will(self, message):
    # Awesome stuff
    self.say("Bonjour!", message=message)


Note that we pass messsage along. This allows will to route his reply to the correct room. Without it, he'll just speak to the DEFAULT_ROOM.

say() comes with a number of options, including color, html, and ping notify.

self.say(content, message=None, room=None, html=False, color="green", notify=False)

Reply with a mention

Sometimes you want will to ping you - that's where @name mentions are great. To do those in will, you'll want to use self.reply()

@respond_to("^hi")   # Basic
def hi(self, message):
    self.reply(message, "hello, %s!" % message.sender.nick)

Hi, Hello, username!

Note the order of arguments is different here, and messsage is required. All the options:

self.reply(message, content, html=False, color="green", notify=False)

Talk to the room from a webhook

When will recieves messages from webhooks and HTTP requests, he's still connected to chat, and you can use .say(). By default, he'll speak to DEFAULT_ROOM.

def ping(self):

If you want to talk to a different room, you can pass in the room argument with one of the rooms from self.available_rooms.

Send an email

Will has one email backend at the moment, via mailgun. If you've set DEFAULT_FROM_EMAIL, MAILGUN_API_URL, and MAILGUN_API_KEY, you can use self.send_email()

@respond_to("status report")
def send_status_report(self):
    self.send_email(email_list=[''], subject="Here's the latest report", message=rendered_template("report.html", {}))

Here's all the options:

self.send_email(from_email=None, email_list=[], subject="", message="")

Schedule a reply for the future

Sometimes, you want will to make plans for the future. That's where self.schedule_say() comes in handy.

@randomly(start_hour='10', end_hour='17', day_of_week="mon-fri", num_times_per_day=1)
def walkmaster(self):
    now =
    in_5_minutes = now + datetime.timedelta(minutes=5)

    self.say("@all Walk happening in 5 minutes!")
    self.schedule_say("@all It's walk time!", in_5_minutes)

The options are pretty much the same as self.say, with the addition of the when parameter.

self.schedule_say(content, when, message=None, room=None, html=False, color="green", notify=False)

Set the topic

Sometimes, it's good to give the conversation some direction. Will can set the topic in hipchat using self.set_topic()

import requests

@respond_to("new topic")
def give_us_somethin_to_talk_about(self, message):
    r = requests.get("")
    data = r.json()
    self.set_topic(data["text"], message=message)

Note: you can't set the topic of a 1-1 chat. Will will complain politely. All options:

self.set_topic(topic, message=None, room=None) 

Do any python thing

Will is Just Python. Because of that, your imagination is the limit of what he can do to respond to requests.

Here's a few things our will does, every day:

Will is open-source, and PRs are very welcome. If someone wants to write self.send_sms(), or anything else, it's all yours!

Ready to make some plugins? Check out how to create and organize plugins.