Image Conversation Cards
image-conversation

Image Conversation Cards

Run in Postman ❯ 

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

Note: This performs case-insensitive prefix matching.

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.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: 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.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: 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.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: 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.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: 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.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"
    }
  }
}