Controller Overview

Controllers are responsible for handling incoming requests and getting a response back to the user via replies. They also perform all state transitions.
Naming Conventions
The controller's methods, also referred to as actions, must be named after the flow's states. So for example, given the flow:
1
flow :onboard do
2
  state :say_welcome
3
  state :ask_for_phone
4
  state :get_phone, fails_to: :ask_for_phone
5
end
Copied!
The corresponding controller would be:
1
class OnboardsController < BotController
2
  def say_welcome
3
​
4
  end
5
​
6
  def ask_for_phone
7
  
8
  end
9
​
10
  def get_phone
11
​
12
  end
13
end
Copied!
BotController
Every Xip bot comes with a default bot_controller.rb. You don't have to know what each method does yet, we'll cover each in their respective doc sections.
1
# frozen_string_literal: true
2
​
3
class BotController < Xip::Controller
4
​
5
  helper :all
6
​
7
  def route
8
    if current_message.payload.present?
9
      handle_payloads
10
      # Clear out the payload to prevent duplicate handling
11
      current_message.payload = nil
12
      return
13
    end
14
​
15
    # Allow devs to jump around flows and states by typing:
16
    #   /flow_name/state_name or
17
    #   /flow_name (jumps to first state) or
18
    #   //state_name (jumps to state in current flow)
19
    # (only works for bots in development)
20
    return if dev_jump_detected?
21
​
22
    if current_session.present?
23
      step_to session: current_session
24
    else
25
      step_to flow: 'hello', state: 'say_hello'
26
    end
27
  end
28
​
29
private
30
​
31
  # Handle payloads globally since payload buttons remain in the chat
32
  # and we cannot guess in which states they will be tapped.
33
  def handle_payloads
34
    case current_message.payload
35
    when 'developer_restart', 'new_user'
36
      step_to flow: 'hello', state: 'say_hello'
37
    when 'goodbye'
38
      step_to flow: 'goodbye'
39
    end
40
  end
41
​
42
  # Automatically called when clients receive an opt-out error from
43
  # the platform. You can write your own steps for handling.
44
  def handle_opt_out
45
    do_nothing
46
  end
47
​
48
  # Automatically called when clients receive an invalid session_id error from
49
  # the platform. For example, attempting to text a landline.
50
  # You can write your own steps for handling.
51
  def handle_invalid_session_id
52
    do_nothing
53
  end
54
​
55
end
56
​
Copied!
All of your controllers will inherit from this BotController:
1
class QuotesController < BotController
2
​
3
end
Copied!
Failing to Progress a User
One of the primary responsibilities of a controller is to update a user's session. The other responsibility is sending replies to a user. If you fail to do either of these things, essentially the user at the other end won't have any feedback.
If a controller action fails to update the state or send any replies, Xip will automatically fire a CatchAll. This is designed to catch errors during development. If you are certain you don't want to send any feedback to the user for a specific action you can call do_nothing to override Xip's default behavior.  
Before/After/Around Filters
Like Ruby on Rails controllers, Xip controllers support before_action, after_action, and around_action filters.
Given a BotController that loads a user:
1
class BotController < Xip::Controller
2
​
3
  before_action :current_user
4
  
5
  private def current_user
6
    @current_user ||= User.find_by_session_id(current_session_id)
7
  end
8
  
9
end
Copied!
The current_user method will be run on all controllers that inherit from BotController. Similarly, if you add a before_action to a child controller, only that controller's actions will run that filter.

Flows - Previous

State Options

Next - Controllers

Sessions

Last modified 9mo ago

Copy link

Contents

Naming Conventions

BotController

Failing to Progress a User

Before/After/Around Filters