Peep OA — Public API Documentation

Overview

Public API for external (3rd-party) integration with the Peep Official Account system to send messages to users via OA.

Base URL:

https://oa-api.peepshare.ai

Postman Collection: Download — Import into Postman to test the API instantly

Authentication
Response Format
Rate Limiting
Endpoints
Message Item Types

Authentication

The Public API uses API Key + JWT Token authentication.

Steps:

Obtain api_key and api_secret from the admin team
Call POST /api/v2/public/auth/token to receive access_token and refresh_token
Include access_token in the header of every request:
```
Authorization: Bearer <access_token>
```
When the token expires, use POST /api/v2/public/auth/refresh-token to obtain a new token

Rate Limiting

Endpoint Group	Limit
All endpoints	200 requests / min

When the rate limit is exceeded, you will receive HTTP 429 Too Many Requests:

{
  "statusCode": 429,
  "data": "ThrottlerException: Too Many Requests",
  "timestamp": "2026-07-22 17:23:30",
  "path": "/api/v2/public/webhook/broadcast-greeting"
}

Response Format

Success Response

All successful responses are wrapped with a data field:

{
  "data": { ... }
}

Error Response

When an error occurs, the response has the following format:

{
  "statusCode": 404,
  "data": {
    "statusCode": 404,
    "code": "NOT_FOUND",
    "info": "not found account_provider in db"
  },
  "timestamp": "2026-07-22 15:46:10",
  "path": "/api/v2/public/webhook/broadcast-greeting"
}

Field	Type	Description
`statusCode`	number	HTTP status code
`data.code`	string	Error code (see table below)
`data.info`	string	Error details
`timestamp`	string	Time when the error occurred
`path`	string	Endpoint that was called

Error Codes:

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Token is invalid or expired
`NOT_FOUND`	404	Requested resource not found
`BAD_REQUEST`	400	Invalid request data
`JOB_BUSY`	400	A broadcast job is currently in progress
`INTERNAL_SERVER_ERROR`	500	Internal server error

Endpoints

1. Generate Token

Generate an access token for API calls.

POST /api/v2/public/auth/token

Authentication: Not required (uses api_key + api_secret instead)

Request Body:

Field	Type	Required	Description
`api_key`	string	✅	Your API Key
`api_secret`	string	✅	Your API Secret

Example Request:

curl -X POST https://<domain>/api/v2/public/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "pk_abc123...",
    "api_secret": "sk_xyz789..."
  }'

Example Response:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": "1h"
  }
}

2. Refresh Token

Request a new access token when the current one has expired.

POST /api/v2/public/auth/refresh-token

Authentication: Not required

Request Body:

Field	Type	Required	Description
`refresh_token`	string	✅	Refresh token from Generate Token

Example Request:

curl -X POST https://<domain>/api/v2/public/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

Example Response:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": "1h"
  }
}

3. Broadcast Greeting

Send a greeting message (pre-configured welcome message in OA) to a user.

POST /api/v2/public/webhook/broadcast-greeting

Authentication: Bearer Token

Request Body:

Field	Type	Required	Description
`user_id`	string	✅	Recipient's User ID

Example Request:

curl -X POST https://<domain>/api/v2/public/webhook/broadcast-greeting \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "user_id": "user_123456"
  }'

Example Response:

{
  "data": {
    "id": "uuid-of-greeting",
    "title": "Welcome Message",
    "slug": "welcome-message",
    "data": [
      {
        "type": "message",
        "msg": "Hello! Welcome!"
      }
    ]
  }
}

4. Broadcast Image Link

Send an image to a user. The link field is optional — if provided, tapping the image opens the URL; if omitted, it's a plain image.

POST /api/v2/public/webhook/broadcast-image-link

Authentication: Bearer Token

Request Body:

Field	Type	Required	Description
`user_id`	string	✅	Recipient's User ID
`image_url`	string	✅	Image URL
`link`	string	❌	URL embedded in image (if set, tapping image opens this URL)

Example Request:

curl -X POST https://<domain>/api/v2/public/webhook/broadcast-image-link \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "user_id": "user_123456",
    "image_url": "https://images.unsplash.com/photo-1564760290292-23341e4df6ec?q=80&w=1740&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
    "link": "https://example.com/landing-page"
  }'

Example Response:

{
  "data": "success"
}

5. Broadcast Message (Single User)

Send a text message to a single user.

POST /api/v2/public/webhook/broadcast-message

Authentication: Bearer Token

