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}
key 内容
reason string エラーメッセージ

アプリ向け 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}
key 内容
service int プッシュサービスの種類 (1:APNs, 2:FCM, 4:WebPush, 5:ADM)
token string デバイストークン

Response (application/json)

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

1{
2    "user_key": "<<user_key>>"
3}
key 内容
user_key string ユーザーキー(当該デバイスの BoltzMessenger 上の ID)

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

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

Request (application/json)

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

1{
2    "token": "<<user_key>>" 
3}
key 内容
token string デバイストークン

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]
key 内容
[] array[Channel]
- 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]
key 内容
[] array[Message]
- 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}
key 内容
{} Message
- 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}
key 内容
[セグメント登録値 key] string, number 更新する値

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

挙動
文字列 指定された値に更新する
数値 指定された数値に更新する
型変換できない場合はその値は更新しない
日付 何が指定されても現在時刻に更新する
カウンタ 何が指定されてもその値を +1 する

Response (application/json)

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

ご不明な点はありませんか?

機能の詳細、導入のご検討、お見積もり依頼などは、お気軽にお問い合わせください。
担当者から追ってご連絡いたします。

お問い合わせはこちら

記事へ戻る