Image Direct Message 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_direct_message

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

Resource URL

https://ads-api.twitter.com/8/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 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_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",
      "media_url": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
      "recipient_user_id": "756201191646691328",
      "id": "59wpi",
      "created_at": "2018-01-27T05:44:31Z",
      "media_key": "3_957000624519835648",
      "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/8/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/8/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",
    "media_url": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
    "recipient_user_id": "756201191646691328",
    "id": "59wpi",
    "created_at": "2018-01-27T05:44:31Z",
    "media_key": "3_957000624519835648",
    "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/8/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

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

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/8/accounts/18ce54d4x5t/cards/image_direct_message?first_cta=DM me&first_cta_welcome_message_id=865707372148174852&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",
    "media_url": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
    "recipient_user_id": "756201191646691328",
    "id": "59wpi",
    "created_at": "2018-01-27T05:44:31Z",
    "media_key": "3_957000624519835648",
    "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",
      "media_url": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
      "recipient_user_id": "756201191646691328",
      "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/8/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

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

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: space card

Example Request

PUT https://ads-api.twitter.com/8/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",
    "media_url": "https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg",
    "recipient_user_id": "756201191646691328",
    "id": "59wpi",
    "created_at": "2018-01-27T05:44:31Z",
    "media_key": "3_957000624519835648",
    "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/8/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/8/accounts/18ce54d4x5t/cards/image_direct_message/4zi61

Example Response

{
  "data": {
    "name": "DM card",
    "id": "4zi61",
    "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"
    }
  }
}

Was this document helpful?

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.