Request Body:

Field	Type	Required	Description
`user_id`	string	✅	Recipient's User ID
`msg`	string	✅	Main message content
`desc`	string	❌	Short text shown on push notification

Example Request:

curl -X POST https://<domain>/api/v2/public/webhook/broadcast-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "user_id": "user_123456",
    "msg": "Hello! You have a new message",
    "desc": "Notification"
  }'

Example Response:

{
  "data": "success"
}

6. Broadcast Message (Mass)

Broadcast messages to multiple users or all users.

POST /api/v2/public/message/broadcast-message

Authentication: Bearer Token

Request Body:

Field	Type	Required	Description
`target`	string	✅	Send type: `all`, `selected`, `single`
`user_ids`	string[]	❌*	List of User IDs (*required when target = `selected` or `single`)
`items`	array	✅	Message items (max 5 items)

Item Object:

Field	Type	Required	Description
`type`	string	✅	Message type (see Message Item Types)
`msg`	string \| string[]	✅	Message content
`desc`	string	❌	Description (max 170 characters)
`link`	string	❌	URL link (for type = `oa_image_link`)

Example Request — type message (text message):

curl -X POST https://<domain>/api/v2/public/message/broadcast-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "target": "selected",
    "user_ids": ["user_001", "user_002", "user_003"],
    "items": [
      {
        "type": "message",
        "msg": "Hello! This is a broadcast message",
        "desc": "Short text on push notification"
      }
    ]
  }'

Example Request — type oa_image_link (image with link):

curl -X POST https://<domain>/api/v2/public/message/broadcast-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "target": "all",
    "items": [
      {
        "type": "oa_image_link",
        "msg": "https://images.unsplash.com/photo-1564760290292-23341e4df6ec?q=80&w=1740&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
        "link": "https://example.com/promo",
        "desc": "Special promotion today"
      }
    ]
  }'

Example Request — type image (plain image, no link):

curl -X POST https://<domain>/api/v2/public/message/broadcast-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "target": "single",
    "user_ids": ["user_001"],
    "items": [
      {
        "type": "image",
        "msg": "https://images.unsplash.com/photo-1564760290292-23341e4df6ec?q=80&w=1740&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
      }
    ]
  }'

Example Request — type flex (flex message):

curl -X POST https://<domain>/api/v2/public/message/broadcast-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "target": "selected",
    "user_ids": ["user_001"],
    "items": [
      {
        "type": "flex",
        "msg": "{\"type\":\"bubble\",\"hero\":{\"type\":\"image\",\"url\":\"https://developers-resource.landpress.line.me/fx/img/01_1_cafe.png\",\"size\":\"full\",\"aspectRatio\":\"20:13\",\"aspectMode\":\"cover\",\"action\":{\"type\":\"uri\",\"uri\":\"https://line.me/\"}},\"body\":{\"type\":\"box\",\"layout\":\"vertical\",\"contents\":[{\"type\":\"text\",\"text\":\"Brown Cafe\",\"weight\":\"bold\",\"size\":\"xl\"},{\"type\":\"box\",\"layout\":\"vertical\",\"margin\":\"lg\",\"spacing\":\"sm\",\"contents\":[{\"type\":\"box\",\"layout\":\"baseline\",\"spacing\":\"sm\",\"contents\":[{\"type\":\"text\",\"text\":\"Place\",\"color\":\"#aaaaaa\",\"size\":\"sm\",\"flex\":1},{\"type\":\"text\",\"text\":\"Flex Tower, 7-7-4 Midori-ku, Tokyo\",\"wrap\":true,\"color\":\"#666666\",\"size\":\"sm\",\"flex\":5}]},{\"type\":\"box\",\"layout\":\"baseline\",\"spacing\":\"sm\",\"contents\":[{\"type\":\"text\",\"text\":\"Time\",\"color\":\"#aaaaaa\",\"size\":\"sm\",\"flex\":1},{\"type\":\"text\",\"text\":\"10:00 - 23:00\",\"wrap\":true,\"color\":\"#666666\",\"size\":\"sm\",\"flex\":5}]}]}]},\"footer\":{\"type\":\"box\",\"layout\":\"vertical\",\"spacing\":\"sm\",\"contents\":[{\"type\":\"button\",\"style\":\"link\",\"height\":\"sm\",\"action\":{\"type\":\"uri\",\"label\":\"CALL\",\"uri\":\"https://line.me/\"}},{\"type\":\"button\",\"style\":\"link\",\"height\":\"sm\",\"action\":{\"type\":\"uri\",\"label\":\"WEBSITE\",\"uri\":\"https://line.me/\"}},{\"type\":\"box\",\"layout\":\"vertical\",\"contents\":[],\"margin\":\"sm\"}],\"flex\":0}}",
        "desc": "Brown Cafe"
      }
    ]
  }'

