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.twitter.com/8/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: 18ce54d4x5t

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: 59woh

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

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/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.twitter.com/8/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: 18ce54d4x5t

card_id
required

A reference to the image conversation card you are operating with in the request.

Type: string

Example: 59woh

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/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.twitter.com/8/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: 18ce54d4x5t

first_cta
required

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

Type: string

Example: #ShareNow

first_cta_tweet
required

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

Type: string

Example: I Heart @AdsAPI

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: 3_1151345051104991073

name
required

The name for the card.

Type: string

Example: image conversation card

thank_you_text
required

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

Type: string

Example: Thank you

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

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 second_cta is not set.

Example: Start a conversation

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

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.

Note: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required.

Type: string

Example: 3_883112887618682880

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/8/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.twitter.com/8/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: 18ce54d4x5t

card_id
required

A reference to the image conversation card you are operating with in the request.

Type: string

Example: 4i0qg

first_cta
optional

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

Type: string

Example: #ShareNow

first_cta_tweet
optional

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

Type: string

Example: I Heart @AdsAPI

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 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: 3_1151345051104991073

name
optional

The name for the card.

Type: string

Example: moon card

thank_you_text
optional

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

Type: string

Example: Thank you

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 image 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.

Note: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required.

Type: string

Example: 3_883112887618682880

Example Request

PUT https://ads-api.twitter.com/8/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.twitter.com/8/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: 18ce54d4x5t

card_id
required

A reference to the image conversation card you are operating with in the request.

Type: string

Example: 4i0qe

Example Request

DELETE https://ads-api.twitter.com/8/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"
    }
  }
}

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.