Message Flow

The bot receives input from the user, the bot responds to the user.

Seems simple, right?

But before, between, and be-after that happening, a lot of other things happen as well. Understanding control flow in the message interactions is critical to writing a successful bot.

This flowchart illustrates the entire path of the message. If this seems too complicated to understand, don’t worry — we’ll break it down piece by piece. But it might be helpful to get a bird’s-eye view of what’s going on.

Message flow

Message Flow

Here is a brief text description of the flow:

  • User sends a message

    • Does it match a pattern for a message?

    • Yes — Select that message.

    • No

      • Does it match an intent?

        • Yes — Select that message.
        • No — Select the default message.
  • The Message Begins

  • Preprocess Code is evaluated

    • If Send Immediate Reply is called during Preprocess, the Immediate Reply message is added to output and the output is sent to the user. This ends the message flow.
    • If Trigger Next Message is called during Preprocess, flow begins again with that message.
  • Preresult is added to Output

  • Main Result is prepared

    • What is the Response Content Type?
    • Static
      • Result is added to output.
    • Dynamic
      • Responder is invoked.
        • If a Required Context is needed
          • If stored, fetch from memory
          • If not stored, ask user for input.
        • Webhook request is sent
        • The response from the request is processed and added to output.
  • Postresult is added to output

  • Postprocess code is evaluated

    • If Send Immediate Reply is called during Postprocess, the Immediate Reply message is added to output and the output is sent to the user. This ends the message flow.
    • If Trigger Next Message is called during Postprocess, flow begins again with that message. (Output queue is retained.)
  • Output is sent to user.

  • If there is Process User Result code:

    • Wait for input from user.
    • Execute Process User Response code.
    • If Send Immediate Reply is called during Process User Result, the Immediate Reply message is added to output and the output is sent to the user. This ends the message flow.
    • If Trigger Next Message is called during Process User Result, flow begins again with that message.
    • Otherwise, User Response is treated as a new input, and Pattern Matching begins.
  • End. (Wait for next input.)

Now, let’s break it down.

User Input and Message Selection

User Input and Pattern Matching

User Input and Pattern Matching

When a user sends a message to your bot, the bot tries to match the content of the message to a pattern. If a match is found, then that message is triggered.

If no patterns are matched, the bot tries to match an intent.If a match is found, then that message is triggered.

Otherwise, the default message is triggered.

If there is no matched pattern, no matched intent, and no default message, the bot simply does not respond, and waits for the next input.

Begin Message and Preprocess Execution

Begin Message and Preprocess Execution

Begin Message and Preprocess Execution

When a message has been triggered, the Preprocess Code is executed.

If sendImmediateReply() has been called during code execution, the message defined in that function is added to output, the output is sent to the user, and the message flow ends.

If setTriggerNextMessage(), has been called during code execution, a new Message Flow begins.

Otherwise, the output is prepared.

Output is Prepared

Output is Prepared

Output is Prepared

The Output is prepared in four stages:

  • Preresult
  • Result
  • Quick Replies
  • Postresult

The pre-result and post-result is static content. The Result can either be static or dynamic. Static content is simply defined in the Message Editor. Dynamic content is fetched from a RESTful Web Service using a Web Responder.

Note

The Output is not sent to the user at this stage — it is only prepared. Consequently, if setTriggerNextMessage() is called during the Postprocess Code execution, the results will be queued until the output is sent to the user.

Note

If anything follows Quick Replies (either Post Result content or output added by a triggered next message), the Quick Replies will not be accessible to the user. Quick Replies are removed from the Messenger window as soon as the next message is sent.

Main Result Prepared

Result is Prepared

Result is Prepared

Dynamic or Static

Dynamic vs. Static Result

Dynamic vs. Static Result

In the case of a Static Result, the result is simply prepared. Dynamic Results require a Web Responder, which is immediately invoked.

Required Context

Required Context needed?

Required Context needed?

A Required Context is a special type of variable or parameter needed for a Web Responder. A Required Context includes a built-in mini-responder that asks the user for the value of the parameter when it is needed.

If a Required Context is not called as a parameter in a Web Responder, the Web Responder’s HTTP Request is immediately prepared and sent to the Webhook URL.

Required Context flow

Required Context flow

If a Required Context is called as a parameter in a Web Responder, the bot will check if the required value is stored already. If not, the Required Context’s built-in mini-responder will send its Message Content to the user, asking for the needed information. The user’s response is saved as the value for the parameter.

If the Required Context value is already stored, that process is skipped. In either case, the value of the Required Context is included in the Web Responder’s Request, and the Request is sent to the Web Hook URL.

Web Responder Results Prepared and Added to Output

Responder Results added to Output

Responder Results added to Output

The Web Responder send its request and waits for a JSON response. The JSON response is then parsed and a result prepared, based on the structure defined in the Responder. This is then added to the output as the main Result.

Postprocess Code is Executed and Output is Sent to the User

Postprocess Code is Executed

Postprocess Code is Executed

Once the output is prepared (Pre-result, Main Result, and Post-result), the Postprocess Code is executed .

If sendImmediateReply() has been called during code execution, the message passed to the function is added to output, the output is sent to the user, and the message flow ends.

If setTriggerNextMessage() has been called during code execution, a new Message Flow begins.

Otherwise, the output is sent to the user.

Process User Response Code is Executed

Process User Response

Process User Response

After this, if there is any Embedded Code in Process User Response, the bot waits for a user input before executing it. This happens whether the User Response is a free-entry or a selection from a Quick Reply entry.

Note

The content of the user’s input can be pulled into the JavaScript with getCurrentUserMessage().

If sendImmediateReply() is called during code execution, the Immediate Reply message is sent to output, and the message flow ends.

If setTriggerNextMessage() is called during code execution, a new Message Flow begins.

Otherwise, the user response is treated as a new input, and the Message Flow begins again with Pattern Matching. (This is true even if there was a Quick Reply Menu. — Pattern Matching can be used to catch Quick Reply responses.)

Message Flow Ends

New User Input

New User Input