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  "reason": "<エラー理由>"
3}

アプリ向け API の認証

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

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

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

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

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

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

Request (application/json)

1{
2    "service": 1,
3    "token": "<<token>>" 
4}

Response (application/json)

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

1{
2    "user_key": "<<user_key>>"
3}

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

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

Request (application/json)

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

1{
2    "token": "<<user_key>>" 
3}

Response (application/json)

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

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

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

Request

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

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

Response (application/json)

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

 1[
 2    {
 3        "channel_id": 3,
 4        "channel_name": "テスト用",
 5        "subscribed": true
 6    },
 7    {
 8        "channel_id": 11,
 9        "channel_name": "緊急連絡用",
10        "subscribed": false
11    }
12]

• 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        "message_id": 2,
 4        "channel_name": "テスト用",
 5        "published_date": "2015-02-20T03:30:00+09:00",
 6        "title": "タイトル",
 7        "description": "メッセージ" 
 8    },
 9    {
10        "message_id": 1,
11        "channel_name": "緊急連絡用",
12        "published_date": "2015-02-20T02:50:00+09:00",
13        "title": "タイトル",
14        "description": "メッセージ" 
15    }
16]

• 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    "message_id": 2,
3    "channel_name": "テスト用",
4    "published_date": "2015-02-20T03:30:00+09:00",
5    "title": "タイトル",
6    "description": "メッセージ" 
7}

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

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

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

Request

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

1{
2    key1: "value1",
3    key2: "value2",
4     ：      ：
5     ：      ：
6}

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

Response (application/json)

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