（翻訳）Webhook Reference - facebook for developers

（※ 本ページは、facebook for developer にあるページの勝手翻訳です。）
https://developers.facebook.com/docs/messenger-platform/webhook-reference

----

# Webhook Reference

下記は、Messenger Platform を使って君の Webhook に届くコールバック（Callbacks）の説明だ。

もし君が、Webbook の設定についてもっと知りたいのであれば、この[詳細な解説](https://developers.facebook.com/docs/graph-api/webhooks)を読んでほしい。本ドキュメントは、全般的な設定、Facebook側から来るデータのフォーマットとそのデータの検証方法について説明する。


## 設定（Setup）

君が Webhook の設定をする時、次の６つの項目が選択項目として目にかかるだろう。全てオプショナルな項目で、必要に応じて選択してくれ。どの項目もコールバックに紐づいている。

| 項目 | 説明  |訳注|
|:-----|:------|:------|
| message              | [`Message Received Callback`][link-cb-mess]の登録 |テキストメッセージや添付されたデータ（画像、音声、映像、ファイルやロケーション情報など）のイベントを処理する。|
| messaging_postbacks  | [`Postback Received Callback`][link-cb-post]の登録 | Postbackボタン[^1]、[Get Startedボタン][link-ex-gets]、[Persistent Menu][link-ex-perm]やStructured Messageがタップされた時のイベントを処理する。|
| messaging_optins     | [`Send-to-Messenger Plugin`][link-ex-s2mp]経由での [`Authentication Callback`][link-cb-auth]の登録 | [Send-to-Messengerプラグイン][link-ex-s2mp]がタップされた際に呼ばれるイベントを処理する。|
| message_deliveries   | [`Message Delivered Callback`][link-cb-mdli]の登録 | メッセージが配信された時のイベントを処理する。|
| message_reads        | [`Message Read Callback`][link-cb-read]の登録 | メッセージがユーザーに読まれた時のイベントを処理する。|
| message_echoes       | [`Message Echo Callback`][link-cb-echo]の登録 |Facebookページからメッセージが送られた際に発動するイベント処理用コールバックで、テキストや添付データを処理する。|

![Fig.1](https://scontent-nrt1-1.xx.fbcdn.net/t39.2365-6/13509233_503116336549432_1721690749_n.png)
（Facebook の当該ページより引用）

[^1]: 再度 Webhook をコールするような仕組みになるボタン
[link-cb-mess]:https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-received
[link-cb-post]:https://developers.facebook.com/docs/messenger-platform/webhook-reference/postback-received
[link-cb-auth]:https://developers.facebook.com/docs/messenger-platform/webhook-reference/authentication
[link-cb-mdli]:https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-delivered
[link-cb-read]:https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-read
[link-cb-echo]:https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-echo
[link-ex-gets]:https://developers.facebook.com/docs/messenger-platform/thread-settings/get-started-button
[link-ex-perm]:https://developers.facebook.com/docs/messenger-platform/thread-settings/persistent-menu
[link-ex-s2mp]:https://developers.facebook.com/docs/messenger-platform/plugin-reference/send-to-messenger

## アプリをページに登録する（Subscribe App to Page）

アプリを、ページ（訳注：Facebookページ）の更新情報と紐づくよう、登録をする。「Messenger」タブ内の項目「Webhooks section」で可能だ。

> :information_source: 1つのページあたり、10個のアプリを紐づけることができる。

![Fig.2](https://scontent-nrt1-1.xx.fbcdn.net/t39.2365-6/13466568_984470978337660_125967052_n.png)
（Facebook の当該ページより引用）

または、APIを使ってこのようにしてもいい。

```shell-session
curl -X POST "https://graph.facebook.com/v2.6/me/subscribed_apps?access_token=PAGE_ACCESS_TOKEN" 
```

次のような応答が返ってくれば、成功だ。

```shell-session
{
  "success": true
}  
```

## 一般的なフォーマット（Common Format）

Messeenger Platform の全てのコールバックは、次のような一般構造を持っている。

```json
{
  "object":"page",
  "entry":[
    {
      "id":"PAGE_ID",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"USER_ID"
          },
          "recipient":{
            "id":"PAGE_ID"
          },

          ...
        }
      ]
    }
  ]
} 
```

### ペイロード

| フィールド名 | 説明 | 型 |
|:-----------|:------------|:-----|
|object      |固定値`page`        |String |
|entry       |イベントデータの配列 | Array of *entry* |

### `entry` オブジェクト

| フィールド名 | 説明 | 型 |
|:-----------|:------------|:-----|
|id        |ページのID                       |String
|time      |情報更新時刻(ミリ秒/エポック時間) |Number
|messaging |`messaging`オブジェクトの配列     |Array of messaging

### `messaging` オブジェクト

| フィールド名 | 説明 | 型 |
|:-----------|:------------|:-----|
|sender.id    |送信ユーザーID                   |String
|recipient.id |受信ユーザーID                   |String
|...          |その他、コールバック毎固有のデータ |

> :information_source: ユーザーを指し示すためのIDとして、page-scoped IDs(PSID)を用いている。すなわち、ページ毎にユーザのIDはユニークになる。
> :information_source: もし君が [Facebook Login](https://developers.facebook.com/docs/facebook-login) 機能を実装している場合、ユーザーIDは、app-scoped なものとなり、Messenger Platform では機能しないだろう。


## 応答

君が実装する Webhook は、Fackbook側から呼ばれる場合`200 OK`のHTTP ステータスコードを返す必要がある。もしこの200応答に失敗しているような場合は、Messenger Platform によって、[登録解除](https://developers.facebook.com/docs/messenger-platform/webhook-reference#unsubscribe) される場合もある。

君の Webhook がデータを受け入れ次第、メッセージ到着情報がユーザー側に自動的に届けられる。加えて、メッセージ確認済み情報を[送信アクション](https://developers.facebook.com/docs/messenger-platform/send-api-reference/sender-actions)を使って送ることも可能だ。


### 登録解除

もし、君の Webhook がエラーを返すような状態（例えば、`2xx`ではないステータスを返す、など）や、15分以上タイムアウトな状態（応答するのに20秒以上時間をかけている状態）の場合、我々Facebookは、開発警告メッセージを君に送るだろう。

８時間エラー状態が続いた場合、我々は Webhook が利用不可能で君のアプリから登録を解除した旨の開発警告メッセージを送るだろう。問題を解決したあとは、Webhookを[再登録してほしい](https://developers.intern.facebook.com/docs/messenger-platform/webhook-reference#subsribe)。

![Fig.3](https://scontent-nrt1-1.xx.fbcdn.net/t39.2365-6/13480194_134179967005698_496318901_n.png)
（Facebook の当該ページより引用）


### データ処理

（ペイロード中の）`entry`オブジェクトは、複数のオブジェクトの配列だ。加えて、配列 `messaging` も複数のオブジェクトを有している。全てのイベントについて処理をするために、これら`entry`と`messaging`の中身について繰り返し処理を行ってほしい。どの`messaging`オブジェクトも`sender`と`recipient`のデータを持っている。そしてオブジェクトは、コールバックの種類によりそのデータの中身が異なってくる。

> :information_source: たぶん我々Facebookは、特に処理が立て込んでいる高負荷な場合など、一度のコールバック処理で複数のイベントを処理するだろう。そういう事情から、（Webhookへ）送ったデータの全てのイベントに対しての情報が取れるよう、`entry`と`messaging`に関しての繰り返し処理を確実にして応答メッセージに入れてほしい。


### セキュリティ

HTTPリクエストは、リクエストのペイロード・データからSHA1アルゴリズムによって作られた署名を、`X-Hub-Signature`というヘッダ名で含んでいる。これは、`sha1=`から始まる、アプリの秘密鍵を用いて作られた文字列だ。

君のコールバックのエンドポイント（のプログラム）は、この署名から、オリジナルのペイロード・データであるかどうかの正常性を検証できる。

ここでちょっと覚えてて欲しいのが、ペイロード・データ中では16進数小文字化でのUNICODEのエスケープ処理が行われていることだ。デコードしたバイト列をそのまま用いて（比較用の）署名を作成しても、本来使いたいものとは違う署名となるので注意だ。例えば、`äöå`という文字列は、`\u00e4\u00f6\u00e5`とエスケープされている。