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: |
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: |
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 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 will be ignored if Note: Requests which include 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: |
card_id
required
|
A reference to the image DM 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.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: |
first_cta
required
|
The Call-To-Action (CTA) text for the first option. Maximum length: 20 characters. Type: string Example: |
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
Type: long Example: |
name
required
|
The name for the card. Type: string Example: |
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: |
image_media_id
sometimes required
|
A This is a write-only field. In the response, the API will provide a Twitter URL for this image. Note: Required if Note: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: long Example: |
image_media_key
sometimes required
|
The 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 Note: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: |
second_cta
optional
|
The Call-To-Action (CTA) text for the second option. Maximum length: 20 characters. Type: string Example: |
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
Type: long Example: |
third_cta
optional
|
The Call-To-Action (CTA) text for the third option. Maximum length: 20 characters. Type: string Example: |
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
Type: long Example: |
fourth_cta
optional
|
The Call-To-Action (CTA) text for the fourth option. Maximum length: 20 characters. Type: string Example: |
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
Type: long Example: |
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: |
card_id
required
|
A reference to the image DM card you are operating with in the request. Type: string Example: |
first_cta
optional
|
The Call-To-Action (CTA) text for the first option. Maximum length: 20 characters. Type: string Example: |
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
Type: long Example: |
image_media_id
optional
|
A 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: |
image_media_key
optional
|
The 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: |
second_cta
optional
|
The Call-To-Action (CTA) text for the second option. Maximum length: 20 characters. Type: string Example: |
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
Type: long Example: |
third_cta
optional
|
The Call-To-Action (CTA) text for the third option. Maximum length: 20 characters. Type: string Example: |
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
Type: long Example: |
fourth_cta
optional
|
The Call-To-Action (CTA) text for the fourth option. Maximum length: 20 characters. Type: string Example: |
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
Type: long Example: |
name
optional
|
The name for the card. Type: string Example: |
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: |
card_id
required
|
A reference to the image DM card you are operating with in the request. Type: string Example: |
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"
}
}
}