BoltzMessenger Web が提供する API

BoltzMessenger Web が提供する API について解説します。標準でインストールした場合、以下の URL は /bm/api/v1.1/ 以下に配置されます。

概要

レスポンスの内容

BoltzMessenger Web は各種 API 実行後、以下のレスポンスを返します。

成功した場合

データがある API の場合は 200 OK、データがない API の場合は 204 No Content の HTTP レスポンスを返します。

失敗した場合

処理に失敗した場合は、HTTPステータスコードを 400 以上とし、以下の JSON を含む HTTP レスポンスを返します。

1
2
3

{
  "reason": "<エラー理由>"
}

アプリ向け API の認証

アプリ向け API でユーザーの特定が必要なものについては、ユーザー登録 API から返されたユーザーキーを HTTP ヘッダ X-BoltzMessenger-UserKey として含める必要があります。

1
2
3

GET /messages HTTP/1.1
Content-Type: application/json
X-BoltzMessenger-UserKey: <<user_key>>

iOS のデバイストークンのエンコード

デバイストークンを渡すパラメータでは、iOS のデバイストークンはHEXエンコード(16進数表記)にしたものを使用します。2015年7月1日現在は64文字の文字列となります。

ユーザー登録API [POST /devices]

新しいユーザートークンを登録します。すでに当該トークンが登録済みの場合は、以前登録したユーザーキーが返されます。

Request (application/json)

1
2
3
4

{
    "service": 1,
    "token": "<<token>>" 
}

Response (application/json)

成功時は、以下の内容を含む 200 OK を返します。失敗時はエラーレスポンスを返します。

1
2
3

{
    "user_key": "<<user_key>>"
}

トークン更新API [PUT /device]

user_key に紐付くトークンを更新します。各プッシュサービスからトークンの更新が通知された場合に実行します。[PUT /devices] ではないことに注意してください。

Request (application/json)

HTTP ヘッダに X-BoltzMessenger-Key の指定が必要です。

1
2
3

{
    "token": "<<user_key>>" 
}

Response (application/json)

成功時は 204 No Content を返し、失敗時はエラーレスポンスを返します。

チャンネル設定取得API [GET /channels]

チャンネルの一覧と、現在のユーザーの登録状態を取得します。

Request

HTTP ヘッダに X-BoltzMessenger-Key の指定が必要です。

リクエストボディはありません。

Response (application/json)

成功時は、以下の内容を含む 200 OK を返します。失敗時はエラーレスポンスを返します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

[
    {
        "channel_id": 3,
        "channel_name": "テスト用",
        "subscribed": true
    },
    {
        "channel_id": 11,
        "channel_name": "緊急連絡用",
        "subscribed": false
    }
]

• channel_id | int | チャンネルID
• channel_name | string | チャンネル名
• subscribed | bool | このユーザーが登録済みかどうか (true:登録済み)

チャンネル登録/解除API [(PUT|DELETE) /channels/:channel_id]

チャンネルの登録・解除を行います。登録を行う場合が PUT リクエスト、解除を行う時が DELETE リクエストとなります。

すでに登録済みの場合に登録リクエストを送った場合や、すでに解除済みの場合に解除リクエストを送った場合もエラーを返すことはなく、正常完了としてレスポンスを返します。

Request

URL の :channel_id の部分に登録/解除対象となるチャンネルIDを指定します。

HTTP ヘッダに X-BoltzMessenger-Key の指定が必要です。

リクエストボディはありません。

Response (application/json)

成功時は 204 No Content を返し、失敗時はエラーレスポンスを返します。

メッセージ一覧API [GET /messages]

現在のユーザーが登録しているチャンネルに対して配信されたメッセージの一覧を取得します。

Request

HTTP ヘッダに X-BoltzMessenger-Key の指定が必要です。

リクエストボディはありません。

Response (application/json)

成功時は、以下の内容を含む 200 OK を返します。失敗時はエラーレスポンスを返します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[
    {
        "message_id": 2,
        "channel_name": "テスト用",
        "published_date": "2015-02-20T03:30:00+09:00",
        "title": "タイトル",
        "description": "メッセージ" 
    },
    {
        "message_id": 1,
        "channel_name": "緊急連絡用",
        "published_date": "2015-02-20T02:50:00+09:00",
        "title": "タイトル",
        "description": "メッセージ" 
    }
]

• message_id | int | メッセージID
• channel_name | string | 配信先のチャンネル名
• published_date | string | 配信日時
• title | string | メッセージのタイトル(通知として送信されたもの)
• description | string | メッセージの内容

メッセージ取得API [GET /messages/:mesasge_id]

特定のメッセージを取得します。

Request

URL の : mesasge_id の部分に取得対象となるメッセージIDを指定します。

HTTP ヘッダに X-BoltzMessenger-Key の指定が必要です。

リクエストボディはありません。

Response (application/json)

成功時は、以下の内容を含む 200 OK を返します。失敗時はエラーレスポンスを返します。

1
2
3
4
5
6
7

{
    "message_id": 2,
    "channel_name": "テスト用",
    "published_date": "2015-02-20T03:30:00+09:00",
    "title": "タイトル",
    "description": "メッセージ" 
}

• message_id | int | メッセージID
• channel_name | string | 配信先のチャンネル名
• published_date | string | 配信日時
• title | string | メッセージのタイトル(通知として送信されたもの)
• description | string | メッセージの内容

セグメント更新API [PUT /segments]

セグメントの登録値更新を行います。

Request

HTTP ヘッダに X-BoltzMessenger-Key の指定が必要です。

1
2
3
4
5
6

{
    key1: "value1",
    key2: "value2",
     ：      ：
     ：      ：
}

BoltzMessenger Admin よりセグメントとして事前に登録しておいた key の型によって、以下のように値が更新されます。

Response (application/json)

成功時は 204 No Content を返し、失敗時はエラーレスポンスを返します。