Video Direct Message Cards

Note: 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.

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/8/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 and cursor are exclusive.

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/8/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",
      "media_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
      "recipient_user_id": "756201191646691328",
      "video_owner_id": "756201191646691328",
      "media_key": "13_953023103654797312",
      "id": "5a8av",
      "created_at": "2018-01-30T18:18:00Z",
      "card_uri": "card://958403939703054336",
      "updated_at": "2018-01-30T18:18:00Z",
      "poster_media_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/8/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/8/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",
    "media_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
    "recipient_user_id": "756201191646691328",
    "video_owner_id": "756201191646691328",
    "media_key": "13_953023103654797312",
    "id": "5a8av",
    "created_at": "2018-01-30T18:18:00Z",
    "card_uri": "card://958403939703054336",
    "updated_at": "2018-01-30T18:18:00Z",
    "poster_media_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/8/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

media_key
required

The media key for a video to be used in this card.

Note: The video must be in the account's Media Library.

Note: An aspect ratio of 16:9 is required.

Type: string

Example: 13_1168079965037467209

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

poster_media_key
optional

The media key for a poster image to be used in this card. If not specified, the first frame will be used.

Note: The video must be in the account's Media Library.

Type: long

Example: 3_882726458191298561

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/8/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&media_key=13_953023103654797312

Example Response

{
  "data": {
    "name": "video direct message card",
    "first_cta": "DM me",
    "first_cta_welcome_message_id": "865707372148174852",
    "media_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
    "recipient_user_id": "756201191646691328",
    "video_owner_id": "756201191646691328",
    "media_key": "13_953023103654797312",
    "id": "5a8av",
    "created_at": "2018-01-30T18:18:00Z",
    "card_uri": "card://958403939703054336",
    "updated_at": "2018-01-30T18:18:00Z",
    "poster_media_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",
      "media_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
      "recipient_user_id": "756201191646691328",
      "video_owner_id": "756201191646691328",
      "media_key": "13_953023103654797312",
      "account_id": "18ce54d4x5t",
      "poster_media_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/8/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

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

media_key
optional

The media key for a video to be used in this card.

Note: The video must be in the account's Media Library.

Note: An aspect ratio of 16:9 is required.

Type: string

Example: 13_1168079965037467209

name
optional

The name for the card.

Type: string

Example: winter card

poster_media_key
optional

The media key for a poster image to be used in this card. If not specified, the first frame will be used.

Note: The video must be in the account's Media Library.

Type: long

Example: 3_882726458191298561

Example Request

PUT https://ads-api.twitter.com/8/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",
    "media_url": "https://video.twimg.com/amplify_video/vmap/953023103654797312.vmap",
    "recipient_user_id": "756201191646691328",
    "video_owner_id": "756201191646691328",
    "media_key": "13_953023103654797312",
    "id": "5a8av",
    "created_at": "2018-01-30T18:18:00Z",
    "card_uri": "card://958403939703054336",
    "updated_at": "2018-01-30T18:24:54Z",
    "poster_media_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/8/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

Example Request

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

Example Response

{
  "data": {
    "name": "video DM card",
    "id": "4zjee",
    "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"
    }
  }
}

Was this document helpful?

Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.