Twitter Direct Message API beta

Toru Furukawa

11 min readDec 3, 2017

Twitter っていうオンラインサービスのドキュメントを見ていると、Direct Message beta というのがある。それを使ってみたという話だ。

そうそう、この文章は pyspa advent calendar 2017 の 3日目。

免責事項

聞かれもしないのに、SNSで「ご報告」とかいうタイトルで結婚したことを書いてるやつみたいで申し訳ないんだけど、ああ書く必要ってあるんだなと気づいたので書いておく。

個人的に書いたものである。公開されている情報だけに基いて、自分でコードを書いて実行したらこうなった、という記録である。

これは挙動のサンプルであって、プロダクション環境でそのまま使うことを想定していないし、責任も持たない。

能書き

Direct Message （以下 DM）を使うようなコードがするのは、受信と送信である。今回は送信についてのみ書く。受信は (1) GET でポーリングする、(2) Streaming API で継続的に受信する、(3) Webhook API で都度呼び出してもらう、のいずれかになる。(3) は beta と書かれている。

基本

https:/api.twitter.com/1.1/direct_messages/events/new.json に POST する。Content-Type に application/json を指定し、body に JSONでリクエストパラメータを指定する。

{
  "event": {
    "type": "message_create", 
    "message_create": {
      "target": {"recipient_id": "xxxxxxxx"},     
      "message_data": {"text": "スパム"}
    }
  }
}

recipient_id には、宛先ユーザーの idを指定する。screen name じゃなくて、数字のid。

twurl を使うと以下のようになる。

twurl -A 'Content-type: application/json' -X POST /1.1/direct_messages/events/new.json -d '{"event": {"type": "message_create", "message_create": {"target": {"recipient_id": "xxxxxxxx"}, "message_data": {"text": "スパム"}}}}'

Quick Reply — options

Quick Reply の option list は、選択肢を提示するようなメッセージへの付加情報である。

各選択肢について label、description、metadata を指定できる。

{
  "event": {
    "type": "message_create",
    "message_create": {
      "target": {"recipient_id": "xxxxxxxx"},
      "message_data": {
        "text": "何食べる？",
        "quick_reply": {
          "type": "options",
          "options": [
            {
              "label": "spam", 
              "description": "great food",
              "metadata": "spam0"
            },
            {
              "label": "ham",
              "description": "good food",
              "metadata": "ham0"
            },
            {
              "label": "spam",
              "description": "spam",
              "metadata": "spam1"
            },
            {
              "label": "spam",
              "description": "spam",
              "metadata": "spam2"
            }
          ]
        }
      }
    }
  }
}

label と description は選択肢の見栄えを決定する。ユーザーがいずれかの選択肢をタップすると、label と metadata が送信され、受信側で取得できる。この例ではどの spam をタップしたかが分かるというわけだ。

twurl -A 'Content-type: application/json' -X POST /1.1/direct_messages/events/new.json -d '{"event": {"type": "message_create", "message_create": {"target": {"recipient_id": "xxxxxxxx"}, "message_data": {"text": "\u4f55\u98df\u3079\u308b\uff1f", "quick_reply": {"type": "options", "options": [{"label": "spam", "description": "great food", "metadata": "spam0"}, {"label": "ham", "description": "good food", "metadata": "ham0"}, {"label": "spam", "description": "spam", "metadata": "spam1"}, {"label": "spam", "description": "spam", "metadata": "spam2"}]}}}}}'

Quick Reply — location

Quick Reply として location を指定すると、ユーザーに位置情報を入力させられる。

ユーザーに現在位置の送信を強制できない。任意の経緯度か、 Yelp の place id かを選んで送信する。

リクエストパラメータは以下のとおり。metadata は任意。いったいどういう文脈で位置情報が来たか分かるように、ボットを作る側が用意しておく。

{
  "event": {
    "type": "message_create",
    "message_create": {
      "target": {"recipient_id": "xxxxxxxx"},
      "message_data": {
        "text": "どこにいるの？",
        "quick_reply": {
          "type": "location",
          "location": {"metadata": "external_id"}
        }
      }
    }
  }
}

twurl

twurl -A 'Content-type: application/json' -X POST /1.1/direct_messages/events/new.json -d '{"event": {"type": "message_create", "message_create": {"target": {"recipient_id": "xxxxxxxx"}, "message_data": {"text": "\u3069\u3053\u306b\u3044\u308b\u306e\uff1f", "quick_reply": {"type": "location", "location": {"metadata": "external_id"}}}}}}'

DM Button

Button は、メッセージに Call to Action 用のボタンを付加する情報。と言いつつ、これは任意のURLへのリンクを提供する機能。

リクエストパラメータは以下の感じ。

{
  "event": {
    "type": "message_create",
    "message_create": {
      "target": {"recipient_id": "xxxxxxxx"},
      "message_data": {
        "text": "うぇーい",
        "ctas": [
          {
            "type": "web_url",
            "label": "example",
            "url": "http://example.com/"
          },
          {
            "type": "web_url",
            "label": "ツイートする",
            "url": "https://twitter.com/intent/tweet?text=%E3%81%81%E3%81%A3%E3%81%89%E3%80%9C"
          }
        ]
      }
    }
  }
}

ひとつめのボタンは http://example.com/ へとばすだけのリンクになっている。

ふたつめのボタンは、Twitter の Web Intent URL になっていて、タップすると「ぁっぉ〜」というテキストを投稿しようとする。

JSON に渡すのは URL である。というわけで、 URL エンコードしたURLをパラメータとして渡す。

twurl を使うときは、-d オプションではうまくいかない。= でパースしてしまうから。JSON 全体を URL エンコードしたものを -r オプションで渡す必要がある。

twurl -A 'Content-type: application/json' -X POST /1.1/direct_messages/events/new.json -r '%7B%22event%22%3A%20%7B%22type%22%3A%20%22message_create%22%2C%20%22message_create%22%3A%20%7B%22target%22%3A%20%7B%22recipient_id%22%3A%20%22857061032736440320%22%7D%2C%20%22message_data%22%3A%20%7B%22text%22%3A%20%22%E3%81%86%E3%81%87%E3%83%BC%E3%81%84%22%2C%20%22ctas%22%3A%20%5B%7B%22type%22%3A%20%22web_url%22%2C%20%22label%22%3A%20%22example%22%2C%20%22url%22%3A%20%22http%3A//example.com/%22%7D%2C%20%7B%22type%22%3A%20%22web_url%22%2C%20%22label%22%3A%20%22%E3%83%84%E3%82%A4%E3%83%BC%E3%83%88%E3%81%99%E3%82%8B%22%2C%20%22url%22%3A%20%22https%3A//twitter.com/intent/tweet%3Ftext%3D%25E3%2581%2581%25E3%2581%25A3%25E3%2581%2589%25E3%2580%259C%22%7D%5D%7D%7D%7D%7D'

Welcome Message

DMのインターフェースに入ったとき、ユーザー側に表示するメッセージを指定できる。API でメッセージを複数登録できる。

Welcome message を、ひとつだけ「デフォルトのウェルカムメッセージ」として登録できる。これでDMに入った時、かならずこのメッセージが表示されるようになる。

welcome message のID を使って、DMの web intent を作ると、「このURLを踏むと、このウェルカムメッセージでDMが始まる」ということができる。

welcome message を表示しただけでは、bot 側にはなんの通知もいかない。Quick reply やキーボード入力からの送信したときに bot 側にeventが届く。

終わりに

すみません M-1 がそろそろ始まるんで、このへんで。 welcome message は地味なんで適当で勘弁してください。

@furni がサンプルらしいです。