Creatives

Image Direct Message 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/image_direct_message

Retrieve details for some or all image direct message cards associated with the current account.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/cards/image_direct_message

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 DM cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 59wpi
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: space
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/image_direct_message?card_ids=59wpi

Example Response

{
  "request": {
    "params": {
      "card_type": "image_direct_message",
      "card_ids": [
        "59wpi"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "space card",
      "first_cta": "DM me",
      "first_cta_welcome_message_id": "865707372148174852",
      "image_display_height": "418",
      "image": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
      "recipient_user_id": "756201191646691328",
      "preview_url": null,
      "id": "59wpi",
      "account_id": "18ce54d4x5t",
      "created_at": "2018-01-27T05:44:31Z",
      "image_display_width": "800",
      "card_uri": "card://957127157993500678",
      "updated_at": "2018-01-30T01:33:49Z",
      "deleted": false,
      "card_type": "IMAGE_DIRECT_MESSAGE"
    }
  ]
}

GET accounts/:account_id/cards/image_direct_message/:card_id

Retrieve a specific image direct message card belonging to the current account.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/cards/image_direct_message/: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 DM card you are operating with in the request.

Type: string

Example: 59wpi
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/image_direct_message/59wpi

Example Response

{
  "request": {
    "params": {
      "card_type": "image_direct_message",
      "card_id": "59wpi",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "space card",
    "first_cta": "DM me",
    "first_cta_welcome_message_id": "865707372148174852",
    "image_display_height": "418",
    "image": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
    "recipient_user_id": "756201191646691328",
    "preview_url": null,
    "id": "59wpi",
    "account_id": "18ce54d4x5t",
    "created_at": "2018-01-27T05:44:31Z",
    "image_display_width": "800",
    "card_uri": "card://957127157993500678",
    "updated_at": "2018-01-30T01:33:49Z",
    "deleted": false,
    "card_type": "IMAGE_DIRECT_MESSAGE"
  }
}

POST accounts/:account_id/cards/image_direct_message

Create a new image direct message card associated with the current account.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/cards/image_direct_message

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) text for the first option. Maximum length: 20 characters.

Type: string

Example: DM me
first_cta_welcome_message_id
required

The welcome message ID to associate with the first CTA.

Note: This welcome message must be owned by the user specified in recipient_user_id.

Type: long

Example: 865707372148174852
name
required

The name for the card.

Type: string

Example: direct message card
recipient_user_id
required

The user to start a conversation with, from the perspective of the user interacting with the card.

Note: This must be the owner of the specified welcome messages.

Type: long

Example: 756201191646691328
image_media_id
sometimes required

A media_id of an image which will be used in this card.

This is a write-only field. In the response, the API will provide a Twitter URL for this image.

Note: Required if image_media_key is not specified.

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

Type: long

Example: 927056155779592193
image_media_key
sometimes required

The media_key of a media library image which will be used in this card.

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: Required if image_media_id is not specified.

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

Type: string

Example: 3_957000624519835648
second_cta
optional

The Call-To-Action (CTA) text for the second option. Maximum length: 20 characters.

Type: string

Example: Browse Moments
second_cta_welcome_message_id
optional

The welcome message ID to associate with the second CTA.

Note: This welcome message must be owned by the user specified in recipient_user_id.

Type: long

Example: 926684855910800782
third_cta
optional

The Call-To-Action (CTA) text for the third option. Maximum length: 20 characters.

Type: string

Example: Play a bot song
third_cta_welcome_message_id
optional

The welcome message ID to associate with the third CTA.

Note: This welcome message must be owned by the user specified in recipient_user_id.

Type: long

Example: 948027689453946009
fourth_cta
optional

The Call-To-Action (CTA) text for the fourth option. Maximum length: 20 characters.

Type: string

Example: Play Twitter Trivia
fourth_cta_welcome_message_id
optional

The welcome message ID to associate with the fourth CTA.

Note: This welcome message must be owned by the user specified in recipient_user_id.

Type: long

Example: 913349640786179035

Example Request

POST https://ads-api.twitter.com/4/accounts/18ce54d4x5t/cards/image_direct_message?first_cta=DM me&first_cta_welcome_message_id=865707372148174852&image_media_key=3_957000624519835648&name=direct message card&recipient_user_id=756201191646691328

Example Response

{
  "data": {
    "name": "direct message card",
    "first_cta": "DM me",
    "first_cta_welcome_message_id": "865707372148174852",
    "image_display_height": "418",
    "image": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
    "recipient_user_id": "756201191646691328",
    "preview_url": null,
    "id": "59wpi",
    "account_id": "18ce54d4x5t",
    "created_at": "2018-01-27T05:44:31Z",
    "image_display_width": "800",
    "card_uri": "card://957127157993500678",
    "updated_at": "2018-01-27T05:44:31Z",
    "deleted": false,
    "card_type": "IMAGE_DIRECT_MESSAGE"
  },
  "request": {
    "params": {
      "name": "direct message card",
      "first_cta": "DM me",
      "first_cta_welcome_message_id": "865707372148174852",
      "image_display_height": "418",
      "image": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
      "recipient_user_id": "756201191646691328",
      "image_media_key": "3_957000624519835648",
      "account_id": "18ce54d4x5t",
      "image_display_width": "800",
      "card_type": "IMAGE_DIRECT_MESSAGE"
    }
  }
}

PUT accounts/:account_id/cards/image_direct_message

Update the specified image direct message card belonging to the current account.

Note: It is not possible to update the recipient_user_id as all welcome messages must belong to user specified in the create (POST) request.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/cards/image_direct_message/: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 DM card you are operating with in the request.

Type: string

Example: 4zi61
first_cta
optional

The Call-To-Action (CTA) text for the first option. Maximum length: 20 characters.

Type: string

Example: Tell me a joke
first_cta_welcome_message_id
optional

The welcome message ID to associate with the first CTA.

Note: This welcome message must be owned by the user specified in recipient_user_id.

Type: long

Example: 910471490455820676
image_media_id
optional

A media_id of an image which will be used in this card.

This is a write-only field. In the response, the API will provide a Twitter URL for this image.

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

Type: long

Example: 918361305759098838
image_media_key
optional

The media_key of a media library image which will be used in this card.

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 1.91:1 is required.

Type: string

Example: 3_957000624519835648
second_cta
optional

The Call-To-Action (CTA) text for the second option. Maximum length: 20 characters.

Type: string

Example: Browse Moments
second_cta_welcome_message_id
optional

The welcome message ID to associate with the second CTA.

Note: This welcome message must be owned by the user specified in recipient_user_id.

Type: long

Example: 933687438848534839
third_cta
optional

The Call-To-Action (CTA) text for the third option. Maximum length: 20 characters.

Type: string

Example: Play a bot song
third_cta_welcome_message_id
optional

The welcome message ID to associate with the third CTA.

Note: This welcome message must be owned by the user specified in recipient_user_id.

Type: long

Example: 936485028098425302
fourth_cta
optional

The Call-To-Action (CTA) text for the fourth option. Maximum length: 20 characters.

Type: string

Example: Play Twitter Trivia
fourth_cta_welcome_message_id
optional

The welcome message ID to associate with the fourth CTA.

Note: This welcome message must be owned by the user specified in recipient_user_id.

Type: long

Example: 919658669896157121
name
optional

The name for the card.

Type: string

Example: space card

Example Request

PUT https://ads-api.twitter.com/4/accounts/18ce54d4x5t/cards/image_direct_message/59wpi?name=space card

Example Response

{
  "data": {
    "name": "space card",
    "first_cta": "DM me",
    "first_cta_welcome_message_id": "865707372148174852",
    "image_display_height": "418",
    "image": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
    "recipient_user_id": "756201191646691328",
    "preview_url": null,
    "id": "59wpi",
    "account_id": "18ce54d4x5t",
    "created_at": "2018-01-27T05:44:31Z",
    "image_display_width": "800",
    "card_uri": "card://957127157993500678",
    "updated_at": "2018-01-30T01:33:49Z",
    "deleted": false,
    "card_type": "IMAGE_DIRECT_MESSAGE"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "IMAGE_DIRECT_MESSAGE",
      "card_id": "59wpi",
      "name": "space card"
    }
  }
}

DELETE accounts/:account_id/cards/image_direct_message/:card_id

Permanently delete the specified image direct message 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/image_direct_message/: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 DM card you are operating with in the request.

Type: string

Example: 4zi61

Example Request

DELETE https://ads-api.twitter.com/4/accounts/18ce54d4x5t/cards/image_direct_message/4zi61

Example Response

{
  "data": {
    "name": "DM card",
    "id": "4zi61",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-11-05T06:17:13Z",
    "updated_at": "2017-11-05T06:37:21Z",
    "deleted": true,
    "card_type": "IMAGE_DIRECT_MESSAGE"
  },
  "request": {
    "params": {
      "card_id": "4zi61",
      "card_type": "image_direct_message",
      "account_id": "18ce54d4x5t"
    }
  }
}