Creatives

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

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

Resource URL

https://ads-api.twitter.com/4/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 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/4/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",
      "video_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "video_content_id": "958388276489895936",
      "preview_url": null,
      "id": "5a86h",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/958388276489895936/pl/q-gHLuId_71EFVdk.m3u8",
      "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",
      "video_poster_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/4/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/4/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",
    "video_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "video_content_id": "958388276489895936",
    "preview_url": null,
    "id": "5a86h",
    "account_id": "18ce54d4x5t",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/958388276489895936/pl/q-gHLuId_71EFVdk.m3u8",
    "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",
    "video_poster_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/4/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
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
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_958388276489895936
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
cover_image_id
optional

A media_id 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.

Type: long

Example: 883112887618682880
cover_video_id
optional

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

Type: string

Example: 13_867520357225418752
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: 883140118466265088
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

Example Request

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

Example Response

{
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "video_content_id": "958388276489895936",
    "preview_url": null,
    "id": "5a86h",
    "account_id": "18ce54d4x5t",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/958388276489895936/pl/q-gHLuId_71EFVdk.m3u8",
    "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",
    "video_poster_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",
      "video_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "video_content_id": "958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/958388276489895936/pl/q-gHLuId_71EFVdk.m3u8",
      "first_cta_tweet": "Ads API",
      "title": "Developers",
      "video_poster_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/4/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
cover_image_id
optional

A media_id 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.

Type: long

Example: 883112887618682880
cover_video_id
optional

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

Type: string

Example: 13_867520357225418752
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: 883140118466265088
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
name
optional

The name for the card.

Type: string

Example: developers card
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
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_771791717175468032

Example Request

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

Example Response

{
  "data": {
    "name": "developers card",
    "first_cta": "#APIs",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "video_content_id": "958388276489895936",
    "preview_url": null,
    "id": "5a86h",
    "account_id": "18ce54d4x5t",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/958388276489895936/pl/q-gHLuId_71EFVdk.m3u8",
    "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",
    "video_poster_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/4/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/4/accounts/18ce54d4x5t/cards/video_conversation/4i0ya

Example Response

{
  "data": {
    "name": "video conversation card",
    "id": "4i0ya",
    "account_id": "18ce54d4x5t",
    "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"
    }
  }
}