# Development guidelines for corporate customers
These are the development guidelines for corporate users. Follow these guidelines when developing on the LINE Platform.
Table of contents
- About LINE bot
- Notes on receiving webhook events on bot servers
- Secure communication and bot server environment
- Verification of received webhook events
- Support for mass and intensive webhook event delivery
- Webhook ON/OFF setting
- Webhook ON/OFF and auto reply message settings
- Processing flow when receiving a webhook request
- If a problem occurs when sending a webhook request
- Other precautions
- Notes on sending API requests
- Notes on using LINE Login
- LINE Login authorization and verification process
- About callback URLs
- Get authorization code or error response in web app
- Issue an access token
- Verify the ID token
- Other LINE Login APIs
- Linking information obtained through LINE Login with information managed by your company (ID linking)
- Add friend option
- state verification
- LINE Front-end Framework (LIFF)
- Other features
# About LINE bot
# What is LINE Developers?
LY Corporation provides APIs that enables external companies and developers to link with LY Corporation services. The LINE Developers site provides developers with these LINE API specs, documentation explaining development procedures, and a console for configuration. To learn more, see About LINE Developers site.
# How LINE bot works
LINE bots use the Messaging API to send and receive information. To learn more, see How it works in the Messaging API documentation.
# About the relationship between LINE bots and channels
The relationship between bots as a component of the LINE Official Account and the channel is as follows.
# Understanding various terms
See the Glossary to learn more about the various terms.
# LINE bot development procedure
Create a LINE Official Account (bot) and Messaging API channel.
You can create them from one of these sites:
- LINE Developers Console
- LINE Official Account Manager
- LINE AGP
This section shows how to create them in the LINE Developers Console.
Prepare these systems and mechanisms:
- Environment such as a server that calls the Messaging API that supports TLS 1.2 or later
- Environment such as a bot server that gets webhook events that support TLS 1.2 or later
It's not always necessary to prepare separate environments for the environment such as the server that calls the Messaging API and the environment such as the bot server that gets the webhook event.
Prepare and implement the bot server to get webhook events.
In the LINE Developers Console, go to Messaging API > Webhook settings, set the bot server URL in Webhook URL, and then enable Use Webhook.
Add the LINE Official Account you created as a friend and check if the bot server is getting webhook events.
# Items to check before releasing the LINE bot
Before releasing a LINE bot, be sure to check the following.
Members who need access to the LINE Developers Console are granted channel permissions and LINE Official Account Manager permissions (opens new window) (only available in Japanese).
Confirm that the correct URL is set in Messaging API > Webhook settings > Webhook URL in the LINE Developers Console, and that the bot server can properly process webhook events.
The implementation takes into account the precautions described in Notes on sending API requests.
Comply with the security standards in the LINE BOT security guidelines (opens new window) (only available in Japanese) and LINE BOT security checklist (opens new window) (only available in Japanese), or establish an environment that is equal or better.
# Notes on receiving webhook events on bot servers
# Secure communication and bot server environment
# HTTPS communication compatible with TLS 1.2 or later
When the bot server gets webhook events sent from the LINE Platform, it must use HTTPS communication that supports TLS 1.2 or later. Use an SSL certificate issued by a public certification authority for HTTPS communication. You can purchase an SSL certificate, or you can use a certificate issued for free, such as Let's Encrypt (opens new window). For more information on setting up webhooks, see Set a Webhook URL in the Messaging API documentation.
# Build an environment that complies with security guidelines
These security guidelines and checklists describe the security standards that must be met when building a bot server. When providing services using a LINE bot, comply with the stated security standards or prepare an environment equal to or better than that.
- LINE bot security guidelines (opens new window) (only available in Japanese)
- LINE bot security checklist (opens new window) (only available in Japanese)
# Verification of received webhook events
The request header x-line-signature
contains a signature to verify that the received webhook event came from the LINE Platform. The bot server uses a defined algorithm from the received request body to get the digest value and verify that it matches the signature in the x-line-signature
request header. By verifying that the signatures match, you can verify that the request you got is the correct webhook event sent by the LINE Platform.
The channel secret is used as the calculation key for the signature. Therefore, be careful when handling the channel secret. For more information and code samples, see Signature validation in the Messaging API reference.
The IP address of the LINE Platform from which the webhook request is sent isn't disclosed. For better security, use signature validation instead of access control by IP address.
# Support for mass and intensive webhook event delivery
Due to the nature of the LINE Official Account, a large amount of access (sending webhook events) may occur unexpectedly. If a webhook request that exceeds the processing capacity of the bot server is sent, messages to users may be delayed or not delivered.
- Immediately after setting Show in search results (opens new window) (only available in Japanese) of the LINE Official Account to "Show"
- Immediately after the implementation of measures such as Sponsored sticker (opens new window) (only available in Japanese)
- Immediately after sending a message to all friends at once using broadcast message, etc. (especially when including a campaign or other measure)
- Immediately after being featured in the media, such as news or television
Access may be particularly concentrated during the hours of 12:00 noon and 17:00 to 24:00.
- LY Corporation doesn't provide an environment for performing load tests on bot servers. Don't perform load testing in a way that includes the LINE Platform.
- If you send an announcement message such as a campaign that's considered to be highly responsive to users on the LINE Official Account with a large number of friends (more than one million), it may affect the performance of the entire LINE Platform. In such cases, avoid sending messages all at once, and take measures such as sending messages in stages so that access from users isn't concentrated.
# Webhook ON/OFF setting
You can turn on or off Use webhook from Messaging API settings > Webhook settings in the LINE Developers Console. You can also turn Webhooks on or off in the Settings > Response settings section of the LINE Official Account Manager.
When enabling Webhook settings, verify the operation in a test environment using a verification account before applying the settings to the target LINE Official Account.
The webhook settings made in the LINE Developers Console and LINE Official Account Manager are synchronized.
# Webhook ON/OFF and auto reply message settings
This is the combination of the Webhooks setting and the Response mode and Greeting message settings in LINE Official Account Manager.
Webhooks | Response mode and Greeting message | Setting availability |
---|---|---|
Enabled | Enabled | ✅ |
Enabled | Disabled | ✅ |
Disabled | Enabled | ✅ |
Disabled | Disabled | ❌ |
For a better user experience, settings that don't use Webhooks and the LINE Official Account Manager's Response mode and Greeting message settings aren't allowed, as this will prevent the LINE Official Account from sending messages to users.
LINE Official Account Manager's Greeting message is a message that is automatically sent when a LINE Official Account is added. Greeting message is also sent when unblocked.
# Processing flow when receiving a webhook request
Respond with HTTP status code 200
within 2 seconds after the bot server gets the webhook event.
It's recommended to desynchronize the event processing when the bot server gets the webhook request so that the processing of the webhook request doesn't delay the subsequent processing. If event processing is asynchronous, implement it so that it can be processed while maintaining the context of the event.
This image depicts asynchronized processing.
# If a problem occurs when sending a webhook request
For Messaging API channels under the certified provider, if the HTTP status code 200
isn't sent within 2 seconds after getting the webhook event, a request_timeout
error notification is sent to the channel administrator.
The error notification feature is only available for Messaging API channels that are under the certified provider.
# Other precautions
# One webhook can contain multiple webhook event objects
A webhook sent from the LINE Platform may contain multiple webhook event objects. Also, there isn't always one user per webhook, so a Message event from person A and a Follow event from person B may be in the same webhook.
Make sure the bot server can handle everything properly even when it receives a webhook that contains multiple webhook event objects. For more information about webhook event objects, see Webhook Event Objects in the Messaging API reference.
# Responding to structural changes in webhook event objects
Properties may be added to the webhook event object when there are additions or changes to the Messaging API functionality. Implement the bot server so that receiving a webhook event object with a new property doesn't cause problems. For more information about webhook event objects, see Webhook Event Objects in the Messaging API reference.
# About the header included in the webhook request
See Request headers in the Messaging API reference.
# About processing unexpected chat transmissions
You can't restrict users from sending chats and corresponding webhook events to your LINE Official Account. If a specific user sends an unexpected chat, implement the system so that the process can be changed depending on the situation.
# Notes on sending API requests
# Issuing channel access tokens
Messaging API requests use a channel access token to verify that the user has permission to use the channel. We currently provide four types of channel access tokens with different expiration dates and issuance methods.
It's possible to issue long-lived channel access tokens with extremely long expiration dates from the LINE Developers Console, but from a security standpoint, we don't recommend issuing long-lived channel access tokens. When issuing channel access tokens, we recommend using short-lived channel access tokens with an expiration date of 30 days or channel access tokens with a user-specified expiration or stateless channel access tokens.
# Reissuing channel access tokens
Short-lived channel access tokens and channel access tokens with a user-specified expiration and stateless channel access token have expiration dates, after which they're no longer available. Also, once issued, the expiration date of the channel access token can't be extended (renewed). Therefore, it's necessary to consider the remaining expiration date and build a process to reissue new channel access tokens on a regular basis.
You can issue multiple channel access tokens, but there's a limit to the number that can be issued depending on the type of channel access token. When using the Messaging API from multiple servers or systems, be sure to correctly manage the channel access tokens used by each.
For short-lived channel access tokens or channel access tokens with a user-specified expiration, after issuing a new channel access token, we recommend that you revoke the old channel access token that you no longer use. For more information, see Example of channel access token operation in the LINE Platform basics.
# Max channel access token issuance limit
The maximum issuance limits for each type of channel access token are as follows:
Type | Max issuance limit | Behavior when max limit is exceeded | Conditions under which the channel access token is invalid |
---|---|---|---|
Short-lived channell access token | 30 | Invalidate existing short-lived channel access tokens in order of issuance |
|
Long-lived channel access token | 1 | Existing long-lived channel access tokens are disabled |
|
Access token with a user-specified expiration | 30 | API error and unable to issue additional tokens |
|
Stateless channel access token | limitless | - |
|
# Message delivery request
If the message is successfully sent, an empty JSON object is returned with HTTP status code 200
(202
for the narrowcast API only).
When sending a message fails, a response body containing JSON data such as error messages is returned as Error responses.
Error messages contained in the error response aren't guaranteed and are subject to change without notice. When an error occurs, perform exception handling according to the received HTTP status code.
When you make a request to the Messaging API, save the logs of the requested API and the received response for a certain period of time. For more information on saving logs, see Save logs in the Messaging API documentation.
# Retry message delivery request
Even when there's no LINE Platform failure, these problems may occur due to the network connection status of the bot server and other factors.
- API request doesn't complete successfully
- Can't get a response from the LINE Platform properly
In such a case, if you make the same API request in succession, the user will get the same message twice if the first API request was successfully accepted. To prevent this, implement a retry key (X-Line-Retry-Key
) to safely retry requests. For more information on message sending requests, see Retrying a failed API request in the Messaging API documentation.
# Request limits
There are limits to the length of messages that can be sent by LINE bots in a single request, as well as the number of messages that can be sent within a certain amount of time.
# Text message limits
The max number of characters that can be specified in Text message is 5000.
# Request size limits
The max request size is 2MB.
# Request rate limits
The Messaging API applies Rate limits to each endpoint.
Regardless of whether you're using a production account or a test account, sending mass requests for the purpose of behavioral testing is prohibited. Don't include the LINE Platform when performing load tests on message sending.
# How to send messages
For more information about how to send messages, see the following documentation:
For more information on the expiration date of the reply tokens used in Reply messages, see Reply token in the Messaging API reference.
# Use HTTPS (TLS 1.2 or later)
Communication between the system that called the Messaging API and the LINE API server must be done over HTTPS (TLS 1.2 or later). In addition, when using the Messaging API to send an Image message or Flex Message including an Image component, the server that stores the file must support HTTPS (TLS 1.2 or later) communication.
# Dealing with high volume access
Depending on the number of users the messages are sent to, and the content of the messages, a large volume of access may be generated to URLs, images, and other content in the messages.
To prepare for such cases, use load balancing mechanisms such as CDNs or load balancers, or send messages in stages, so that the server from which the content is stored doesn't go down due to a large volume of access.
# Notes on using LINE Login
By using LINE Login, you can implement a login function that uses the user's LINE account information in your web services and native apps.
For example, by incorporating LINE Login in a web app and linking the acquired information with your company's membership information, you can send more personalized messages to users using the Messaging API.
For more information on LINE Login, see LINE Login overview.
# LINE Login authorization and verification process
The process of LINE Login for web apps (web login) is based on the OAuth 2.0 (opens new window) authorization code grant flow and the OpenID® Connect (opens new window) protocol. For more information on LINE Login for web apps, see Login flow in the LINE Login documentation.
# About callback URLs
The callback URL (redirect_uri
) is used as the Receiving the authroization code or error response with a web app URL after the user has performed authentication and authorization operations for LINE Login. The callback URL can be set in LINE Login in the channel settings of the LINE Developers Console.
For more information on callback URLs, see Setting a callback URL in the LINE Login documentation.
Up to 400 URLs can be registered as callback URLs.
You can register a URL that includes query parameters as the callback URL.
The
redirect_uri
specified at the time of authorization request is a URL-encoded string of the URL registered as the callback URL. Any query parameter can be added.- You can register
https://example.com
as the callback URL and specifyhttps://example.com?key=value
inredirect_uri
specified at the time of authorization request.
- You can register
# Get authorization code or error response in web app
When the user's authentication and authorization process is complete, the user is redirected to the callback URL.
When a user grants access to an app, an authorization code is returned. However, if the user doesn't grant access to an app, an error response is returned. For more information on authorization codes and error responses, see Receiving the authorization code or error response with a web app in the LINE Login documentation.
# Issue an access token
An access token is issued using the authorization code obtained by the authorization request for LINE Login. For more information on issuing an access token, see Issue access token in the LINE Login v2.1 API reference.
- The
redirect_uri
parameter specified when issuing an access token must be the same as the value specified during the authorization request. - Authorization codes can be used only once, regardless of whether or not an access token is successfully issued.
# Verify the ID token
An ID token is included in the payload of the token endpoint obtained by an authorization request for LINE Login with openid
specified in the scope. You can get the user's profile information by verifying the obtained ID token. For more information, see Get profile information from ID tokens in the LINE Login documentation.
# Other LINE Login APIs
By using the acquired access token, you can check the friendship between the user and the LINE Official Account, and get the user's profile information. For more information on the LINE Login API, see LINE Login v2.1 API reference.
# Linking information obtained through LINE Login with information managed by your company (ID linking)
By linking user information (user IDs, etc.) obtained through LINE Login with member information managed by the company, it's possible to deliver more personalized messages.
- LY Corporation doesn't provide a way to link user information obtained through LINE Login with member information managed by the company.
- When linking membership information, etc., design the system with security in mind to prevent spoofing.
- Set up a flow line to unlink user information of the LINE Platform and member information, etc.
- If you select Unlink from Settings > Account > Authorized apps of the LINE app, "Channel consent" of LINE Login will be withdrawn, but the association of user information won't be released. The process of linking information obtained through LINE Login with information managed by the company must be done separately by the customer.
# Add friend option
LINE Login allows you use the option to add your LINE Official Account as friend when users log in. This is called the add friend option. The LINE Official Account used for the add friend option can be set in the LINE Developers Console. For more information, See Add a LINE Official Account as a friend when logged in (add friend option) in the LINE Login documentation.
- The LINE Official Accounts you link to are limited to those related to the LINE Login channel. For example, don't link Company A's LINE Official Account to Company B's LINE Login channel, which isn't related to Company A.
- Changes in settings are reflected immediately, so operate with caution to avoid accidentally setting unintended LINE Official Accounts (for testing, etc).
- If the LINE Login channel is under the certified provider, the Add Friend (Unblock) option on the LINE Login consent screen will be selected (checked) by default.
# state verification
The state
parameter specified when requesting authorization for LINE Login is required to prevent Cross-Site Request Forgery (opens new window). Randomly generate it in your web app for each authorization request session and validate it when receiving the authorization code or error response.
# LINE Front-end Framework (LIFF)
LINE Front-end Framework (LIFF) is a web app platform provided by LY Corporation. A web app that runs on this platform is called a LIFF app.
The LIFF app lets you get LINE user IDs and other information from the LINE Platform. The LIFF application can use these to provide functions that utilize user information or send messages on behalf of the user.
For more information on the LIFF app, see LINE Front-end Framework.
# Other features
# How to set the destination browser
When accessing a URL from a chat room or from the LINE in-app browser, you can change the browser that opens the URL to an external browser by opening the URL with special query parameters. For more information on query parameters, see Opening a URL in an external browser.
# About URL schemes
We provide URL schemes that can be used in chat rooms with LINE Official Accounts. For more information on URL schemes, see Using LINE features with the LINE URL scheme.
# About channel permissions
The status of the LINE Login channel and the LINE MINI App channel is "Developing" immediately after the channel is created. To log in to LINE or access the LIFF app on a channel with the "Developing" status, you need a LINE account with admin or tester privileges on the channel.
For more information on permissions, see Channel roles in the LINE Developers Console documentation.
# Stickers and emojis available in the Messaging API
In the Messaging API, stickers are exchanged using identifiers such as package IDs and sticker IDs.
# Send stickers via the Messaging API
For more information about the sticker that can be sent via the Messaging API, see Stickers in the Messaging API documentation.
# Check the sticker sent by the user
When a user sends a sticker to the LINE Official Account, the package ID and sticker ID of the sent sticker will be sent as a Webhook message event.
We don't disclose the mechanism to get the image of the sent sticker using the sticker ID included in the received Webhook event. We provide this service only when our Technology Partner (opens new window) (only available in Japanese) creates a chat tool (CRM tool, etc.) that allows direct interaction with the user, or when LY Corporation deems it appropriate. Contact our representative for details.
# Sending LINE emojis
You can send LINE emojis when you send a text message. For more information on LINE emojis, see LINE emoji in the Messaging API documentation.
# Getting LINE emojis
When a user sends a LINE emoji to the LINE Official Account, it is stored as an array in the emojis object in the text object of the message event.
- The default LINE emojis sent from LINE for Android won't be included.
- Unicode-defined emojis and older versions of LINE emojis may not be retrieved correctly.