Upload
dhruv-suri
View
24
Download
3
Embed Size (px)
Citation preview
LINE株式会社
LINE BusinessConnect
Operational Guidelines Revised Monday, December 15, 2014
Introduction
2 ©LINE Corporation
Basic rules governing use of the LINE BusinessConnect service are set forth in the following agreements.
• LINE Corporate Service Basic Agreement
• LINE Corporate Service LINE Official Account Agreement
• LINE Corporate Service LINE BusinessConnect Agreement
Companies can apply for BusinessConnect use by entering into the above agreements, and then completing the separate
LINE BusinessConnect Application Form.
These guidelines are legally binding as part of the LINE Corporate Service LINE BusinessConnect Agreement, and parties
entering the agreement must abide by the stipulations contained within the guidelines as well.
Moreover, these guidelines also cover special considerations not contained within the relevant agreement, as well as
stipulations contained within the agreement requiring extra care. Please understand that these guidelines may change when
new features are added, etc.
* This resource may not be shared with third parties without consent.
About LINE BusinessConnect
©LINE Corporation 3
Overview of Services Offered
©LINE Corporation 4
Full Account
Test (Development) Account
LINE developers LINE Official Account MANAGER
Companies creating LINE BusinessConnect (simply BusinessConnect below) accounts are offered the following services.
Account actually friend-
able by real users.
Development and testing
use account only friendable
by project members.
LINE developers is a website with
information necessary to manage
BusinessConnect development.
Administrative page used to operate the
account (P6)
Account Administrative Website
LINE developers is a site used to manage information on necessary specifications, as well as Channel information, for the
development of apps and services linked with BusinessConnect and LINE. Content is separated into 2 overall categories:
“Documents” and “Channels”.
Documents Channels
LINE developers
©LINE Corporation 5
The Documents page contains information on
specifications, including for LINE’s API. Please refer to
documents contained on this stage when implementing
the BusinessConnect system.
Channels are used to create gateway servers needed to
connect your company with LINE, and each account needs
to have 1 Channel issued. You can check information
related to your Channel and change settings under the
Channels category.
LINE Official Account Manager allows you to do the following.
LINE Official Account Manager
©LINE Corporation 6
What You Can Do with API-based Official Accounts
and BusinessConnect Accounts
What You Can Do Only with API-based Official
Accounts
・Set up greeting sent to friending users, and turn ON/OFF
friend API receipt.
・Set up auto-response and keyword messages, and turn
ON/OFF message API.
・View Statistical Data (Number of Friends, Number of Current
Valid Friends, etc.)
・(Administrator only) Give login privileges.
・Batch send messages
・Post to Timeline
・Create and send PR and research pages used in conjunction
with batch messages and Timeline posts.
LINE BusinessConnect Structure
Talk Server Channel Gateway Server
LINE App
BusinessConnect Server
LINE Platform
Via API
Receiving Operation / Message
(Called Events)
Calling API
Users sends message to company
Company sends message to user
API info sent from Channel Gateway Server to BusinessConnect.
API info sent from BOT server to Channel Gateway server.
©LINE Corporation 7
• Talk Server・・・ Server tasked with sending/receiving messages, etc.
• Channel Gateway Server(GW Server) ・・・ Server tasked with sending info received from talk server to BusinessConnect server, and vice versa.
Channel required for use.
• BusinessConnect Server(BC Server) ・・・ Server set up to allow company to send and receive requests from LINE.
• Receiving Operation ・・・API info for friending, blocking, etc.
• Receiving Message ・・・ Message sent by user to BusinessConnect account.
• Request ・・・・ Sending/receipt of JSON-format API info from GW server to BC server, or BC server to GW server.
• Event ・・・ Title of single operation or message including in JSON commands.
• Calling API ・・・ API request sent from BC server to GW server.
BusinessConnect Operational Rules
©LINE Corporation 8
BusinessConnect Operational Rules
9 ©LINE Corporation
If you are planning to implement new features through a BusinessConnect account, please make sure to disclose relevant
information regarding these plans to us in advance before finalizing your contract. Contracts will be finalized once we have
checked the viability of planned features, as well as whether planned features violate any agreements or operational rules.
1. Advance Disclosure of Proposed Plans
Please take necessary precautions and measures, such as removing administrator privileges from employees who have left
your company or changed departments, to ensure that sensitive information is not leaked to outside parties. The following
lists the minimum required measures in such cases:
・Deletion of LINE Official Account Manager administrator and viewing privileges (both test and real versions)
・Deletion of LINE developers administrator and viewing privileges (both test and real versions)
・Deletion of test-use accounts from relevant individual’s devices.
2. Management of Administrator Privileges
Account Deletion Method
1. Block the relevant account
2. Slide the relevant account’s chat banner from the chat list to the left. Then tap Delete.
3. Go to the More tab, then Settings > Friends > Blocked Users and tap the Edit button found next to the relevant account.
4. Tap Delete.
Please do not forget to delete the actual chat history of the relevant account as well.
BusinessConnect Operational Rules
©LINE Corporation 10
1. You must obtain the consent of LINE users when connecting user information to your members’ information, client data, in-site action
records, etc.
2. Please take any necessary precautions and measures to handle user personal information, and make obtained user information available
to relevant users at all times (by creating and abiding by a privacy policy listed on a website, etc.)
3. Information requiring a high level of security, including passwords, passcodes, credit card information, etc., must not be obtained
through chats.
4. User information, including LINE IDs, registered email addresses and phone numbers, etc., cannot be obtained as if for LINE registration
purposes through your BusinessConnect account or website.
5. User identification codes (MIDs), uniquely given to each LINE user, must not be listed or used on your account, website, URL or source
code so as to be viewable by third parties. If you choose to save MIDs, they must always be encrypted and may not be saved in plain
text.
6. Obtained MIDs and other LINE-related information must be used only for the account through which it was obtained, and actions such
as name collating across multiple accounts are prohibited.
7. After being blocked by a user, please delete user information obtained from the relevant user, including MIDs and nicknames, and make
every effort not to store unnecessary information.
8. We ask that you take all necessary precautions to ensure that any other information relevant to a user’s privacy is securely handled
when obtained or used.
3. Regarding the Obtainment of User-Related Information
Please ensure that you abide by the following rules when obtaining user-related information (personal info, LINE user info,
member info, client data, etc.)
BusinessConnect Operational Rules
11 ©LINE Corporation
4. Sending of Consent Text when Supplying User Info
As user information is passed directly to companies using the BusinessConnect
service, the obtainment of user consent, or the sending of text constituting
consent, is required. Please refer to the following for the timing and content of
such consent-related messages.
(Account Name) is operated by (Company Name).
Please check the following for rules and regulations regarding the use and
handling user information provided by LINE or otherwise obtained, and
understand that continued “friending” of this account constitutes consent to the
information contained in the link below.
http://me2.do/xcM24DiY
User Info Obtainment Consent-Related Message (include URL)
●For Newly Created Accounts
Please send the consent-related message when a user adds the account.
●For Existing Account Holders Switching to an API-Based Account
Please complete the following 2 actions
・Send the consent-related message when a user adds the account.
・Batch send consent-related message right after switching to API-based account.
©LINE Corporation 12
BusinessConnect Operational Rules
5. Content of Messages Sent Via API
・Abiding by App Market Regulations
LINE is a service provided through app markets available on smartphone OSes, such as iOS and Android, and must abide by the relevant
regulations of each market. If any message sent is deemed to be in violation of relevant regulations, we reserve the right to issue
immediate warnings or to suspend service in certain cases. Particular examples of strictly prohibited actions are the inclusion of direct
links to external apps or external app download pages (on App Store, Google Play, etc.)
・Message Resale
Excluding certain cases in which we provide consent, accounts and message content may not be resold.
・Message Content with the Potential to Offend Users
Messages containing content with the potential to offend users, such as messages that blatantly depict sensitive body areas,
or are overtly sexual or revealing of skin, are prohibited.
BusinessConnect Operational Rules
13 ©LINE Corporation
6. Pre-Release Checks for BusinessConnect Accounts
BusinessConnect accounts must begin operation only after passing each and every required condition set in the Checklist
provided by us in order to ensure safe conduct and the avoidance of security related issues.
Please check to see that you have cleared every condition set forth in the Checklist, and only sign and submit it once you
have done so. We will conduct another confirmation on our side, so please continue account release preparations during this
time.
7. BusinessConnect Account Operation
We will conduct regular checks to see that the above Checklist is being abided by even after a BusinessConnect account is
released and begins operation, and will issue warnings to account holders that do not meet the required conditions. We ask
that parties receiving warnings work to resolve the relevant issues as soon as possible.
8. Contract Termination
Please immediately cease operation of your account after your contract has ended, and delete any and all information
obtained from users, including MIDs and nicknames, as well as information gained via LINE chats, and also make sure to
dispose of any relevant documents and other materials obtained from us. However, if users have clearly consented to the
continued storage of certain information on your side, deletion of such information will not be required. Please send written
notification, including by email, once the disposal process has been completed
BusinessConnect Development How-To
and Key Points
©LINE Corporation 14
BusinessConnect Development How-To
©LINE Corporation 15
What to Do Before Starting Development
You need to complete the following steps before starting development.
1. Obtain BusinessConnect server and SSL certification, and set up event endpoint URL
2. Submit completed “LINE BusinessConnect Account Creation Application” to LINE.
3. Create BusinessConnect Channel and Account (done on LINE side)
4. Complete preparations to receive event requests from BC server. -Have received requests return the status code 200 (explained later)
5. Friend account to check whether requests are being properly received by the BC server.
6. Begin development.
Please check to see that you’ve received the following LINE-issued materials before beginning development.
Materials Provided by LINE
• LINE BusinessConnect Service Introduction Material
• LINE BusinessConnect Operational Guidelines (this resource)
• LINE BusinessConnect Server Security Guidelines
• LINE BusinessConnect Security Check List
• LINE BusinessConnect LINE developers Manual
Documents Sent by You
• LINE BusinessConnect Account Creation Application
• LINE BusinessConnect Resource Check List
Materials Provided by LINE
* Event endpoint URL
Endpoint URL used when sending
requests from GW server to BC server.
What to Do During Development
©LINE Corporation 16
A) Creation of Connection with GW Server - Returns HTTP status code 200 (OK) to received requests.
- Automatically updates Channel access token,
B) Secure Connection and Server Environment - SSL-based connection.
- Environment constructed according to Security Guidelines.
C) Preventing Invalid Requests from Sources Outside of LINE - Signature validation of received requests.(Signature Validation)
D) Measures to Handle Large Concentrated Request Volumes - Hold stress tests to check durability against large access volumes.
E) Other Important Points - Processing of single requests containing multiple events.
- Handling duplicates when messages resent.
We ask that companies utilizing BusinessConnect create, at a minimum, the systems below in order to protect user information and to
ensure smooth communication with users through LINE.
A) Proper Network Connection with GW Server
©LINE Corporation 17
A-1. Returning HTTP Status Code 200 (OK) to Received Requests
Please first set up the BC server so that it promptly returns the status code 200 once receiving a request. Please aim to have status
codes returned within 1,000 milliseconds (1 second). If a response is not sent within 5 seconds, a slow response error alert will be
triggered, and if a response is not sent within 10 seconds, or a response other than status code 200 is sent, the request will be
resent by the GW server. We recommend the following setup procedure to ensure prompt and accurate status code responses.
A-2. Automatic Refreshing of Channel Access Token
When a request is sent from you to the GW server, the GW server will authenticate each request using the Channel access token issued to
each Channel and contained within the request header. An expiration date is assigned to the Channel access token, and you will no longer
be able to send requests once this access token has expired. Therefore, please construct the BC server so that it regularly and
automatically refreshes the access token. * Please refer to the RESTful API’s Reissuance of Access Tokens for API reference on refreshing
access tokens.
Recommended Procedure
1. Receive JSON request on BC server.
2. Enter JSON content into DB, memory, etc.
3. Return status code 200 to GW server
4. Conduct signature validation, duplicate checks, etc. (explained later)
5. Individually process event within code if request is successfully validated as per item 4.
B) Secure Network and Server Environment
©LINE Corporation 18
B-1. Network Environment Supporting SSL
BusinessConnect requires that the network environment between the GW server and BC server supports SSL. In addition, as we do not support self-created certifications, please ensure that you procure an SSL certificate from the relevant agency in advance of registration.
B-2. Network Constructed According to Security Guidelines
The following materials contain the security standards required when implementing the BusinessConnect service. We ask all developers to abide by the security guidelines contained below and to prepare an environment that meets or exceeds all security standards before beginning development.
• LINE BusinessConnect Server Security Guidelines
LINE BusinessConnect Server Security Checklist
SSL
GW Server BC Server
Via GW Server
C) Preventing Unauthorized Requests Not from LINE
©LINE Corporation 19
BC Server
A signature is included in sent requests. The BC server calculates a separate signature using received request signature, and
checks to see whether or not this signature matches the one contained in the header in order to validate it.
Please see relevant documents for how to calculate signatures. Signature keys (channel secret) can be checked from the
LINE developers website. Please take ample care in handling signature keys, etc. so as to avoid unauthorized access.
Via Server
Outside LINE
?
Authorized Request
Unauthorized
Request
Match
No Match
Process request as
normal.
Dispose of without
processing.
C-1. Signature Validation of Received Requests
API
API
Message from
LINE App
Unauthorized
Access
Calculates separate
request signature to
check validity of header
signature.
D) Countermeasures Against Large Concentrated Access Volumes
©LINE Corporation 20
D-1) Implementation of Stress Tests that Assume Large Access Volumes One special feature of LINE-based media is that user access may sometimes greatly increase over concentrated periods. Such circumstances may lead the BC server to become inundated with requests it cannot fully process, resulting in delays or the inability to send out response messages. Please conduct stress tests during the response message development stage and take necessary countermeasures against such concentrated access volumes.
Please also inform us of the following information before and after implementing a stress test. • Expected Maximum Access Volume • Test Method • Test Results (Average response speed, occurring errors, etc.)
Caution ・No stress test environment is provided from the GW server, so please prepare this on your side. ・If the BC server is unable to fully handle all received requests, the GW server queue may also become inundated with requests unable to fully processed by the BC server. If the GW server becomes heavily inundated with such requests, this may negatively affect other Channels, and in such cases we may have no choice but to delete backed up requests.
• Right after account is released. • Right after releasing sponsored stickers.
In terms of peak time periods, access volume tends to spike around 12 noon and between 5 pm and midnight each day.
Circumstances Where High Access Volumes are Likely
• Right after sending batch message to users. • When covered by news, in TV, or other media.
E) Other Important Points
©LINE Corporation 21
E-1. Processing of Requests Containing Multiple Events
E-2. Handling Duplicate Processing of Resent Requests
Requests do not always simply contain 1 event. When a large volume of messages are simultaneously sent, or a large number of users friend the account, 1 request may contain multiple events, and vice versa, so please construct your system with such multiple event-carrying requests in mind.
If more than 10 seconds pass before the status code 200 is returned, the GW will likely resend the same request. If this resent request is processed as if it were the original request, the same message may be sent to the same user more than once. Please set up the server so that it is able to determine whether a request has already been processed, and disposes of requests if so.
Recommended Procedure
1. Enter JSON content into DB/memory after receipt of request, then return status code 200 (refer to previous page)
2. Check Event “ID” attribute shown at the very top of the JSON code.
3. Dispose of data if the request has already been processed.
* The “ID” attribute is also contained in the content attributes of message requests, so please ensure not to mistake it.
The following points can also lead to system trouble if not handled properly in advance.
Recommended Request Processing Flow
©LINE Corporation 22
Disposal
Resent
Over 10 seconds pass
Disposal
Status Code 200 Returned [A-1]
Signature Validation[C-1]
Check for Duplicates(ID) [E-2]
Relevant Operation/Message Processed
LINE’S GW Server Your BC Server
No Match
Match
Yes
No
Signature matches?
Request Processed
Before?
JSON Request Received Request Sent
Entered into DB/Memory, etc.
Timeout Judgment
Status Code 200 Received
Request Transmission Processing Complete
Aim for 1
Second
or Less
GW Server → BC Server Error Alerts
©LINE Corporation 23
When a request is sent from the GW server to the BC server and the BC server experiences some type of error, an error alert will be sent by email as well as displayed on LINE developers. Please check the causes of relevant errors promptly after receiving an alert, and take measures to resolve the issues.
Email Recipients ・People with CHANNEL_EDITOR privileges under relevant Channel Roles within LINE developers. ・Mailing list registered as the Contact Mailing List Address under the relevant Channel’s Basic Info Page
Subject [LINE Developers] BusinessConnect: Errors have been detected - <Channel Name>
Examples of Error Notifications
SLOW_RESPONSE
(Response time > 5000ms)
Sent when 200 response takes more than 5 seconds. Message response and other
processing may be experiencing delays.
REQUEST_TIMEOUT
(Response time > 10s)
Sent when 200 response takes more than 10 seconds. Message processing will be
deemed unsuccessful and request will be resent.
ERROR_STATUS_CODE 503 BC server may be unable to receive requests due to access overload.
ERROR_STATUS_CODE 500 The BC server may experience an error for some reason.
Error Reference
Page https://developers.line.me/channels/apibot/<Channel_ID>/errors
There are a number of other error types. Each alert signifies some sort of problem, so if received, please check to see what is causing the issue and take necessary measures to resolve it.
Related Features
©LINE Corporation 24
Sending Multiple Messages
©LINE Corporation 25
A Multiple Message feature exists that allows multiple messages (speech bubbles) to be sent in 1 request. While 3 speech bubble
messages sent as 3 requests would be counted as 3 messages in your allotted message count, using this feature would have the request
counted as only one allotted message.
POST /v1/events HTTP/1.1
Host: channel-apis.line.naver.jp
Content-type: application/json; charset=UTF-8
X-LINE-ChannelToken: YOUR_CHANNEL_ACCESS_TOKEN
{
"to":["u5912407b444e54885d00111f7b0ce375"],
"toChannel":1383378250,
"eventType":"140177271400161403",
"content": {
"messages": [
{
"contentType": 1,
"text": "First message"
},
{
"contentType": 2,
"originalContentUrl": "...",
"previewImageUrl": "..."
},
...
]
}
}
POST /v1/events HTTP/1.1
Host: channel-apis.line.naver.jp
Content-type: application/json; charset=UTF-8
X-LINE-ChannelToken:
YOUR_CHANNEL_ACCESS_TOKEN
{
"to":["u5912407b444e54885d00111f7b0ce375"],
"toChannel":1383378250,
"eventType":"138311608800106203",
"content":{
"contentType":1,
"toType":1,
"text":"First message"
}
}
POST /v1/events HTTP/1.1
…..
{ … }
POST /v1/events HTTP/1.1
…..
{ … }
Multiple Message Transmission Standard Message Transmission
3 speech bubble messages delivered to user,
counted as 1 allotted message per user.
3 messages delivered separately to each user,
counted as 3 messages per user.
Turning ON/OFF Friend Adding and Message API
©LINE Corporation 26
LINE Official Account Manager Account Settings > Basic Settings Page
Auto-Response Message or New Friend Greeting Page Top
You can set the friend adding and message API ON or OFF using the LINE Official Account Manager. Settings for Auto-Response Messages and New Friend Greeting can each be set in 3 different ways, shown below.
You can stop/restart requests for received messages from the auto-response message settings screen.
You can stop/restart friend adding for received operations from the New Friend Greeting settings screen.
API ON/OFF Settings Options
©LINE Corporation 27
Each setting can be utilized in the following ways.
① Select “Don’t Use”
② Select “Use” Without Checking “Receive ◯◯ Simultaneously via API”
③ Select “Use” With “Receive ◯◯ Simultaneously via API” Checked
Selecting “Don’t Use” turns off the New Friend Greeting and Auto-Response Message features from LINE Official Account Manager, and messages are instead sent from the BC server via the API. This is the default setting for BusinessConnect. Example: When you wish to send individual messages to users (standard BusinessConnect usage method).
Stops API and sends responses using the New Friend Greeting and Auto-Response Message registered on the LINE Official Account Manager. Example 1: When you want to batch send the same message to users using New Friend Greeting, etc. Example 2: When the BC server is experiencing an issue and you want to temporarily stop API-based transmissions.
Comprehensive method that has responses sent using the New Friend Greeting and Auto-Response Message registered on the LINE Official Account Manager, but API info also sent simultaneously to BC server. Example: When you are fine with fixed message responses, but you want to obtain MIDs for use in sending specific users messages at a later time.
Caution: ・Please note that the New Friend Greeting message will be sent again to users who remove their block on your account when the feature is set to ② or ③ above on your BusinessConnect account.
Sticker Usage Method
©LINE Corporation 28
Using BusinessConnect, stickers are sent as ID information which itself cannot be used to discern the particular sticker. The following rules have also been established as each sticker is sent under the rights of each sticker publishing company.
When Sent from You to Users
Companies can send the following stickers. A. 4 Default Sticker Sets (Moon, James and Brown, Cony, Cherry Coco, Huge Emoji) B. Stickers you have license ownership of (Sponsored stickers, etc.) The chart for Stickers in the A group is provided by LINE. Please contact your representative for more information. If you want to send stickers from the B group, please contact us with the relevant sticker names and the days they were released (if you wish to use images, please prepare those yourself). You can also use stickers even after 6 months has passed since they first became available.
Displaying Stickers Sent from Users to You
Please contact your representative, who can provide you with a URL scheme allowing you to obtain sticker images.
Caution Please be aware of the fact that usage is prohibited in circumstances like those below as you will be deemed to have engaged in secondary usage, which violates the license agreement. ・Use of received sticker images on TV programs, websites, and other media. ・Use of images for business purposes beyond the scope of BusinessConnect-related services.
How to Use Emoticons
©LINE Corporation 29
Sending and Receiving Emoticons
Emoji available on LINE in LINE versions up to 4.1.x. Around 170 emoticons. Emoticon data is encoded using Unicode for sending and receipt. Please inquire with us for images and Unicode charts.
Emoji type appearing on LINE since version 4.2.0, with more new types added continuously. Not compatible with BusinessConnect. You’ll see text in place of Sticons sent by users, such as (full moon), (corn), (doberman), or (airplane).
LINE offers two types of Emoji. BusinessConnect is only compatible with the type referred to as “Emoticons.”
Emoticon (Supported with BusinessConnect) Sticon (Not Yet Supported on BusinessConnect)
Channel Web Applications
©LINE Corporation 30
Channel Web Applications (CWA) refers to a feature that allows you to use web-view based apps created in-house within the LINE app. With
this feature, you can display specified pages by loading them inside of the LINE app. This feature is unique in that it is used within the LINE
app, meaning you can obtain LINE user information and match it appropriately to your own content.
Advance application is required to use the CWA feature. Please express your interest in the feature when submitting account
application documents.
URL Rule: line://ch/[Channel_ID]
Opens Your Web-View
App in LINE
For detailed specs and setup methods, please check the items listed under JavaScript SDK in LINE developers
●Main Usage Examples
With CWA, you can obtain LINE user info
(MIDs) using an in-house developed page.
The following are some main ways this
feature is utilized.
・Questionnaires matched with user info
・UI difficult to use through text-based
input (seat and product selection, etc.)
・Account verification
Etc.
CWA Structure
©LINE Corporation 31
CWA reads set
URL
https-based Page
Creation
URL set via LINE
developers
Caution ・CWA features may only be used within the scope of BusinessConnect account operation. Promotions aimed at users are prohibited outside of LINE chats and Timeline posts (e.g. from external sites, etc.) ・Users with iOS versions 8 and above may experience malfunctioning on LINE versions 4.7.x and below.
Encrypted user
information (MID)
obtained from
cookies
Histories
obtained from
your page
matched with
member
information
Info, etc. sent to
user
Decryption
Displayed on LINE app
Confidential
RECOMMENDATIONS FOR
SYSTEM IMPLEMENTATION
32 © LINE Corporation
Recommendations for Operation and Development - Part 1
33 © LINE Corporation
1. Showing the help menu
Please design your official account so that the user is able
to bring up a help menu when needed.
- Display the menu when the user enters “help” or “menu”.
- Display the menu any time the user sends a message.
Please see the image on the right for an example.
2. Make keywords short and simple
You can reduce the chance of the user making a mistake
when entering a keyword by keeping the choices as short
as possible.
Show the help menu any time
the user sends a message.
3. Handling keyword typos
If the user does not receive some sort of reply from you
after sending a message, they may be unable to tell if their
action was successful or not. Please think of an appropriate
reply message and a way to handle messages sent
incorrectly from the user.
Recommendations for Operation and Development - Part 2
34 © LINE Corporation
5. Editing sent messages
It is possible that the user may make a mistake when
sending messages to your account. If the mistake is related
to important information such as an order or reservation,
please include a way to check for and correct errors in sent
messages in order to help reduce occurrences of this
problem.
4. Cancel message settings
Allow the user to stop receiving automatic messages (such
as regularly scheduled messages or notices for new
products) whenever they want.
Example – UI for canceling
messages received automatically.
6. Keep terminology consistent
In order to avoid confusing the user, we recommend you
take careful considerations to provide the user with text
that contains no spelling errors, inconsistent terminology or
capitalization, or potentially difficult to understand
abbreviations.
Example: Basic Transition Diagram for LINE Fortune-Telling (wireframe)
35 © LINE Corporation
Thanks for friending LINE Fortune-Telling! We can tell you have a lot of fun in store! Powered by Media Kobo
Welcome Message for New Friends
We’ll send you your daily horoscope. First, tell us your birthday in a 4 digit format. Example: July 27 would be “0727”.
0727
*Please include the exemption of liability for handling additional personal information with BusinessConnect here.
Correct request
Bad request
Hello Please send us your birthday using only 4 digits. That’s the only way we can understand.
Error Message
Reply Message for Fortune Results
Daily Horoscope for Leo ----- Better butter up that courage, because you’re going to need it today. Good things are... See the rest of your fortune here: http://nav.cx/1bryq7
Do you want us to send you the daily horoscope for Leo at a certain time? Reply with either “yes” or “no”.
no
We’re having trouble understanding what you mean. If you want to set fortune alerts, enter “yes”. If you’d rather not, just say “no”. Thanks!
Bad requests
Whatever man
Error Message
You’re all set! Don’t get sad if we’re a little late sending you messages. 1. Today’s Fortune -10:00am LEO
There’s a lot more to us than just daily horoscopes. Send us one of the keywords listed below to learn more! Fortune – Today’s fortune Work – Predictions for your job Love – Predictions for your love life Help – Brings up the help menu You might find it easier to set alerts for LINE Fortune-Telling. Enter “help” to learn more.
yes
Correct requests What time would you like us to send you your fortune? Please reply using a 4 digit format. Example: 9:30 AM would be “0930”. Round times to the nearest 15 minute interval.
Settings for Message Delivery Time
End Session|Return to Menu
Settings Complete
1000
Correct request
Bad request
Hello
Please try again using a 4 digit format. Example: 9:30 AM would be “0930”. Round times to the nearest 15 minute interval.
Error Message
Daily Horoscope for LEO ★---- Better bring a bucket, because it’s raining money today. If you can’t buy happiness, you might try renting it! See the rest of your fortune here: http://nav.cx/1bryq7
Fortune Alert
Added as a Friend
Messages are sent at the specified time.
This is only an example. We are not trying to suggest
that the above diagram is the perfect design for
everyone. Please think of the needs of your users,
then find the best design method that works for your
company.
This wireframe for LINE Fortune-Telling details the processes involved from adding the account as a friend to receiving alerts
for regularly updated fortunes.
Frequently Asked Questions
©LINE Corporation 36
FAQ
©LINE Corporation 37
Category Question Answer
Account Issuance Can an account be issued even if the endpoint URL has not yet been decided?
Accounts cannot be issued in this case as no place to accept requests will exist. Accounts are only issued once the endpoint URL has been decided.
Do endpoint URLs of test-use accounts also need https?
We allow you the use of http for test-use accounts, but responsibility is placed on you for this decision.
Is mailing list information required? Please include mailing list information if possible so that we can contact you if a mobile network issue occurs or to provide important information.
Are secondary and tertiary points of contact necessary?
Yes, these are necessary when registering for a real-use account.
Handling Obtained Information
Are user MIDs ever changed for any reason?
A user’s MID will never change as long as they do not delete their account. A user will however be issued a new MID if they create a new account after deleting an old one.
Is it possible to receive a list of all user MIDs who’ve friended my account?
We do not provide MID lists.
Can information on the number of friends be obtained?
You can view this from the account manager page provided by LINE for official accounts. This information cannot be obtained via API.
Can information on users who’ve blocked the account be obtained?
Yes. An operation type called opType: 8 will be sent when a user blocks your account.
What happens when messages are sent to MIDs of users who’ve blocked/deleted the account?
The sent request will have a response returned to the BC server stating “successfully sent”, but the user will not actually receive it. Messages not actually sent are not included in the calculation of allotted messages used.
FAQ
©LINE Corporation 38
Category Question Answer
Handling Obtained Information
After receiving a block notification, exactly what is considered user information needing to be deleted?
Information Considered User Information: User info (MIDs, nicknames, icon pictures, status messages) and user info obtained through chats (personal info, attributes, etc.), as well as chat histories received from users, etc. Information Not Considered User Information: Information obtained by user entry on your website after using a link, info saved in a format unusable to determine user identities, etc.
Receiving Operations / Messages
What is the maximum characters receivable in a message from users?
There is a maximum of 10,000 characters.
You stated that certain requests contain multiple messages, but when does this actually occur? How do descriptions look in such cases?
Multiple messages may be sent together to reduce server load when users send a large volume of messages in a short period of time. The code will display as the following in such cases. {"result":[{1ST EVENT},{2ND EVENT}, ...]}
Calling API What is the maximum number of MIDs that can be included in the “to” section of 1 request (the max. no. of users reachable with 1 request)
Up to 150 MIDs can be included in the “to” section of 1 request. 1 MID counts as one message for billing purposes.
When image, audio, and video content are sent, are these then stored on my server, after which the user accesses them?
Correct. The URL will directly access the API designated URL to access content. However, data once accessed will be stored on the user’s device, so they will not re-access the same data unless they delete it first.
How long does image, audio, and video content need to be stored on my servers?
We cannot give a general response as this depends on how you intend to use such content. Users may not immediately access such content, so its best to store it for a certain period of time.
FAQ
©LINE Corporation 39
Category Question Answer
Calling API Do old access tokens become invalid after updating the access token?
Old access tokens become invalid after updating an access token through the API. Please temporarily stop sending messages and take other precautions so as not to cause errors after updating a token but before the new token setup is complete.
Connection between Servers
How fast are messages sent and received?
We cannot give a definitive response to this question as it depends on the state of the talk, GW, and BC servers at the time.
Is it okay to send responses to the GW server during stress tests?
Please refrain from placing load on our GW servers during stress tests.
Is it possible to create virtual user accounts for testing?
Virtual user accounts cannot be created.
Please contact the following email address for any additional questions.
API Specifications
©LINE Corporation 40
The information contained in the following pages is for reference only, and is subject to future changes.
Please make sure to check LINE developers documents for the latest information.
API Properties of Received Messages
41 © LINE Corporation
{"result":[ { "from:"u2ddf2eb3c959e561f6c9fa2ea732e7eb8", "fromChannel:"1341301815", "to":["u0cc15697597f61dd8b01cea8b027050e"], "toChannel":"1441301333", "eventType":"138311609000106303", "content": { "location":null, "id":"325708", "contentType":1, "from":"uff2aec188e58752ee1fb0f9507c6529a", "createdTime":1332394961610, "to":["u0a556cffd4da0dd89c94fb36e36e1cdc"], "toType":1, "contentMetadata":null, "text":"Hello, BOT Server!" }, ... ]}
Sample Code
The following sample is the JSON string received when a message is sent from a user.
Please see LINE Developers “BOT Server API” > Receiving Messages/Operations > Receiving Messages.
API Properties of Received Messages
42 © LINE Corporation
The details of each property are as follows.
Please see LINE Developers “BOT Server API” > Receiving Messages/Operations > Receiving Messages.
Property Name Value (Example) Description
from “u2ddf2eb3c959e561f6c9fa2ea732e7eb8″ Fixed value.
fromChannel “1341301815″ Fixed value.
to “u0cc15697597f61dd8b01cea8b027050e” MID assigned to bot server channel.
toChannel “1441301333″ Channel ID of bot server.
eventType “138311609000106303″ or “138311609100106403″ Data type identifier.
content {…} Actual content of the information sent. Details in the table below.
Property name Type Description
id String Message identifier.
contentType Integer Value representing the message type.
from String MID of the user who sent this message.
createdTime Integer Date and time this request was created, given in milliseconds since 00:00 on January 1, 1970.
to Array of String MID of message recipient.
toType Integer Type of message recipient (1=user).
contentMetadata Object Detailed information about this message.
text String Text sent.
location Object Location data. Included when message is a location information message.
Received Messages: Detailed Information About “location” and “contentMetadata”
Properties
43 © LINE Corporation
Property Name Type Description
title String A string saying “location information”.
address String Address.
latitude Decimal Latitude.
longitude Decimal Longitude.
phone String Phone number.
The API properties when receiving location information (“location”) and stickers (“contentMetadata”) are as follows.
Properties of “location” Object
contentType value Property name Type Description
8 (Sticker) STKPKGID String Sticker package ID.
STKID String Sticker ID.
STKVER String Sticker version.
STKTXT String Sticker text.
10 (Contact Information)
mid String Contact’s MID.
displayName String Contact’s display name (nickname).
Properties of “contentMetadata” Object
Please see LINE Developers “BOT Server API” > Receiving Messages/Operations > Receiving Messages.
API Properties of Received Operations
44 © LINE Corporation
Property name Type Description
revision Integer Revision number of this operation.
opType Integer Type of operation (only 4 = add friend is currently supported).
params Array of Strings
MID array.
{"result":[ { "from:"uefb896062d34df287b220e7b581d24a6", "fromChannel:"1341301815", "to":["u0cc15697597f61dd8b01cea8b027050e"], "toChannel":"1441301333", "eventType":"138311609100106403", "content": { "params":[ "u0f3bfc598b061eba02183bfc5280886a", null, null ], "revision":2469, "opType":4 } }, ... ]}
Sample Code
The following sample shows the code and API properties received when a user performs an
operation with the account. Currently, only the “add friend” operation is supported.
Receiving Operations Properties
Please see LINE Developers “BOT Server API” > Receiving Messages/Operations > Receiving Messages.
API Specifications When Sending Messages
45 © LINE Corporation
Property Name Value
to MIDs of receiving users. Up to 150.
toChannel Fixed value “1383378250”.
eventType Fixed value "138311608800106203“.
content Object with the actual content being sent (differs by message type).
POST /v1/events HTTP/1.1 Host: channel-apis.line.naver.jp Content-type: application/json; charset=UTF-8 X-LINE-ChannelToken: YOUR_CHANNEL_ACCESS_TOKEN { "to":["u5912407b444e54885d00111f7b0ce375"], "toChannel":1383378250, "eventType":"138311608800106203", "content":{ ... } }
Sample Code
When sending messages, the following code will be generated.
Message Sending Properties
Endpoint URL https://channel-apis.line.naver.jp/v1/events
HTTP Method POST
Required Request header
Content-Type: application/json; charser=UTF-8 X-Line-ChannelToken: Channel Access Token
Common API Specifications for Bot Servers
Please see LINE Developers “BOT Server API” > Calling APIs > Sending Messages.
Sending Messages: Properties by “content” Type
46 © LINE Corporation
content Property name Type Description
Text contentType Integer Fixed value 1.
toType Integer Type of recipient specified in the “to” property (1 = user).
text String String that you want to send. Max. 1024 characters.
Image contentType Integer Fixed value 2.
toType Integer Type of recipient specified in the “to” property (1 = user).
originalContentUrl String Image URL. Only JPEG format is supported. Max. resolution is 1024x1024.
previewImageUrl String Preview image URL. Only JPEG format is supported. Max. resolution is 240x240.
Video contentType Integer Fixed value 3.
toType Integer Type of recipient specified in the “to” property (1 = user).
originalContentUrl String Video URL. MP4 format is recommended.
previewImageUrl String Preview image URL.
Sound contentType Integer Fixed value 4.
toType Integer Type of recipient specified in the “to” property (1 = user).
originalContentUrl String Sound file URL. M3A format is recommended.
contentMetadata.AUDLEN String Sound file length in milliseconds.
The information in the “content” property is as follows.
Please see LINE Developers “BOT Server API” > Calling APIs > Sending Messages.
Sending Messages: Properties by “content” Type
47 © LINE Corporation
content Property name Type Description
Location contentType Integer Fixed value 7.
toType Integer Type of recipient specified in the “to” property (1 = user).
text String Text explanation location (name or address).
location.title String Same text as “text” property.
location.latitude Decimal Latitude.
location.longitude Decimal Longitude.
Sticker contentType Integer Fixed value 8.
toType Integer Type of recipient specified in the “to” property (1 = user).
contentMetadata.STKID String Sticker ID.
contentMetadata.STKPKGID
String Sticker package ID.
contentMetadata.STKVER String Sticker version.
The information in the “content” property are as follows.
Please see LINE Developers “BOT Server API” > Calling APIs > Sending Messages.
Rich Message API
48 © LINE Corporation
You can send rich messages using the Rich Message API. This API allows for greater freedom of format than ordinary rich
messages offered to official accounts.
Ordinary Rich Messages API Rich Messages
Created using the templates
provided.
Set links and regions freely.
Sample: Rich Message API Source Code
49 © LINE Corporation
} }, "scenes": { "scene1": { "draw": [ { "image": "image1", "x": 0, "y": 0, "w": 700, "h": 700 } ], "listeners": [ { "type": "touch", "params": [0, 0, 700, 350], "action": "openHomepage" }, { "type": "touch", "params": [0, 350, 700, 350], "action": "showItem" } ] } } }
{ "canvas": { "width": 700, "height": 700, "initialScene": "scene1" }, "images": { "image1": { "x": 0, "y": 0, "w": 700, "h": 700 } }, "actions": { "openHomepage": { "type": "web", "text": "Open our homepage.", "params": { "linkUri": "http://your.server.name/" } }, "showItem": { "type": "web", "text": "Show item.", "params": { "linkUri": "http://your.server.name/items/123" }
Please see LINE Developers “BOT Server API” > Send Rich Content Message.