LINE Notify API Document
- 2023/11/17 Updated
Removed HTTP support for imageThumbnail/imageFullsize (please use HTTPS) - 2021-06-14 Updated
Add description about limiting the number of tokens(connected services) - 2019-06-25 Updated
Modify description about imageFullsize. - 2019-06-11 Updated
Add description about notificationDisabled. - 2016-11-08 Updated
Add description about sticker. - 2016-10-24 Updated
Add description about uploading image. - 2016-09-29 Updated
Initial version
Overall flow and possible implementations of the API
The API consists of an OAuth2 authentication part and a LINE notification part. The overall flow of the API is as follows.
- Intended users: Plan to configure LINE notifications
- Connected service: Redirect to OAuth2 authorization endpoint
- LINE: Select notification channel and check user agreement status. Redirect to connected service.
- Connected service: Receive access token by accessing OAuth2 token endpoint using the parameters given during redirection
- Connected service: Stores access tokens
- (When sending notification) Connected service: Calls notification API using stored access tokens
- (When checking notification settings) Connected service: Calls connection status check API and then displays connection status to user
- (When disabling notifications) Connected service: Calls disconnection API
From the flow above, features that need to be implemented on connected services are as follows
- Generating OAuth2 URL addresses and redirecting
- Storing OAuth2 access tokens connected to users
- Calling the notification API at the time of a notification
- (If there is a page for checking connection status) Displaying connection status through connection status API
- (When the connected service is disabling a notification) Calling notification revoke API
As notifications can be configured and revoked on the web page, implementation of the API is optional.
Authentication
Overview: Becomes a provider based on OAuth2 (https://tools.ietf.org/html/rfc6749). The authentication method is authorization_code. The access token acquired here can only be used for notification services.
The host name for authentication API endpoint is notify-bot.line.me.
GET https://notify-bot.line.me/oauth/authorize
The following is the OAuth2 authorization endpoint URI.
Request method
| Request methods/headers | Value |
|---|---|
| Method | GET |
Request parameters
The received parameters are as follows.
| Parameter name | Required/optional | Type | Description |
|---|---|---|---|
| response_type | Required | fixed value | Assigns "code" |
| client_id | Required | string | Assigns the client ID of the generated OAuth |
| redirect_uri | Required | uri |
Assigns the generated redirect URI. We recommend using HTTPS on redirect URI to prevent code parameter leaks. |
| scope | Required | fixed value | Assigns "notify" |
| state | Required | string |
Assigns a token that can be used for responding to CSRF attacks LINE Notify is designed with web applications in mind, and requires state parameter variables. |
| response_mode | Optional | string |
By assigning "form_post", sends POST request to redirect_uri by form post instead of redirecting We recommend assigning this to prevent code parameter leaks in certain environments |
Response
When successful, redirects to the assigned redirect_uri or posts according to the form with the parameters below attached.
| Parameter name | Type | Description |
|---|---|---|
| code | string | A code for acquiring access tokens |
| state | string | Directly sends the assigned state parameter |
When there is a failure, redirects to the assigned reirect_uri with the parameters below attached.
| Parameter name | Type | Description |
|---|---|---|
| error | string | Assigns error codes defined by OAuth2 https://tools.ietf.org/html/rfc6749#section-4.1.2 |
| error_description | string | An optional huma-readable text providing additional information, used to assist the client developer in understanding the error that occurred. |
| state | string | Directly send the assigned state parameter |
POST https://notify-bot.line.me/oauth/token
The OAuth2 token endpoint.
Request methods
| Request methods/headers | Value |
|---|---|
| Method | POST |
| Content-Type | application/x-www-form-urlencoded |
Request parameters
The parameters are as follows.
| Parameter name | Required/optional | Type | Description |
|---|---|---|---|
| grant_type | Required | fixed value | Assigns "authorization_code" |
| code | Required | string | Assigns a code parameter value generated during redirection |
| redirect_uri | Required | uri | Assigns redirect_uri to assigned authorization endpoint API |
| client_id | Required | string | Assigns client ID to issued OAuth |
| client_secret | Required | string | Assigns secret to issued OAuth |
Response
| Response header | Value |
|---|---|
| Status |
200: Success 400: Bad request Other: Processed over time or stopped |
| Content-Type | application/json |
Response body
The response body is a JSON object type.
| Name | Type | Value description |
|---|---|---|
| access_token | string |
An access token for authentication. Used for calling the notification API to be mentioned below. This access token has no expiration date. |
Notification
Overview: An API for LINE notifications. OAuth authentication is required in advance. It can be used to check connection status, actual notifications, and disconnecting.
The host name for notification API end point is notify-api.line.me.
Authentication method
Request header authorization: Grants bearer <access_token> and accesses. If the access token used is invalid, a 401 status code and WWW-Authenticate header is returned according to RFC6750
POST https://notify-api.line.me/api/notify
Sends notifications to users or groups that are related to an access token.
If this API receives a status code 401 when called, the access token will be deactivated on LINE Notify (disabled by the user in most cases). Connected services will also delete the connection information.
Requests use POST method with application/x-www-form-urlencoded (Identical to the default HTML form transfer type).
Expected use cases
When a connected service has an event that needs to send a notification to LINE
Request method
| Request methods/headers | Value |
|---|---|
| Method | POST |
| Content-Type | application/x-www-form-urlencoded OR multipart/form-data |
| Authorization | Bearer <access_token> |
Request parameters
The parameters are as follows.
| Parameter name | Required/optional | Type | Description |
|---|---|---|---|
| message | Required | String | 1000 characters max |
| imageThumbnail | Optional | HTTPS URL | Maximum size of 240×240px JPEG |
| imageFullsize | Optional | HTTPS URL | Maximum size of 2048×2048px JPEG |
| imageFile | Optional | File |
Upload a image file to the LINE server. If you specified imageThumbnail ,imageFullsize and imageFile, imageFile takes precedence. There is a limit that you can upload to within one hour. |
| stickerPackageId | Optional | Number |
Package ID. Sticker List. |
| stickerId | Optional | Number | Sticker ID. |
| notificationDisabled | Optional | Boolean |
true: The user doesn't receive a push notification when the message is sent. false: The user receives a push notification when the message is sent (unless they have disabled push notification in LINE and/or their device). If omitted, the value defaults to false. |
Response
| Response headers | Value |
|---|---|
| status |
200: Success 400: Bad request 401: Invalid access token 500: Failure due to server error Other: Processed over time or stopped |
| Content-Type | application/json |
Response body
The response body is a JSON object type.
| Name | Type | Value description |
|---|---|---|
| status | number |
Value according to HTTP status code 200: Success 400: Bad request 401: Invalid access token |
| message | string | Message visible to end-user |
Sample
GET https://notify-api.line.me/api/status
An API for checking connection status. You can use this API to check the validity of an access token. Acquires the names of related users or groups if acquiring them is possible.
On the connected service side, it's used to see which groups are configured with a notification and which user the notifications will be sent to. There is no need to check the status with this API before calling /api/notify or /api/revoke.
If this API receives a status code 401 when called, the access token will be deactivated on LINE Notify (disabled by the user in most cases). Connected services will also delete the connection information.
Expected use cases
If a connected service wishes to check the connection status of a certain user
As LINE Notify also provides the same feature, support for this API is optional.
Request methods
| Request methods/headers | Value |
|---|---|
| Method | GET |
| Authorization | Bearer <access_token> |
Response
The message body contains detailed information in JSON
| Response headers | Value |
|---|---|
| Status |
200: Success・Access token valid 401: Invalid access token Other: Processed over time or stopped |
| Content-Type | application/json |
Response body
The response body is a JSON object type.
| Name | Type | Value description |
|---|---|---|
| status | number |
Value according to HTTP status code 200: Success・Access token valid 401: Invalid access token |
| message | string | Message visible to end-user |
| targetType | string |
If the notification target is a user: "USER" If the notification target is a group: "GROUP" |
| target | string |
If the notification target is a user, displays user name. If acquisition fails, displays "null." If the notification target is a group, displays group name. If the target user has already left the group, displays "null." |
Sample
POST https://notify-api.line.me/api/revoke
An API used on the connected service side to revoke notification configurations. Using this API will revoke all used access tokens, disabling the access tokens from accessing the API.
The revocation process on the connected service side is as follows
- Call /api/revoke
- If step 1 returns status code 200, the request is accepted, revoking all access tokens and ending the process
- If step 1 returns status code 401, the access tokens have already been revoked and the connection will be d
- If step 1 returns any other status code, the process will end (you can try again at a later time)
Expected use cases
When the connected service wishes to end a connection with a user
As LINE Notify also provides the same feature, support for this API is optional.
Request methods
| Request methods/headers | Value |
|---|---|
| Method | POST |
| Content-Type | application/x-www-form-urlencoded |
| Authorization | Bearer <access_token> |
Request parameters
There are no parameters.
Response
The message body contains detailed information in JSON
| Response headers | Value |
|---|---|
| Status |
200: Success 401: Invalid access token Other: Processed over time or stopped |
| Content-Type | application/json |
Response body
The response body is a JSON object type.
| Name | Type | Value description |
|---|---|---|
| status | number |
Value according to HTTP status code 200: Success 401: Invalid access token |
| message | string | Message visible to end-user |
Sample
API Rate Limit
There is a limit to the number of times an API can be called on each service.
The default number is set to 1000.
The limit is per access token.
The API Rate Limit status, can be checked on the response header of the API.
| Header name | Description |
|---|---|
| X-RateLimit-Limit | The limit of API calls per hour |
| X-RateLimit-Remaining | The number of possible remaining API calls |
| X-RateLimit-ImageLimit | The limit of Uploading image per hour |
| X-RateLimit-ImageRemaining | The number of possible remaining Uploading image |
| X-RateLimit-Reset |
The time when the limit is reset (UTC epoch seconds) ex:1472195604 |
Limiting the number of tokens(connected services)
It is possible to issue up to 100 tokens per user.