I think that the most interesting part of a chatbot (or conversational agent) is that it actually allows the developer (company) to directly communicate with its end-users (customers). We're currently limited to echoing the text messages only if they are sent by our user to us. Are there any other methods for us to communicating with our clients?

In this post, we would be taking a look at the LineBotApi class and the different linebot.models objects we could use for replying our user.

Throwback Review

From the last post, we've created an echo bot that mimics the reply of our user. Our implementation of the main function for handling messages looks something like this:

# Import required modules
from linebot import LineBotApi
from linebot.models import *

# Initialize Messaging API & Webhook
line_bot_api = LineBotApi('Channel Access Token')
handler = WebhookHandler('Channel Secret')

# Message handler
@handler.add(MessageEvent, message=TextMessage)
def handle_message(event):
    line_bot_api.reply_message(
        event.reply_token,
        TextSendMessage(text=event.message.text)
    )

LineBotApi

The LineBotApi is basically the class that allows the developer to send messages, setup rich menus, and getting some information regarding our users. Here, we would be focusing on 4 functions: reply_message(), push_message(), multicast() and broadcast().

In our example above, we are using the reply_message() function. This function basically sends a response according to the reply_token that is sent from the user to our bot. There is a time limit for using the reply_token, could only be used once, and used only when our client sends a message.

The push_message() on the other hand, allows us to send a message to our client. Messages are sent according to the client's user_id (make sure to keep track of them). So, it is very useful for API triggers or sending multiple message bubbles to our client. We could also send a multicast() to multiple users, where the to argument takes in a list[str] that could handle up to 150 users. Finally, there is a broadcast() function that allows us to send news or announcements to all our users.

from linebot import LineBotApi
line_bot_api = LineBotApi('Channel Access Token')

line_bot_api.reply_message(reply_token, messages, notification_disabled=False, timeout=None)

line_bot_api.push_message(to, messages, notification_disabled=False, timeout=None)

line_bot_api.multicast(to, messages, notification_disabled=False, timeout=None)

line_bot_api.broadcast(messages, notification_disabled=False, timeout=None)

The messages argument could basically take in a SendMessage object, or a list[SendMessage] of objects. Now, what are these objects?

linebot.models

Just like the average LINE user, we could send different kinds of messages (text, sticker, image, video, audio, location) to our client. The only difference is, we are doing it by code (and we don't need to buy them stickers).

text_message = TextSendMessage(text='Hello, world')

sticker_message = StickerSendMessage(
    package_id='1',
    sticker_id='1'
)

image_message = ImageSendMessage(
    original_content_url='https://example.com/original.jpg',
    preview_image_url='https://example.com/preview.jpg'
)

video_message = VideoSendMessage(
    original_content_url='https://example.com/original.mp4',
    preview_image_url='https://example.com/preview.jpg'
)

audio_message = AudioSendMessage(
    original_content_url='https://example.com/original.m4a',
    duration=240000
)

location_message = LocationSendMessage(
    title='my location',
    address='Tokyo',
    latitude=35.65910807942215,
    longitude=139.70372892916203
)

There are also many other types of messages we could send to our user. These are called Templates. The most common one is ButtonTemplate, where you give the user some buttons that allows the user to "perform" some actions (as shown in the examples below). There are some restrictions when it comes to these templates:

  1. Thumbnail image (.png or .jpg only) has max width of 1024px, max size of 1 MB, and aspect ratio of 1.41:1 or 1:1
  2. Title has max length of 40 characters
  3. Text has max length of 160 characters (60 with image or title)
  4. Maximum 4 actions
buttons_template_message = TemplateSendMessage(
    alt_text='Buttons template',
    template=ButtonsTemplate(
        thumbnail_image_url='https://example.com/image.jpg',
        title='Menu',
        text='Please select',
        actions=[
            PostbackAction(
                label='postback',
                display_text='postback text',
                data='action=buy&itemid=1'
            ),
            MessageAction(
                label='message',
                text='message text'
            ),
            URIAction(
                label='uri',
                uri='http://example.com/'
            )
        ]
    )
)

Buttons

CarouselTemplate could be thought of as a scrollable ButtonsTemplate that sends a few CarouselColumn (could be thought of as ButtonsTemplate). Allowing the developer to give the client more choices. Just like ButtonsTemplate there are also some restrictions for CarouselTemplate.

  1. Each column have the same restrictions as ButtonsTemplate
  2. Each column must have the same number of actions
  3. Maximum 10 columns
carousel_template_message = TemplateSendMessage(
    alt_text='Carousel template',
    template=CarouselTemplate(
        columns=[
            CarouselColumn(
                thumbnail_image_url='https://example.com/item1.jpg',
                title='this is menu1',
                text='description1',
                actions=[
                    PostbackAction(
                        label='postback1',
                        display_text='postback text1',
                        data='action=buy&itemid=1'
                    ),
                    MessageAction(
                        label='message1',
                        text='message text1'
                    ),
                    URIAction(
                        label='uri1',
                        uri='http://example.com/1'
                    )
                ]
            ),
            CarouselColumn(
                thumbnail_image_url='https://example.com/item2.jpg',
                title='this is menu2',
                text='description2',
                actions=[
                    DatetimePickerAction(
                        label='datetime2',
                        data='action=book_table',
                        mode='datetime'
                    ),
                    CameraAction(
                        label='camera2'
                    ),
                    LocationAction(
                        label='location2'
                    )
                ]
            )
        ]
    )
)

Carousel

The actions available for Buttons and Carousel include:

  1. MessageAction: Template text message reply
  2. PostbackAction: Sends POST request (handler.add(PostbackEvent))
  3. URIAction: Opens a web url
  4. DatetimePickerAction: Allows user to return a date/time
  5. CameraAction: Opens camera in LINE
  6. CameraRollAction: Opens camera roll in LINE
  7. LocationAction: Opens location screen in LINE

Besides using Buttons and Carousels to give our options, there is also a QuickReply function that allows us to create template replies. This allows us to provide more than one answer.

text_message = TextSendMessage(
        text='Hello, world!',
        quick_reply=QuickReply(
            items=[
                QuickReplyButton(action=MessageAction(label="Hello", text="Hello")),
                QuickReplyButton(action=MessageAction(label="Bounjour", text="Bounjour")),
                QuickReplyButton(action=MessageAction(label="Guten tag", text="Guten tag"))
           ]
        )
    )

QuickReply

So, there we have it. The most used and basic message APIs for LINE. Now, we could provide more services and experiences for our users.

Reference: LINE API SDK for Python