COLINE Message API

透過COLINE Message API 可在團體內發佈動態消息以及針對聊天室或是個別成員發訊息，並透過 Webhook URL 設定進行交互應用。

進入團體後台，設定應用相關訊息並取得對應token跟secret。

應用名稱
來源IP
聊天室預設 Webhook URL
動態消息 Webhook URL
Webhook 重試次數：1~3
Webhook 重試間隔：1~3秒

Webhook

聊天室有訊息會通知 webhook url
動態消息有回文、已讀會通知 webhook url

Webhook Signature

JWT 用來驗證 request 是否是從 COLINE 發送過來的。

Request
- Headers
```
Authorization: Bearer {JWT}
```

header 跟 payload 分別用 url safe base64 加密。
base64(header).base64(payload) 將加密後的字串組成signature，利用secret作為密鑰，使用HMAC-SHA256進行雜湊加密。
最後組成JWT base64(header).base64(payload).base64(sha256(signature))

header

{
    "alg": "HS256",
    "typ": "JWT"
}

payload
- iss: COLINE, token 為COLINE 發行。
- exp: 毫秒時間到期戳記，從發行時間起算5分鐘後到期。

{
    "iss": "COLINE",
    "exp": 0
}

Status Code

Status Code	Description
200 OK	正常
402 Over The Limit	超過限制
500 Internal Server Error	系統錯誤

API	Description	Rate Limit
GET /v3/open/users{?key,branch_id,next}	取得成員資訊	10 requests per minute
GET /v3/open/branches	取得群組資訊	10 requests per minute
POST /v3/open/files	上傳檔案	30 requests per hour

API	Description	Rate Limit
POST /v3/open/chatrooms	建立聊天室	60 requests per hour
GET /v3/open/chatrooms	取得聊天室	60 requests per hour
GET /v3/open/chatrooms/{ci}/users	取得聊天室成員資訊	30 requests per minute
PUT /v3/open/chatrooms/{ci}/users	更新聊天室成員	1000 requests per hour
POST /v3/open/chatrooms/{ci}/avatar	更新聊天室頭像	60 requests per hour
PUT /v3/open/chatrooms/{ci}	變更聊天室資訊	10 requests per hour
POST /v3/open/messages	建立聊天室訊息	1000 requests per minute
POST /v3/open/postMessages	建立聊天室貼文訊息	1000 requests per minute
POST /v3/open/messages/{ei}	回覆聊天室訊息	1000 requests per minute

API	Description	Rate Limit
POST /v3/open/events	建立動態消息貼文	1000 requests per minute

Message ¶

TextMessage 文字訊息

{
    "type": "text",
    "content": "Hello World~"
}

LocationMessage 定位訊息

{
    "type": "location",
    "language_id": "zh_TW",
    "address": "104台灣台北市中山區新生北路二段39-2號",
    "description": "三竹資訊",
    "longitude": 121.52781128883362,
    "latitude": 25.055070844857372
}

PhotoMessage 圖片訊息

{
    "type": "photo",
    "content": "5403ae99-dbe1-46f5-979d-321ebebd5ca0" // File ID
}

VideoMessage 影片訊息

{
    "type": "video",
    "content": "5403ae99-dbe1-46f5-979d-321ebebd5ca0" // File ID
}

SoundMessage 語音訊息

{
    "type": "sound",
    "content": "5403ae99-dbe1-46f5-979d-321ebebd5ca0" // File ID
}

FileMessage 檔案訊息

{
    "type": "file",
    "content": "5403ae99-dbe1-46f5-979d-321ebebd5ca0" // File ID
}

StickerMessage 貼圖訊息

{
    "type": "sticker",
    "content": "wellcome" // sticker ID
}

TargetMessage 標記成員訊息

{
    "type": "target",
    "user_id":"user_id",
    "content": "wellcome" // 標記訊息內容
}

VoteMessage 投票訊息

{
    "type": "vote",
    "begin_time":1607926789709,
    "end_time":1608185989709,
    "vote_mode":0,// 投票模式(0：一般投票、1：公開投票、2：匿名投票) (optional)
    "list":[
        {
            "key":0,// 投票主題編號
            "title":"title1",// 投票主題
            "ballot":1,// 一次最多可投幾票
            "items":[
                {
                    "key":0,// 投票選項編號
                    "option":"item1"// 投票選項
                },
                {
                    "key":1,
                    "option":"item2"
                },
                {
                    "key":2,
                    "option":"item3"
                }
          ]
          }
    ]
}

StickerID	推薦情境	StickerID	推薦情境
received	傳送失敗	denied	傳送成功
welcome	成員加入	approve	批准
read	已讀	got_it	收到
busy	忙碌	miss_you	久未上線
work_overtime	下班時間沒打卡	clock_in_yet	上班還沒打卡
thank_you	感謝	please	拜託
wait_so_long	等太久	get_cold_feet	落跑
please	拜託	what_do_you_eat	吃什麼
sad	難過

