How To Build Chatbots

on The Personality Forge
Chapter 4: Keyphrase Macros
1 Macros

Keyphrase Macros (macros) are the most powerful extension of Keyphrases. Each one will match dozens of different ways to say the same thing. It extends the reach of Keyphrases a great deal. Macros start with m:. Some examples of macros are (m:you_are), (m:i_like), and (m:we_will).

How Macros Work

The best way to illustrate how a macro works is to show some examples of its matching power.

(m:you_are) the only one

you are
you must be
you have been
you really are
you seem to be
you have to be
surely you are
you sound like
you have always been
you actually must be
you seem to always be
you are sounding like
you are seeming to be
you look like you are
you appear as though you are
you come across as if you are
(and dozens more)

(m:do_you_know) who it was

do you know
could you see
have you heard
do you realize
do you remember
could you even tell
have you been told
are you aware of
are you totally sure of
do you feel certain of
have you since learned
are you positive
have you found out
could you determine
(and dozens more)

Each macro takes contextual cues to come up with an appropriate list of things to match. For example, (m:you_are) matches a different list of phrases when followed by a verb. Also, (m:are_you) will have a different list of things, which will again be different from (m:are_not_you). The great thing is that you don't need to think about this at all! This all happens in the background.

Using Macros

There are thousands of macros, but they are limited to certain words. They are constructed via combinations of subjects, verbs, question words, and "not". These are also known as "buildable" macros because you can put them together with their parts. Here are the words available for buildable macros:




this - (it|this)
that - (it|that|this)
they - (these|those|they)
one - (one|someone|somebody)
we - (n:we)


where - (where|wherever)
which - (what|which|whatever|whichever)
what - (what|whatever)
who - (who|whoever|whom|whomever)
when - (when|whenever|what time|at what time|at what point)
how - (how|however)
why - (why|how come)


not - (not|no|never|rarely|hardly|seldom|scarcely|least)

Verbs should be inflected to match the subject. For example, you would use (m:i_am) rather than (m:i_be) and (m:who_wants) instead of (m:who_want). You can use past tense as well: (m:i_liked). When asking questions, you can add in "do" or "did" where it makes sense: (m:did_you_like), (m:do_you_want). Other than that, macros can only have one subject, one verb, and one question word: (m:why_did_np_have).

Custom Subjects and Verbs

You can use subjects and verbs not in the list by using one-word macros like (m:does) or (m:can).

(nobody|no one) (m:does) understand

everybody (m:does) expect you to (vp)

Macro Placement

Macros are most often found at the beginning of a Keyphrase. But it's possible in some circumstances (like above) to have them in the middle. You can also have two macros in the same Keyphrase, but it may not work in all situations, and should only be rarely used. Here are some examples:

(m:did_you) hear (that|) (m:np_does) (vp)

(m:are_you) proud (that|) (m:np_does) (vp)

You can also use macros in option lists, or Keyphrase lists like this:

(m:i_am hoping|m:i_do hope) * (that|) (m:you_can|m:you_will)

(m:when_do_you_want_to) (meet|get together), (m:when_are_we) meeting

