Standard beta Account Activity API - Direct Messages

POST account_activity/direct_messages/:env_name/subscriptions

Subscribes the provided app to all events for the provided environment for direct messages. After activation, all events for the requesting user will be sent to the app’s webhook via POST request. Idempotent call.

Subscriptions are currently limited based on your account configuration. If you have a need to add more subscriptions, please contact your account manager.

Resource URL

https://api.twitter.com/1.1/account_activity/direct_messages/:env_name/subscriptions.json

Resource Information

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

Parameters

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

Example Response - Success

HTTP 204 NO CONTENT

{}

Error Messages

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

POST 1.1/account_activity/direct_messages/:env_name/webhooks

Registers a new webhook URL for direct messages. The URL will be validated via CRC request before saving. In case the validation failed, returns comprehensive error message to the requester.

Only one webhook URL can be registered to an application.

Resource URL

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

Resource Information

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

Parameters

url (required) Encoded URL for the callback endpoint.

Example Request

POST https://api.twitter.com/1.1/account_activity/webhooks.json?url=https%3A%2F%2myawesomewebsite.com%2Fwebhook

HTTP Responses

HTTP Code Message
200 Webhook URL is registered to the provided application
403 There is an error with your request. See error messages section below.

Example Response - Success

HTTP 200

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

Error Messages

Code Message
214 Webhook URL does not meet the requirements.
214 Too many resources already created.
214 Webhook URL does not meet the requirements. Invalid CRC token or json response format.
214 High latency on CRC GET request. Your webhook should respond in less than 1 second.
214 Non-200 response code during CRC GET request (i.e. 404, 500, etc).

HTTP 403

{
  "errors": [
    {
      "code": 214,
      "message": "Too many resources already created."
    }
  ]
}

GET account_activity/direct_messages/webhooks

Returns all URLs and their statuses for the given app for direct messages. 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/direct_messages/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://mydomain.com/twitter/webhook”,
    “valid”: true,
    “created_timestamp”: “134325325301”
  }
]

Error Messages

Code Message
99 You don’t have access to this resource.

GET account_activity/direct_messages/count

Returns the count of subscriptions that are currently active on your account for direct messages. Note that the /count endpoint requires App-only Oauth, so that you should make requests using a bearer token instead of app-user auth.

Resource URL

https://api.twitter.com/1.1/account_activity/all/count.json

Resource Information

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

HTTP Response Codes

Example Response - Success

HTTP 200

{
"account_name": "test-account",
"subscriptions_count_all": "2",
"subscriptions_count_direct_messages": "1"
}

Error Messages

Code Message
32 Could not authenticate you.

HTTP 401

{
  "errors": [
    {
       "code": 32,
      "message": "Could not authenticate you."
    }
  ]
}

GET account_activity/direct_messages/:env_name/webhooks

Returns all URLs and their statuses for the given environment for direct messages. 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/direct_messages/:env_name/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://mydomain.com/twitter/webhook”,
    “valid”: true,
    “created_timestamp”: “134325325301”
  }
]

Error Messages

Code Message
99 You don’t have access to this resource.

PUT account_activity/direct_messages/:env_name/webhooks

Triggers the challenge response check (CRC) for the given enviroments webhook for direct messages. 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/direct_messages/:env_name/webhooks.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.

Response

HTTP 204 OK

{ }

Error Messages

Code Message
214 Webhook URL does not meet the requirements.
214 Webhook URL does not meet the requirements. Invalid CRC token or json response format.
214 High latency on CRC GET request. Your webhook should respond in less than 1 second.
214 Non-200 response code during CRC GET request (i.e. 404, 500, etc).

DELETE account_activity/direct_messages/:env_name/webhooks/<webhook_id>

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

Resource URL

https://api.twitter.com/1.1/account_activity/direct_messages/:env_name/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.

Response

HTTP 204 OK

{ }

DELETE account_activity/direct_messages/:env_name/subscriptions

Deactivates subscription(s) for the provided user context and app for direct messages. After deactivation, all Direct Message events for the requesting user will no longer be sent to the webhook URL.

Resource URL

https://api.twitter.com/1.1/account_activity/all/:env_name/subscriptions.json

Resource Information

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

Parameters

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