Example Response:

{
  "data": {
    "id": "broadcast-uuid",
    "data": [
      {
        "type": "message",
        "msg": "Hello! This is a broadcast message"
      }
    ],
    "broadcast_at": "2025-07-22 10:30:00",
    "created_at": "2025-07-22 10:30:00",
    "estimate_time_detail": {
      "total_job_time_minutes": 2
    }
  }
}

7. Broadcast Group Message

Broadcast messages to all members in a group.

POST /api/v2/public/message/broadcast-group-message

Authentication: Bearer Token

Request Body:

Field	Type	Required	Description
`account_provider_group_id`	string	✅	UUID of the target group
`items`	array	✅	Message items (max 5 items, same format as Item Object)

Example Request:

curl -X POST https://<domain>/api/v2/public/message/broadcast-group-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "account_provider_group_id": "group-uuid-abc123",
    "items": [
      {
        "type": "message",
        "msg": "Message to all group members"
      },
      {
        "type": "oa_image_link",
        "msg": "https://example.com/event.jpg",
        "link": "https://example.com/event",
        "desc": "Special Event"
      }
    ]
  }'

Example Response:

{
  "data": {
    "id": "broadcast-uuid",
    "data": [...],
    "broadcast_at": "2025-07-22 10:30:00",
    "created_at": "2025-07-22 10:30:00",
    "estimate_time_detail": {
      "total_job_time_minutes": 1
    }
  }
}

8. Broadcast Member Session

Broadcast messages to members in a member group broadcast session.

POST /api/v2/public/message/broadcast-member-session

Authentication: Bearer Token

Request Body:

Field	Type	Required	Description
`member_group_broadcast_id`	string	✅	UUID of the member group broadcast
`items`	array	✅	Message items (max 5 items, same format as Item Object)

Example Request:

curl -X POST https://<domain>/api/v2/public/message/broadcast-member-session \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "member_group_broadcast_id": "mgb-uuid-xyz789",
    "items": [
      {
        "type": "message",
        "msg": "Message for member session"
      }
    ]
  }'

Example Response:

{
  "data": {
    "id": "broadcast-uuid",
    "data": [...],
    "broadcast_at": "2025-07-22 10:30:00",
    "created_at": "2025-07-22 10:30:00",
    "estimate_time_detail": {
      "total_job_time_minutes": 3
    }
  }
}

Message Item Types

Type	Description	`msg` Format	Requires `link`?
`message`	Plain text message	string	❌
`oa_image_link`	Image that opens a link on tap	string (image URL)	✅
`image`	Plain image (no link)	string (image URL)	❌
`flex`	Flex message	string (JSON format)	❌

Quick Start

# 1. Get token
TOKEN=$(curl -s -X POST https://<domain>/api/v2/public/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key":"pk_...","api_secret":"sk_..."}' | jq -r '.data.access_token')

# 2. Send message to a user
curl -X POST https://<domain>/api/v2/public/webhook/broadcast-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "user_id": "target_user_id",
    "msg": "Hello from API!"
  }'

# 3. Broadcast to all users
curl -X POST https://<domain>/api/v2/public/message/broadcast-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "target": "all",
    "items": [{"type": "message", "msg": "📢 Important announcement!"}]
  }'

Overview​

Table of Contents​

Authentication​

Steps:​

Rate Limiting​

Response Format​

Success Response​

Error Response​

Endpoints​

1. Generate Token​

2. Refresh Token​

3. Broadcast Greeting​

4. Broadcast Image Link​

5. Broadcast Message (Single User)​

6. Broadcast Message (Mass)​

7. Broadcast Group Message​

8. Broadcast Member Session​

Message Item Types​

Quick Start​

Overview

Table of Contents

Authentication

Steps:

Rate Limiting

Response Format

Success Response

Error Response

Endpoints

1. Generate Token

2. Refresh Token

3. Broadcast Greeting

4. Broadcast Image Link

5. Broadcast Message (Single User)

6. Broadcast Message (Mass)

7. Broadcast Group Message

8. Broadcast Member Session

Message Item Types

Quick Start