Twitter Account Activity API

The Account Activity API (beta) delivers realtime access to activities related to a Twitter account via webhooks. The Account Activity API currently only supports delivery of Direct Messages.

During the beta, access to the API is provided up to 50 account subscriptions per webhook and up to one webhook per Twitter application.

Receiving Webhook Events

The request to your webhook URL is a POST request. All requests to your webhook URL are over HTTPS. Currently, only Direct Message events are available via the Account Activity API.

A user subscription created with 
POST account_activity/webhooks/:webhook_id/subscriptions
is required to receive events for a user. Events for messages received AND sent to a user will be sent to the webhook. The source_app_id, recipient_id or sender_id can help determine if the message is incoming or outgoing from the user or application.

In some cases your webhook may receive duplicate events. Your webhook application should be tolerant of this and dedupe by event ID.

Callback requests contain three top level objects.

  • direct_message_events: An array of Direct Message Event objects.
  • users: An object containing hydrated user objects keyed by user ID.
  • apps: An object containing hydrated application objects keyed by app ID.

Example Request — Outgoing Message

{
"direct_message_events": [
{
"type": "message_create",
"id": "1234858585",
"created_timestamp": "1392078023507",
"message_create": {
"target": {
"recipient_id": "3805104374"
},
"sender_id": "1234858592",
"source_app_id": "8829219",
"message_data": {
"text": "What's your favorite type of bird?",
"entities": {
"hashtags": [],
"symbols": [],
"urls": [],
"user_mentions": [],
},
"quick_reply": {
"type": "options",
"options": [
{"label": "Red Bird", "metadata": "external_id_1"},
{"label": "Blue Bird", "metadata": "external_id_2"},
{"label": "Black Bird", "metadata": "external_id_3"},
{"label": "White Bird" , "metadata": "external_id_4"}
]
},
"attachment": {
"type": "media",
"media": {
...
}
}
}
}
}
...
],
  "users": {
"1234858592": {
"id": "1234858592",
"created_timestamp": "1415320482361",
"name": "TwitterDev",
"screen_name": "TwitterDev",
"location": "Internet",
"description": "Developer and Platform Relations @Twitter. We are developer advocates. We can't answer all your questions, but we listen to all of them!",
"protected": false,
"verified": true,
"followers_count": 440643,
"friends_count": 1534,
"statuses_count": 2837,
"profile_image_url": "http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"
},
    "3805104374": {
"id": "3805104374",
"created_timestamp": "1449607341142",
"name": "Furni",
"screen_name": "furni",
"location": "San Francisco, CA",
"description": "Furni is Twitter's example company to showcase new developer features.",
"protected": false,
"verified": false,
"followers_count": 297,
"friends_count": 7,
"statuses_count": 1,
"profile_image_url": "http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"
}
},
  "apps": {
"8829219": {
"id": "8829219",
"name": "Furni",
"url": "https://twitter.com/furni"
}
}
}

Example Request — Incoming Message

If a quick reply response is included in the incoming message, the type and metadata will be present in the quick_reply_response object. The label for the chosen option is sent as the message text. The users object contains hydrated condensed user objects using user IDs in direct_message_event objects as keys.

{
"direct_message_events": [
{
"type": "message_create",
"id": "1234858589",
"created_timestamp": "1392078023603",
"message_create": {
"target": {
"recipient_id": "1234858592"
},
"sender_id": "3805104374",
"source_app_id": "268278",
"message_data": {
"text": "Blue Bird",
"entities": {
"hashtags": [],
"symbols": [],
"urls": [],
"user_mentions": [],
},
"quick_reply_response": {
"type": "options",
"metadata": "external_id_2"
},
"attachment": {
"type": "media",
"media": {
...
}
}
}
}
}
...
],
"users": {
"1234858592": {
"id": "1234858592",
"created_timestamp": "1415320482361",
"name": "TwitterDev",
"screen_name": "TwitterDev",
"location": "Internet",
"description": "Developer and Platform Relations @Twitter. We are developer advocates. We can't answer all your questions, but we listen to all of them!",
"protected": false,
"verified": true,
"followers_count": 440643,
"friends_count": 1534,
"statuses_count": 2837,
"profile_image_url": "http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"
},
"3805104374": {
"id": "3805104374",
"created_timestamp": "1449607341142",
"name": "Furni",
"screen_name": "furni",
"location": "San Francisco, CA",
"description": "Furni is Twitter's example company to showcase new developer features.",
"protected": false,
"verified": false,
"followers_count": 297,
"friends_count": 7,
"statuses_count": 1,
"profile_image_url": "http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"
}
},
"apps": {
"268278": {
"id": "268278",
"name": "Twitter Web Client",
"url": "http://twitter.com"
}
}
}

Object: Direct Message Event

Direct Message Event objects are returned by

GET direct_messages/events/list 
GET direct_messages/events/show

and can be consumed in real-time using the Account Activity API.

  • type: The type of event. Currently only message_create.
  • id: The ID of the direct message event.
  • created_timestamp: Epoch timestamp of when the Direct Message event was created.
  • initiated_via.tweet_id: The ID of the Tweet with Direct Message Prompt the conversation was initiated from if one was used.
  • initiated_via.welcome_message_id: The ID of the Welcome Message immediately preceding the conversation if one was used.