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/3/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: |
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: |
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: |
q
optional
|
An optional query to scope cards by Type: string Example: |
sort_by
optional
|
Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: |
with_deleted
optional
|
Include deleted results in your request. Type: boolean Default:
false Possible values:
true , false |
with_total_count
optional
|
Include the Note: This parameter will be ignored if Note: Requests which include Type: boolean Default:
false Possible values:
true , false |
Example Request¶
GET https://ads-api.twitter.com/3/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/3/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: |
card_id
required
|
A reference to the video conversation card you are operating with in the request. Type: string Example: |
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_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/3/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: |
first_cta
required
|
The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: |
first_cta_tweet
required
|
The Tweet text to be used when the first CTA is clicked. Type: string Example: |
name
required
|
The name for the card. Type: string Example: |
thank_you_text
required
|
The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: |
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: |
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 Example: |
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 Example: |
second_cta_tweet
sometimes required
|
The Tweet text to be used when the second CTA is clicked. Note: Required if Type: string Example: |
cover_image_id
optional
|
A This is a write-only field. In the response, the API will provide a Twitter URL for this image. Type: long Example: |
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: |
image_media_id
optional
|
Specify a poster image for the video using the 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: |
third_cta
optional
|
The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: |
third_cta_tweet
sometimes required
|
The Tweet text to be used when the third CTA is clicked. Type: string Note: Required if Example: |
fourth_cta
optional
|
The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: |
fourth_cta_tweet
sometimes required
|
The Tweet text to be used when the fourth CTA is clicked. Type: string Note: Required if Example: |
thank_you_url
optional
|
The URL to be displayed with the thank you text. Type: string Example: |
Example Request¶
POST https://ads-api.twitter.com/3/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/3/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: |
card_id
required
|
A reference to the video conversation card you are operating with in the request. Type: string Example: |
cover_image_id
optional
|
A This is a write-only field. In the response, the API will provide a Twitter URL for this image. Type: long Example: |
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: |
image_media_id
optional
|
Specify a poster image for the video using the 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: |
first_cta
optional
|
The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: |
first_cta_tweet
optional
|
The Tweet text to be used when the first CTA is clicked. Type: string Example: |
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 Example: |
second_cta_tweet
optional
|
The Tweet text to be used when the second CTA is clicked. Note: Required if Type: string Example: |
third_cta
optional
|
The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: |
third_cta_tweet
optional
|
The Tweet text to be used when the third CTA is clicked. Type: string Note: Required if Example: |
fourth_cta
optional
|
The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: |
fourth_cta_tweet
optional
|
The Tweet text to be used when the fourth CTA is clicked. Type: string Note: Required if Example: |
name
optional
|
The name for the card. Type: string Example: |
thank_you_text
optional
|
The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: |
thank_you_url
optional
|
The URL to be displayed with the thank you text. Type: string Example: |
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 Example: |
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: |
Example Request¶
PUT https://ads-api.twitter.com/3/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/3/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: |
card_id
required
|
A reference to the video conversation card you are operating with in the request. Type: string Example: |
Example Request¶
DELETE https://ads-api.twitter.com/3/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"
}
}
}