Standard beta Account Activity API - Direct Messages (retired)

Notice: We retired the Standard beta Account Activity API - Direct Messages on August 16th, 2018. The Premium and Enterprise versions of this API are not affected by this change.

Receive direct message activities via webhooks.

POST account_activity/webhooks

Registers a new webhook URL for the given application context. The URL will be validated via CRC request before saving. In case the validation fails, an error is returned. Only one webhook URL can be registered to an application.

See Securing Webhooks documentaion for webook requirement details.

Resource URL

https://api.twitter.com/1.1/account_activity/webhooks.json

Resource Information

Response Format JSON
Requires Authentication Yes (application validated only, but user context required)
Rate Limited Yes
Requests / 15-min window (app auth) 15

Note

Although only the application context is validated, a user context is required for all write endpoints. Best practice is to use the context of the application owner.

Parameters

url (required) Encoded URL for the callback endpoint.

Response

{
  "id": "1234",
  "url": "https://mydomain.com/webhook",
  "valid": true,
  "created_timestamp": "2016-06-02T23:54:02Z"
}

HTTP Response Codes

Code Message
200 Webhook URL registered to provided application.

Error Messages

Code Message
214 Webhook URL does not meet the requirements.
214 Too many resources already created.

GET account_activity/webhooks

Returns all URLs and their statuses for the given app. Currently, only one webhook URL can be registered to an application.

We mark a URL as invalid if it fails the daily validation check. In order to re-enable the URL, call the update endpoint.

Resource URL

https://api.twitter.com/1.1/account_activity/webhooks.json

Resource Information

Response Format JSON
Requires Authentication Yes (application only)
Rate Limited Yes
Requests / 15-min window (app auth) 15

Response

HTTP 200 OK
[
  {
    “id”: “1”,
    “url”: “https://united.fr/webhook”,
    “valid”: true,
    “created_timestamp”: “134325325301”
  }
]

HTTP Response Codes

Code Message
200 All webhooks URLs successfully returned.

DELETE account_activity/webhooks/:webhook_id

Removes the webhook from the provided application’s configuration. The webhook ID can be accessed by making a call to GET /1.1/account_activity/webhooks.

Resource URL

https://api.twitter.com/1.1/account_activity/webhooks/:webhook_id.json

Resource Information

Response Format JSON
Requires Authentication Yes (application only)
Rate Limited Yes
Requests / 15-min window (app auth) 15

Parameters

webhook_id (required) Webhook ID. Defined in resource path.

HTTP Response Codes

Code Message
204 Webhook has been removed from provided app.

PUT account_activity/webhooks/:webhook_id

Triggers the challenge response check (CRC) for the given webhook’s URL. If the check is successful, returns 204 and reenables the webhook by setting its status to valid.

Resource URL

https://api.twitter.com/1.1/account_activity/webhooks/:webhook_id.json

Resource Information

Response Format JSON
Requires Authentication Yes (application only)
Rate Limited Yes
Requests / 15-min window (app auth) 1

Parameters

webhook_id (required) Webhook ID. Defined in resource path.

HTTP Response Codes

Code Message
204 CRC request successful and webhook status set to valid.

Error Messages

Code Message
214 Webhook URL does not meet the requirements. Please consult: https://dev.twitter.com/webhook/security

POST account_activity/webhooks/:webhook_id/subscriptions

Subscribes the provided app to events for the provided user context. When subscribed, all DM events for the provided user will be sent to the app’s webhook via POST request.

Subscriptions are limited to a maxiumum of 50 users per application.

Resource URL

https://api.twitter.com/1.1/account_activity/webhooks/:webhook_id/subscriptions.json

Resource Information

Response Format JSON
Requires Authentication Yes (user context only)
Rate Limited Yes
Requests / 15-min window (per app) 15

Parameters

webhook_id (required) Webhook ID. Defined in resource path.

HTTP Response Codes

Code Message
204 Subscription added for provided user.

Error Messages

Code Message
348 Client application is not permitted to access this user’s webhook subscriptions.

GET account_activity/webhooks/:webhook_id/subscriptions

Provides a way to determine if a webhook configuration is subscribed to the provided user’s Direct Messages. If the provided user context has an active subscription with the provided app, returns 204 OK. If the response code is not 204, then the user does not have an active subscription. See HTTP Response code and error messages below for details.

Resource URL

https://api.twitter.com/1.1/account_activity/webhooks/:webhook_id/subscriptions.json

Resource Information

Response Format HTTP response code
Requires Authentication Yes (user context only)
Rate Limited Yes
Requests / 15-min window (per app) 750

Parameters

webhook_id (required) Webhook ID. Defined in resource path.

HTTP Response Codes

Code Message
204 User has authorized the app with DM permissions and app has active subscription for the user.
404 User has authorized the app with DM permissions, but there is no active subscription for the user.
401 User has not authorized the app or the user has authorized the app without DM permissions. See included Twitter error code and message for details.

Error Messages

Code Message
348 Client application is not permitted to access this user’s webhook subscriptions.
32 Could not authenticate you.

GET /account_activity/webhooks/:webhook_id/subscriptions/list

Returns a list of the current Direct Message type subscriptions for the specified webhook. Note that the /list endpoint requires app-only authentication (OAuth 2), so requests should be made using a bearer token instead of user access tokens.

Resource URL

https://api.twitter.com/1.1/account_activity/webhooks/<webhook_id>/subscriptions/list.json

Resource Information

Response Format HTTP response code
Requires Authentication Yes (App-only Oauth)
Rate Limited Yes
Requests / 15-min window (app-auth) 50

Parameters

webhook_id (required) Webhook ID. Defined in resource path.

HTTP Response Codes

Code Message
200 Success. A list of subscriptions for the requested webhook will be returned.
401 Your application does not have permission to view subscriptions for the specified webhook.

Example Response - Success

HTTP 200

{
"webhook_id": "99999",
"webhook_url": "https://myawesomewebsite.com/webhook",
"application_id": "13381694",
"subscriptions": [{
    "user_id": "123"
  },
  {
    "user_id": "456"
  },
  {
    "user_id": "789"
  }]
}

Error Messages

Code Message
32 Could not authenticate you.

DELETE account_activity/webhooks/:webhook_id/subscriptions

Deactivates subscription for the provided user context and app. After deactivation, all DM events for the requesting user will no longer be sent to the webhook URL.

Resource URL

https://api.twitter.com/1.1/account_activity/webhooks/:webhook_id/subscriptions.json

Resource Information

Response Format JSON
Requires Authentication Yes (user context only)
Rate Limited Yes
Requests / 15-min window (per app) 50

Parameters

webhook_id (required) Webhook ID. Defined in resource path.

HTTP Response Codes

Code Message
204 Active subscription for the user has been removed.
404 There is no active subscription for the user.

Error Messages

Code Message
348 Client application is not permitted to access this user’s webhook subscriptions.