Webhook Payload ¶

meta
- type: 類型
- user_id: 觸發者成員編號
- created_time: 觸發時間

JoinGroupEvent 團體成員加入(TODO)

{
    "meta":{
        "type": "JOIN_GROUP",
        "created_time":"2020-01-02 13:30:59"
    },
    "content":{
        "users":["USERID1"]
    }
}

JoinBranchEvent 群組成員加入(TODO)

{
    "meta":{
        "type": "JOIN_BRANCH",
        "user_id": "IMUSERID",
        "created_time":"2020-01-02 13:30:59"
    },
    "content":{
        "branch_id":"IMBRANCHID",
        "users":["USERID1"]
    }
}

JoinChatroomEvent 聊天室成員加入

{
    "meta":{
        "type": "JOIN_CHAT",
        "created_time":"2020-01-02 13:30:59"
    },
    "content":{
        "chatroom_id":"IMCHATROOMID",
        "users":["USERID1", "USERID2"]
    }
}

Message 聊天訊息

{
    "meta":{
        "type": "MESSAGE",
        "user_id": "IMUSERID",
        "created_time":"2020-01-02 13:30:59"
    },
    "content":{
        "chatroom_id":"{chatroom_id}",
        "type":"many_to_many",
        "event_id":"{event_id}",
        "messages":[
            {
                "type": "text",
                "content": "hello world from user."
            }
        ]
    }
}

content_type
- many_to_many
- public
- one_to_one

Event 動態消息

message 貼文主文
attachments 附件內容, 參考 Message 區塊的 example

{
    "meta":{
        "type": "EVENT",
        "user_id": "IMUSERID",
        "created_time":"2020-01-02 13:30:59",
    },
    
    "content": {
        "event_id":"IMROOTEVENTID",
        "message": "HelloWorld",
        "attachments":[
            {   
                "type": "photo",
                "content": "FILE_ID"
            },  
            {   
                "type": "sticker",
                "content": "STICKER_ID"
            }
        ]
    }
}

EventRead 動態消息已讀

event_id 主文貼文編號

{
    "meta":{
        "type": "EVENT_READ",
        "user_id": "IMUSERID",
        "created_time":"2020-01-02 13:30:59"
    },
    "content":{
        "event_id":"IMROOTEVENTID"
    }
}

ReplyEvent 動態消息回文

event_id 主文貼文編號
messages 回文訊息

{
    "meta":{
        "type": "REPLY_EVENT",
        "user_id": "IMUSERID",
        "created_time":"2020-01-02 13:30:59"
    },
    "content":{
        "event_id":"IMROOTEVENTID",
        "messages":[
            {
                "type": "text",
                "content": "hello world from user."
            }
        ]
    }
}

團體 ¶

成員資訊 ¶

取得成員資訊
GET`/v3/open/users{?key,branch_id,next}`

Example URI

GET https://eim.mitake.com.tw/v3/open/users?key=&branch_id=&next=

URI Parameters

HideShow

next: string (optional)
分頁
key: string (optional)
搜尋關鍵字，可多筆
branch_id: string (optional)
群組ID，可多筆

Request

HideShow

Headers

li: 語言
token: {token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok",
  "data": {
    "next": "IMNEXTHASH",
    "users": [
      {
        "user_id": "5418bc95-8ca0-44e4-bd8d-16420ab87660",
        "name": "Bobby",
        "nickname": "Bob",
        "email": "ertet@rtet.com",
        "employee_no": "100019",
        "account_type": "LDAP",
        "phone": "+886912345678",
        "branches": [
          "5222901c-7641-4df5-a0eb-4db4b08b66be"
        ]
      }
    ]
  }
}

群組資訊 ¶

取得群組資訊
GET`/v3/open/branches`

Example URI

GET https://eim.mitake.com.tw/v3/open/branches

Request

HideShow

Headers

li: 語言
token: {token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok",
  "data": {
    "branches": [
      {
        "branch_id": "5418bc95-8ca0-44e4-bd8d-16420ab87660",
        "name": "The Branch A",
        "parent": "ROOT"
      }
    ]
  }
}

檔案 ¶

上傳檔案
POST`/v3/open/files`

Example URI

POST https://eim.mitake.com.tw/v3/open/files

Request

HideShow

Headers

Content-Type: form-data
li: 語言
token: {token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok",
  "data": [
    "IMFILEID"
  ]
}

聊天 ¶

聊天室 ¶

建立聊天室
POST`/v3/open/chatrooms`

Example URI

POST https://eim.mitake.com.tw/v3/open/chatrooms

Request

