Video Conversation 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_conversation

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

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/cards/video_conversation

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 conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 5a86h

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: night sky

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_conversation?card_ids=5a86h

Example Response

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_ids": [
        "5a86h"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "id": "5a86h",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "created_at": "2018-01-30T17:53:04Z",
      "card_uri": "card://958397665015775232",
      "title": "Developers",
      "updated_at": "2018-01-30T17:53:04Z",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "deleted": false,
      "card_type": "VIDEO_CONVERSATION"
    }
  ]
}

GET accounts/:account_id/cards/video_conversation/:card_id

Retrieve a specific video conversation card associated with the current account.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/cards/video_conversation/: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 conversation card you are operating with in the request.

Type: string

Example: 4i0ya

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_conversation/5a86h

Example Response

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  }
}

POST accounts/:account_id/cards/video_conversation

Create a new video conversation card associated with the specified account.

See Uploading Media for useful information on uploading images to our endpoints.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/cards/video_conversation

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) hashtag for the first option. Maximum length: 20 characters (not counting the #).

Type: string

Example: #APIs

first_cta_tweet
required

The Tweet text to be used when the first CTA is clicked.

Type: string

Example: Ads API

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 conversation card

thank_you_text
required

The text to be displayed after the CTA is clicked. Maximum length: 23 characters.

Type: string

Example: Build it

title
sometimes required

The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters.

Type: string

Note: Required if second_cta is not set.

Example: Developers

second_cta
sometimes required

The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).

Type: string

Note: Required if title is not set.

Example: #ShareAgain

second_cta_tweet
sometimes required

The Tweet text to be used when the second CTA is clicked.

Note: Required if second_cta is set.

Type: string

Example: I Heart @AdsAPI Again

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

third_cta
optional

The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).

Type: string

Example: #ShareMore

third_cta_tweet
sometimes required

The Tweet text to be used when the third CTA is clicked.

Type: string

Note: Required if third_cta is set.

Example: I Heart @TwitterDev

fourth_cta
optional

The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).

Type: string

Example: #ShareExtra

fourth_cta_tweet
sometimes required

The Tweet text to be used when the fourth CTA is clicked.

Type: string

Note: Required if fourth_cta is set.

Example: I Heart @TwitterDev Again

thank_you_url
optional

The URL to be displayed with the thank you text.

Type: string

Example: https://example.com/thankyou

unlocked_image_media_key
optional

A media_key of an image which will be used in the instant unlock scenario.

This is a write-only field. In the response, the API will provide a Twitter URL for this image.

Note: The image must be in the account's media library.

Type: string

Example: 3_883112887618682880

unlocked_video_media_key
optional

The identifier of a video from the GET accounts/:account_id/media_library endpoint which will be used in the instant unlock scenario.

Type: string

Example: 13_867520357225418752

Example Request

POST https://ads-api.twitter.com/8/accounts/18ce54d4x5t/cards/video_conversation?first_cta=#APIs&first_cta_tweet=Ads API&name=video conversation card&thank_you_text=Build it&title=Developers&media_key=13_958388276489895936

Example Response

{
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "video_poster_height": "9",
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "title": "Developers",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_CONVERSATION"
    }
  }
}

PUT accounts/:account_id/cards/video_conversation/:card_id

Update the specified video conversation card belonging to the current account.

See Uploading Media for useful information on uploading images to our endpoints.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/cards/video_conversation/: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 conversation card you are operating with in the request.

Type: string

Example: 5a86h

first_cta
optional

The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).

Type: string

Example: #APIs

first_cta_tweet
optional

The Tweet text to be used when the first CTA is clicked.

Type: string

Example: Ads API

second_cta
optional

The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).

Type: string

Note: Required if title is not set.

Example: #ShareAgain

second_cta_tweet
optional

The Tweet text to be used when the second CTA is clicked.

Note: Required if second_cta is set.

Type: string

Example: I Heart @AdsAPI Again

third_cta
optional

The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).

Type: string

Example: #ShareMore

third_cta_tweet
optional

The Tweet text to be used when the third CTA is clicked.

Type: string

Note: Required if third_cta is set.

Example: I Heart @TwitterDev

fourth_cta
optional

The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).

Type: string

Example: #ShareExtra

fourth_cta_tweet
optional

The Tweet text to be used when the fourth CTA is clicked.

Type: string

Note: Required if fourth_cta is set.

Example: I Heart @TwitterDev Again

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: developers 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

thank_you_text
optional

The text to be displayed after the CTA is clicked. Maximum length: 23 characters.

Type: string

Example: Build it

thank_you_url
optional

The URL to be displayed with the thank you text.

Type: string

Example: https://example.com/thankyou

title
optional

The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters.

Type: string

Note: Required if second_cta is not set.

Example: Start a conversation

unlocked_image_media_key
optional

A media_key of an image which will be used in the instant unlock scenario.

This is a write-only field. In the response, the API will provide a Twitter URL for this image.

Note: The image must be in the account's media library.

Type: string

Example: 3_883112887618682880

unlocked_video_media_key
optional

The identifier of a video from the GET accounts/:account_id/media_library endpoint which will be used in the instant unlock scenario.

Type: string

Example: 13_867520357225418752

Example Request

PUT https://ads-api.twitter.com/8/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card

Example Response

{
  "data": {
    "name": "developers card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T18:02:15Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_CONVERSATION",
      "card_id": "5a86h",
      "name": "developers card"
    }
  }
}

DELETE accounts/:account_id/cards/video_conversation/:card_id

Permanently delete the specified video conversation 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_conversation/: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 conversation card you are operating with in the request.

Type: string

Example: 4i0ya

Example Request

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

Example Response

{
  "data": {
    "name": "video conversation card",
    "id": "4i0ya",
    "created_at": "2017-07-07T01:36:39Z",
    "updated_at": "2017-08-23T13:29:13Z",
    "deleted": true,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0ya",
      "card_type": "video_conversation",
      "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.