Video Direct Message Cards¶

Note: card_uri is replacing preview_url. This moves associating a card with a Tweet from the Tweet text to a Tweet parameter. To associate a card with a Tweet, use the card_uri parameter with either the POST accounts/:account_id/tweet, POST statuses/update, or POST accounts/:account_id/scheduled_tweets endpoints. This allows users to use more characters in their Tweets.

GET accounts/:account_id/cards/video_direct_message¶

Retrieve details for some or all video direct message cards associated with the current account.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/cards/video_direct_message

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
card_ids optional	Scope the response to just the desired video DM cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `5a8av`
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
q optional	An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. Type: string Example: `aerial`
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: `created_at-asc`
with_deleted optional	Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false`
with_total_count optional	Include the `total_count` response attribute. Note: This parameter will be ignored if `cursor` is specified. Note: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request¶

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/cards/video_direct_message?card_ids=5a8av

Example Response¶

{
  "request": {
    "params": {
      "card_type": "video_direct_message",
      "card_ids": [
        "5a8av"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "video direct message card",
      "first_cta": "DM me",
      "first_cta_welcome_message_id": "865707372148174852",
      "video_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
      "recipient_user_id": "756201191646691328",
      "video_owner_id": "756201191646691328",
      "video_content_id": "953023103654797312",
      "preview_url": null,
      "id": "5a8av",
      "account_id": "18ce54d4x5t",
      "video_hls_url": "https://video.twimg.com/amplify_video/953023103654797312/pl/LaOEWcPzHpWoj_Iv.m3u8",
      "created_at": "2018-01-30T18:18:00Z",
      "card_uri": "card://958403939703054336",
      "updated_at": "2018-01-30T18:18:00Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/953023103654797312/img/56BNaul3VVrxf9Hw.jpg",
      "deleted": false,
      "card_type": "VIDEO_DIRECT_MESSAGE"
    }
  ]
}

GET accounts/:account_id/cards/video_direct_message/:card_id¶

Retrieve a specific video direct message card belonging to the current account.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/cards/video_direct_message/:card_id

Parameters¶

Name Description

account_id

required

The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

card_id

required

A reference to the video DM card you are operating with in the request.

Type: string

Example: 5a8av

with_deleted

optional

Include deleted results in your request.

Type: boolean

Default: false

Possible values: true, false

Example Request¶

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/cards/video_direct_message/5a8av

Example Response¶

{
  "request": {
    "params": {
      "card_type": "video_direct_message",
      "card_id": "5a8av",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "video direct message card",
    "first_cta": "DM me",
    "first_cta_welcome_message_id": "865707372148174852",
    "video_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
    "recipient_user_id": "756201191646691328",
    "video_owner_id": "756201191646691328",
    "video_content_id": "953023103654797312",
    "preview_url": null,
    "id": "5a8av",
    "account_id": "18ce54d4x5t",
    "video_hls_url": "https://video.twimg.com/amplify_video/953023103654797312/pl/LaOEWcPzHpWoj_Iv.m3u8",
    "created_at": "2018-01-30T18:18:00Z",
    "card_uri": "card://958403939703054336",
    "updated_at": "2018-01-30T18:18:00Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/953023103654797312/img/56BNaul3VVrxf9Hw.jpg",
    "deleted": false,
    "card_type": "VIDEO_DIRECT_MESSAGE"
  }
}

POST accounts/:account_id/cards/video_direct_message¶

Creates a new video direct message card associated to a given account.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/cards/video_direct_message

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
first_cta required	The Call-To-Action (CTA) text for the first option. Maximum length: 20 characters. Type: string Example: `DM me`
first_cta_welcome_message_id required	The welcome message ID to associate with the first CTA. Note: This welcome message must be owned by the user specified in `recipient_user_id`. Type: long Example: `865707372148174852`
name required	The name for the card. Type: string Example: `video direct message card`
recipient_user_id required	The user to start a conversation with, from the perspective of the user interacting with the card. Note: This must be the owner of the specified welcome messages. Type: long Example: `756201191646691328`
video_id required	The identifier of a video from the GET accounts/:account_id/media_library endpoint to be included in the card. Note: An aspect ratio of 16:9 is required. Type: string Example: `13_953023103654797312`
image_media_id optional	Specify a poster image for the video using the `media_id` of an uploaded image. If not specified, the first frame will be used. Poster image dimensions should match the video dimensions. This is a write-only field. In the response, the API will provide a Twitter URL for this image. Type: long Example: `929428315226749255`
second_cta optional	The Call-To-Action (CTA) text for the second option. Maximum length: 20 characters. Type: string Example: `Browse Moments`
second_cta_welcome_message_id optional	The welcome message ID to associate with the second CTA. Note: This welcome message must be owned by the user specified in `recipient_user_id`. Type: long Example: `905953936925695848`
third_cta optional	The Call-To-Action (CTA) text for the third option. Maximum length: 20 characters. Type: string Example: `Play a bot song`
third_cta_welcome_message_id optional	The welcome message ID to associate with the third CTA. Note: This welcome message must be owned by the user specified in `recipient_user_id`. Type: long Example: `933237054790401013`
fourth_cta optional	The Call-To-Action (CTA) text for the fourth option. Maximum length: 20 characters. Type: string Example: `Play Twitter Trivia`
fourth_cta_welcome_message_id optional	The welcome message ID to associate with the fourth CTA. Note: This welcome message must be owned by the user specified in `recipient_user_id`. Type: long Example: `929280268839051451`

Example Request¶

POST https://ads-api.twitter.com/3/accounts/18ce54d4x5t/cards/video_direct_message?first_cta=DM me&first_cta_welcome_message_id=865707372148174852&name=video direct message card&recipient_user_id=756201191646691328&video_id=13_953023103654797312

Example Response¶

{
  "data": {
    "name": "video direct message card",
    "first_cta": "DM me",
    "first_cta_welcome_message_id": "865707372148174852",
    "video_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
    "recipient_user_id": "756201191646691328",
    "video_owner_id": "756201191646691328",
    "video_content_id": "953023103654797312",
    "preview_url": null,
    "id": "5a8av",
    "account_id": "18ce54d4x5t",
    "video_hls_url": "https://video.twimg.com/amplify_video/953023103654797312/pl/LaOEWcPzHpWoj_Iv.m3u8",
    "created_at": "2018-01-30T18:18:00Z",
    "card_uri": "card://958403939703054336",
    "updated_at": "2018-01-30T18:18:00Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/953023103654797312/img/56BNaul3VVrxf9Hw.jpg",
    "deleted": false,
    "card_type": "VIDEO_DIRECT_MESSAGE"
  },
  "request": {
    "params": {
      "video_poster_height": "9",
      "name": "video direct message card",
      "first_cta": "DM me",
      "first_cta_welcome_message_id": "865707372148174852",
      "video_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
      "recipient_user_id": "756201191646691328",
      "video_owner_id": "756201191646691328",
      "video_content_id": "953023103654797312",
      "account_id": "18ce54d4x5t",
      "video_hls_url": "https://video.twimg.com/amplify_video/953023103654797312/pl/LaOEWcPzHpWoj_Iv.m3u8",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/953023103654797312/img/56BNaul3VVrxf9Hw.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_DIRECT_MESSAGE"
    }
  }
}

PUT accounts/:account_id/cards/video_direct_message/:card_id¶

Update the specified video direct message card belonging to the current account.

Note: It is not possible to update the recipient_user_id as all welcome messages must belong to user specified in the create (POST) request.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/cards/video_direct_message/:card_id

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
card_id required	A reference to the video DM card you are operating with in the request. Type: string Example: `4zjee`
image_media_id optional	Specify a poster image for the video using the `media_id` of an uploaded image. If not specified, the first frame will be used. Poster image dimensions should match the video dimensions. This is a write-only field. In the response, the API will provide a Twitter URL for this image. Type: long Example: `929428315226749255`
first_cta optional	The Call-To-Action (CTA) text for the first option. Maximum length: 20 characters. Type: string Example: `Tell me a joke`
first_cta_welcome_message_id optional	The welcome message ID to associate with the first CTA. Note: This welcome message must be owned by the user specified in `recipient_user_id`. Type: long Example: `930384951649221544`
second_cta optional	The Call-To-Action (CTA) text for the second option. Maximum length: 20 characters. Type: string Example: `Browse Moments`
second_cta_welcome_message_id optional	The welcome message ID to associate with the second CTA. Note: This welcome message must be owned by the user specified in `recipient_user_id`. Type: long Example: `915193968850536077`
third_cta optional	The Call-To-Action (CTA) text for the third option. Maximum length: 20 characters. Type: string Example: `Play a bot song`
third_cta_welcome_message_id optional	The welcome message ID to associate with the third CTA. Note: This welcome message must be owned by the user specified in `recipient_user_id`. Type: long Example: `908983224974380367`
fourth_cta optional	The Call-To-Action (CTA) text for the fourth option. Maximum length: 20 characters. Type: string Example: `Play Twitter Trivia`
fourth_cta_welcome_message_id optional	The welcome message ID to associate with the fourth CTA. Note: This welcome message must be owned by the user specified in `recipient_user_id`. Type: long Example: `936232223055682535`
name optional	The name for the card. Type: string Example: `winter card`
video_id optional	The identifier of a video from the GET accounts/:account_id/media_library endpoint to be included in the card. Note: An aspect ratio of 16:9 is required. Type: string Example: `13_928298439871906925`

Example Request¶

PUT https://ads-api.twitter.com/3/accounts/18ce54d4x5t/cards/video_direct_message/5a8av?name=winter card

Example Response¶

{
  "data": {
    "name": "winter card",
    "first_cta": "DM me",
    "first_cta_welcome_message_id": "865707372148174852",
    "video_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
    "recipient_user_id": "756201191646691328",
    "video_owner_id": "756201191646691328",
    "video_content_id": "953023103654797312",
    "preview_url": null,
    "id": "5a8av",
    "account_id": "18ce54d4x5t",
    "video_hls_url": "https://video.twimg.com/amplify_video/953023103654797312/pl/LaOEWcPzHpWoj_Iv.m3u8",
    "created_at": "2018-01-30T18:18:00Z",
    "card_uri": "card://958403939703054336",
    "updated_at": "2018-01-30T18:24:54Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/953023103654797312/img/56BNaul3VVrxf9Hw.jpg",
    "deleted": false,
    "card_type": "VIDEO_DIRECT_MESSAGE"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_DIRECT_MESSAGE",
      "card_id": "5a8av",
      "name": "winter card"
    }
  }
}

DELETE accounts/:account_id/cards/video_direct_message/:card_id¶

Permanently delete the specified video direct message card belonging to the current account.

Note: This is a hard delete. As a result, it is not possible to retrieve deleted cards.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/cards/video_direct_message/:card_id

Parameters¶

Name Description

account_id

required

Type: string

Example: 18ce54d4x5t

card_id

required

A reference to the video DM card you are operating with in the request.

Type: string

Example: 4zjee

Example Request¶

DELETE https://ads-api.twitter.com/3/accounts/18ce54d4x5t/cards/video_direct_message/4zjee

Example Response¶

{
  "data": {
    "name": "video DM card",
    "id": "4zjee",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-11-06T04:35:44Z",
    "updated_at": "2017-11-06T04:43:42Z",
    "deleted": true,
    "card_type": "VIDEO_DIRECT_MESSAGE"
  },
  "request": {
    "params": {
      "card_id": "4zjee",
      "card_type": "video_direct_message",
      "account_id": "18ce54d4x5t"
    }
  }
}

Creatives

Video Direct Message Cards¶

GET accounts/:account_id/cards/video_direct_message¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

GET accounts/:account_id/cards/video_direct_message/:card_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

POST accounts/:account_id/cards/video_direct_message¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

PUT accounts/:account_id/cards/video_direct_message/:card_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

DELETE accounts/:account_id/cards/video_direct_message/:card_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