To see a huge list of well-written Keyphrases and macros, hook your chatbot up to a Chatbot Template (available in your chatbot's settings).

Macros and *, (r), (prenoun)

Macros have a built-in optional wildcard to account for words that often come before your subject, like adjecives, adverbs, determiners, and prepositions. This wildcard does not return a key. Therefore you don't have to put optional wildcards like this before or after your macros. For example, "(m:i_like) dogs" will match "I like little dogs" - you don't need to add (r) or (prenoun) before "dogs" for it to work.

Unique Macros

There are also a number of unique macros for special situations.

(m:action) Physical actions. Typically written in third person. Example: *coughs*

(m:com) A command to do something.

(m:do_not) A command to NOT do something.

(m:do_you_believe_in) Do you believe in something?

(m:do_you_think_that) Do you think something?

(m:have_you_met) Have you met someone?

(m:how_does_it_feel) How does it feel when/where/after..

(m:how_does_it_feel_to) How does it feel to do/be something?

(m:i_heard) I heard that STATEMENT.

(m:i_wish) I wish that something was true.

(m:it_feels_like) It feels like STATEMENT.

(m:it_is_time) It is time to/for something.

(m:it_is_not_time) It is NOT time to/for something.

(m:let_me) Let me do something.

(m:let_us) Let's do something.

(m:let_us_not) Let's NOT do something.

(m:name_is) (Key1)'s name is..

(m:opinion_of) What is your opinions of something.

(m:so) That's so ADJ.

(m:sorry) I'm sorry

(m:such) That's such a NOUN.

(m:tell_me) Tell me a FACT.

(m:what_is_name) What is (Key1)'s name?

(m:what_if) What if STATEMENT?

(m:what_makes_you_think) What makes you think that STATEMENT?

(m:your_favorite) What's your favorite NOUN?

Macros & Keys

IMPORTANT! When using macros, ALWAYS use Plug-in Inflectors for verb keys. Macros can match all kinds of different sentence forms and the verb may come back as "jumping" or "jump" or "jumps". For example the Keyphrase "(m:action) (vp)" will match "*jumps for joy*" and "I am jumping for joy". In the first, (key1) would be "jumps" and in the second, (key1) would be "jumping". Plug-in Inflectors ensure your (key) will be in the form you want in your Responses.

Mixing Macros and Non-Macros

If you want to have a Keyphrase that contains macros and non-macros, use Keyphrase lists rather than option lists.


(m:i_am sorry|sorry|m:i_do apologize|my * apologies)


(m:i_am) sorry,
(m:i_do) apologize,
(sorry|my * apologies)
2 Variants
Using Variants

Variants are differences in tone or meaning. Macro matches include data on variants that you can take advantage of in your Responses. First, let's look at the variants a macro can produce, using an example from above:

(m:you_are) the only one

you are
you have been
you have always been
you really are


you must be
you seem to be
you have to be
surely you are
you sound like
you actually must be
you seem to always be
you are sounding like
you are seeming to be
you look like you are
you appear as though you are
you come across as if you are
you are not
you are never
you have not been

In the above example, the first three Macro Keyphrases don't have a variant. The next section are all part of the [seem] variant, and the last secrion are part of the [not] variant. Here's how you take advantage of this information in your Responses (if you want to):

If you don't target a variant with a Response, the Response will match everything (except [not] and [reverse] - see below). At least one Response must not have a variant marker so that the main matches have something to respond to. Responses with a [variant] marker before them will only match that variant.

All the Variants

Variants are produced by the following macros:

Buildable Macros:
be, do [seem]
can [could]
will [would]
most macros [not]

Unique Macros:

[command] - Tell someone to act: You have to VERB.
[suggest] - Suggest an action: You should VERB.
[ask] - Ask someone to do an action: Will you VERB?
[reverse] - Ask someone if they mind doing something: Do you mind VERBING?

[command] - Tell someone not to act: Do not VERB.
[suggest] - Suggest not acting: You should not VERB.
[release] - Releasing planned action: You don't have to VERB.
[stop] - Stop doing an action: Stop VERBING.

[not] - Do you doubt the existence of NOUN?

[suggest] - Suggest an action: Let me VERB.
[ask] - Ask to do actions: Shall I VERB?
[reverse] - Ask with reverse meaning: Do you mind if I VERB?

[command] - Demanding actions together: You will VERB with me.
[suggest] - Suggest actions together: Let's VERB.
[ask] - Asking to do actions together: Shall we VERB?
[reverse] - Asking with reverse meaning: Do you mind if we VERB?

[command] - Refusing actions together: We will not VERB.
[suggest] - Suggesting not taking actions together: We should not VERB.
[release] - Releasing planned actions together: We don't have to VERB.
[stop] - Ending actions together: Let's stop VERBING.

Why Target Variants?

Targetting variants in Responses gives you finer control over the feel of what was said. You might want to respond differently if someone says "You're crazy" vs. "You seem crazy". Or if someone says "Eat this cake!" vs "Would you like this cake?".

Using "Not" In Macros

It’s recommended to use _not as part of a macro only when it doesn’t work without it. If the Keyphrase works with and without "not", it's more flexible to write it without the _not and use the [not] variant.

These don't make sense without the _not:

(m:i_can_not) help it
(m:which) part of (*) (m:do_not_you) (understand|get)
(m:i_will_not) stand by * while (np) (vp)

Macros with _not do not generate a [not] variant.