Image 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/image_conversation¶
Retrieve details for some or all image conversation cards associated with the current account.
Resource URL¶
https://ads-api.x.com/12/accounts/:account_id/cards/image_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 image 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 Note: This performs case-insensitive prefix matching. 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 and
Note: Requests
which include Type: boolean Default:
false Possible values: true ,
false |
Example Request¶
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh
Example Response¶
{
"request": {
"params": {
"card_type": "image_conversation",
"card_ids": [
"59woh"
],
"account_id": "18ce54d4x5t"
}
},
"next_cursor": null,
"data": [
{
"name": "image conversation card",
"first_cta": "#moon",
"image_display_height": "670",
"media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
"thank_you_text": "thanks",
"id": "59woh",
"first_cta_tweet": "stars",
"media_key": "3_957113581522141184",
"created_at": "2018-01-27T04:58:42Z",
"image_display_width": "1280",
"card_uri": "card://923498485702009837",
"title": "Full moon",
"updated_at": "2018-01-27T04:58:42Z",
"deleted": false,
"card_type": "IMAGE_CONVERSATION"
}
]
}
GET accounts/:account_id/cards/image_conversation/:card_id¶
Retrieve a specific image conversation card associated with the current account.
Resource URL¶
https://ads-api.x.com/12/accounts/:account_id/cards/image_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 image 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.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh
Example Response¶
{
"request": {
"params": {
"card_type": "image_conversation",
"card_id": "59woh",
"account_id": "18ce54d4x5t"
}
},
"data": {
"name": "image conversation card",
"first_cta": "#moon",
"image_display_height": "670",
"media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
"thank_you_text": "thanks",
"id": "59woh",
"first_cta_tweet": "stars",
"media_key": "3_957113581522141184",
"created_at": "2018-01-27T04:58:42Z",
"image_display_width": "1280",
"card_uri": "card://923498485702009837",
"title": "Full moon",
"updated_at": "2018-01-27T04:58:42Z",
"deleted": false,
"card_type": "IMAGE_CONVERSATION"
}
}
POST accounts/:account_id/cards/image_conversation¶
Create a new image conversation card associated with the specified account.
See Uploading Media for useful information on uploading images to our endpoints.
Resource URL¶
https://ads-api.x.com/12/accounts/:account_id/cards/image_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:
|
media_key required |
The media key for an image to be used in this card. Note: The image must be in the account's Media Library. Note: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. 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:
|
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:
|
title sometimes required |
The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string Note: Required if 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:
|
unlocked_image_media_key optional |
A 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. Note: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: |
thank_you_url optional |
The URL to be displayed with the thank you text. Type: string Example: |
Example Request¶
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon
Example Response¶
{
"data": {
"name": "image conversation card",
"first_cta": "#moon",
"image_display_height": "670",
"media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
"thank_you_text": "thanks",
"id": "59woh",
"first_cta_tweet": "stars",
"media_key": "3_957113581522141184",
"created_at": "2018-01-27T04:58:42Z",
"image_display_width": "1280",
"card_uri": "card://923498485702009837",
"title": "Full moon",
"updated_at": "2018-01-27T04:58:42Z",
"deleted": false,
"card_type": "IMAGE_CONVERSATION"
},
"request": {
"params": {
"name": "image conversation card",
"first_cta": "#moon",
"image_display_height": "670",
"media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
"thank_you_text": "thanks",
"media_key": "3_957113581522141184",
"account_id": "18ce54d4x5t",
"first_cta_tweet": "stars",
"image_display_width": "1280",
"title": "Full moon",
"card_type": "IMAGE_CONVERSATION"
}
}
}
PUT accounts/:account_id/cards/image_conversation/:card_id¶
Update the specified image conversation card belonging to the current account.
See Uploading Media for useful information on uploading images to our endpoints.
Resource URL¶
https://ads-api.x.com/12/accounts/:account_id/cards/image_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 image conversation card you are operating with in the request. Type: string 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:
|
media_key optional |
The media key for an image to be used in this card. Note: The image must be in the account's Media Library. Note: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string 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 image and above the CTAs. Maximum length: 23 characters. Type: string Note: Required if Example:
|
unlocked_image_media_key optional |
A 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. Note: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: |
Example Request¶
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card
Example Response¶
{
"data": {
"name": "moon card",
"id": "59woh",
"created_at": "2018-01-27T04:58:42Z",
"card_uri": "card://923498485702009837",
"updated_at": "2018-01-29T21:04:39Z",
"deleted": false,
"card_type": "IMAGE_CONVERSATION"
},
"request": {
"params": {
"account_id": "18ce54d4x5t",
"card_type": "IMAGE_CONVERSATION",
"card_id": "59woh",
"name": "moon card"
}
}
}
DELETE accounts/:account_id/cards/image_conversation/:card_id¶
Permanently delete the specified image 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.x.com/12/accounts/:account_id/cards/image_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 image conversation card you are operating with in the request. Type: string Example:
|
Example Request¶
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe
Example Response¶
{
"data": {
"name": "image conversation card",
"id": "4i0qe",
"created_at": "2017-07-07T00:03:01Z",
"updated_at": "2017-08-23T13:26:23Z",
"deleted": true,
"card_type": "IMAGE_CONVERSATION"
},
"request": {
"params": {
"card_id": "4i0qe",
"card_type": "image_conversation",
"account_id": "18ce54d4x5t"
}
}
}