HideShow

Headers

li: 語言
token: {token}

Body

{
  "name": "TestChatroomName",
  "users": [
    "USERID001",
    "USERID002"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok",
  "data": {
    "chatroom_id": "IMCHATROOMID"
  }
}

取得聊天室
GET`/v3/open/chatrooms`

Example URI

GET https://eim.mitake.com.tw/v3/open/chatrooms

Request

HideShow

Headers

li: 語言
token: {token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "success": true,
    "message": "ok",
    "data": {
        "chatrooms": [
            {                    
                "chatroom_id": "bjcvSkZjTWd4RmRnUVJrMTBBMm1LZz09",
                "name": "客服聊天室",
                "type": "many_to_many",
                "avatar": "1460ca4c-3b18-4914-900b-c811a7d78750" //聊天室頭像fileID
            },
             {
                "chatroom_id": "ZUV1SkJ6d091UHFrNGJNTWl4QllqZz09",
                "name": "王大為", //一對一聊天室，聊天室名稱為對象名字
                "type": "one_to_one",
                "avatar": ""
            }
        ]
    }
}

聊天室資訊 ¶

變更聊天室資訊
PUT`/v3/open/chatrooms/{ci}`

Example URI

PUT https://eim.mitake.com.tw/v3/open/chatrooms/ci

URI Parameters

HideShow

ci: string (required)
Chatroom ID

Request

HideShow

Headers

li: 語言
token: {token}

Body

{
  "name": "NEWCHATROOMNAME"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok"
}

聊天室頭像 ¶

更新聊天室頭像
POST`/v3/open/chatrooms/{ci}/avatar`

Example URI

POST https://eim.mitake.com.tw/v3/open/chatrooms/ci/avatar

URI Parameters

HideShow

ci: string (required)
Chatroom ID

Request

HideShow

Headers

Content-Type: form-data
li: 語言
token: {token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok"
}

聊天室成員資訊 ¶

取得聊天室成員資訊
GET`/v3/open/chatrooms/{ci}/users`

Example URI

GET https://eim.mitake.com.tw/v3/open/chatrooms/ci/users

URI Parameters

HideShow

ci: string (required)
Chatroom ID

Request

HideShow

Headers

li: 語言
token: {token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok",
  "data": {
    "users": [
      {
        "user_id": "{user_id}",
        "nickname": "{user_name}"
      }
    ]
  }
}

更新聊天室成員
PUT`/v3/open/chatrooms/{ci}/users`

Example URI

PUT https://eim.mitake.com.tw/v3/open/chatrooms/ci/users

URI Parameters

HideShow

ci: string (required)
Chatroom ID

Request

HideShow

Headers

li: 語言
token: {token}

Body

{
  "add": [
    "{user_id}"
  ],
  "del": [
    "{user_id}"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok"
}

聊天室訊息 ¶

建立聊天室訊息
POST`/v3/open/messages`

user_id: 使用者ID，針對使用者發訊息。
chatroom_id: 聊天室ID，針對聊天室發訊息。

Example URI

POST https://eim.mitake.com.tw/v3/open/messages

Request

HideShow

Headers

li: 語言
token: {token}

Body

{
  "user_id": "IMUSERID",
  "chatroom_id": "IMCHATROOMIDFROM",
  "message": {
    "type": "text",
    "content": "Hello World~"
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok"
}

單筆聊天室訊息 ¶

回覆聊天室訊息
POST`/v3/open/messages/{ei}`

Example URI

POST https://eim.mitake.com.tw/v3/open/messages/ei

URI Parameters

HideShow

ei: string (required)
event ID

Request

HideShow

Headers

li: 語言
token: {token}

Body

{
  "content": "hello world."
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "message": "ok"
}

聊天室貼文訊息 ¶

建立聊天室貼文訊息
POST`/v3/open/postMessages`

Example URI

POST https://eim.mitake.com.tw/v3/open/postMessages

Request

HideShow

Headers

li: 語言
token: {token}

Body

{
    "user_id":"IMUSERID",
    "chatroom_id":"IMCHATROOMIDFROM",
    "tags":["YOURTAG"], //貼文標籤 optional
    "content": {
      "message": "HelloWorld",  // 文字訊息
      "attachments":[  //附加訊息 -- 參考 Message 區塊的 example, 各類型只可附加一次
          {
              "type": "photo",
              "content": "FILE_ID"
          },
          {
              "type": "sticker",
              "content": "STICKER_ID"
          }
      ]
      }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "data": {
        "event_id": "49d87d06-1c29-44b9-b97f-c4a690ec6a06"//IM event id
    },
    "success": true,
    "message": "ok"
}

動態消息 ¶

動態消息貼文 ¶

建立動態消息貼文
POST`/v3/open/events`

Example URI

POST https://eim.mitake.com.tw/v3/open/events

Request

HideShow

Headers

li: 語言
token: {token}

Body

{

  "users":[  //指定成員 (optional)
     "USER_ID01", "USER_ID02", "USER_ID03"
  ],
  "branches":[  //指定群組 (optional)
     "BRANCH_ID01", "BRANCH_ID02", "BRANCH_ID03"
  ]
  "watermark": true,  // 浮水印 (若附件有圖片訊息，可增加此資訊)
  "top":false, //置頂貼文
           "tags":["YOURTAG"], //貼文標籤 optional
  "content": {
      "message": "HelloWorld",  // 文字訊息
      "attachments":[  //附加訊息 -- 參考 Message 區塊的 example, 各類型只可附加一次
          {
              "type": "photo",
              "content": "FILE_ID"
          },
          {
              "type": "sticker",
              "content": "STICKER_ID"
          }
      ]
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "data": {
        "event_id": "49d87d06-1c29-44b9-b97f-c4a690ec6a06"//IM event id
    },
    "success": true,
    "message": "ok"
}

設定 ¶

Webhook ¶

Webhook Signature ¶

Status Code ¶

團體 ¶

聊天 ¶

動態消息 ¶

Message ¶

TextMessage 文字訊息 ¶

LocationMessage 定位訊息 ¶

PhotoMessage 圖片訊息 ¶

VideoMessage 影片訊息 ¶

SoundMessage 語音訊息 ¶

FileMessage 檔案訊息 ¶

StickerMessage 貼圖訊息 ¶

TargetMessage 標記成員訊息 ¶

VoteMessage 投票訊息 ¶

Webhook Payload ¶

JoinGroupEvent 團體成員加入(TODO) ¶

JoinBranchEvent 群組成員加入(TODO) ¶

JoinChatroomEvent 聊天室成員加入 ¶

Message 聊天訊息 ¶

Event 動態消息 ¶

EventRead 動態消息已讀 ¶

ReplyEvent 動態消息回文 ¶

團體 ¶

成員資訊 ¶

取得成員資訊 GET/v3/open/users{?key,branch_id,next}

Example URI

Headers

Headers

Body

群組資訊 ¶

取得群組資訊 GET/v3/open/branches

Example URI

Headers

Headers

Body

檔案 ¶

上傳檔案 POST/v3/open/files

Example URI

Headers

Headers

Body

聊天 ¶

聊天室 ¶

建立聊天室 POST/v3/open/chatrooms

Example URI

Headers

Body

Headers

Body

取得聊天室 GET/v3/open/chatrooms

Example URI

Headers

Headers

Body

聊天室資訊 ¶

變更聊天室資訊 PUT/v3/open/chatrooms/{ci}

Example URI

Headers

Body

Headers

Body

聊天室頭像 ¶

更新聊天室頭像 POST/v3/open/chatrooms/{ci}/avatar

Example URI

Headers

Headers

Body

聊天室成員資訊 ¶

取得聊天室成員資訊 GET/v3/open/chatrooms/{ci}/users

Example URI

Headers

Headers

Body

更新聊天室成員 PUT/v3/open/chatrooms/{ci}/users

Example URI

Headers

Body

設定

Webhook

Webhook Signature

Status Code

團體

聊天

動態消息

TextMessage 文字訊息

LocationMessage 定位訊息

PhotoMessage 圖片訊息

VideoMessage 影片訊息

SoundMessage 語音訊息

FileMessage 檔案訊息

StickerMessage 貼圖訊息

TargetMessage 標記成員訊息

VoteMessage 投票訊息

JoinGroupEvent 團體成員加入(TODO)

JoinBranchEvent 群組成員加入(TODO)

JoinChatroomEvent 聊天室成員加入

Message 聊天訊息

Event 動態消息

EventRead 動態消息已讀

ReplyEvent 動態消息回文

取得成員資訊
GET`/v3/open/users{?key,branch_id,next}`

取得群組資訊
GET`/v3/open/branches`

上傳檔案
POST`/v3/open/files`

建立聊天室
POST`/v3/open/chatrooms`

取得聊天室
GET`/v3/open/chatrooms`

變更聊天室資訊
PUT`/v3/open/chatrooms/{ci}`

更新聊天室頭像
POST`/v3/open/chatrooms/{ci}/avatar`

取得聊天室成員資訊
GET`/v3/open/chatrooms/{ci}/users`

更新聊天室成員
PUT`/v3/open/chatrooms/{ci}/users`

建立聊天室訊息
POST`/v3/open/messages`

回覆聊天室訊息
POST`/v3/open/messages/{ei}`

建立聊天室貼文訊息
POST`/v3/open/postMessages`

建立動態消息貼文
POST`/v3/open/events`