Carousels

Introduction

The Twitter Ads API supports creating and retrieving video carousels and image carousels. The carousel is a card type that can contain between 2 and 6 media assets. The carousel card can direct a user to a website or encourage them to install a mobile app. For more information about carousels, their benefits, best practices, and FAQs, see our Carousel ads on Twitter page.

A carousel, like any other card type, can be used in Tweets and those Tweets can then be promoted. The workflow is the same as what you're already used to:

Upload media
Create the card
Create the Tweet
Promote the Tweet

The only difference is with how the card is created. While other card create requests accept query parameters, carousel card create requests only accept JSON POST bodies.

Endpoints

The Ads API supports creating and retrieving carousels.

To create a carousel—any kind—use the POST accounts/:account_id/cards endpoint. To retrieve carousels, use the GET accounts/:account_id/cards endpoint.

JSON POST Body

Carousels are created using two components. The first specifies the media assets that will be used. The second specifies information about either the website or the app.

Specifically, a carousel card is created by using the following components, in order:

One SWIPEABLE_MEDIAcomponent, which accepts an array of media keys
One of the following:
- A DETAILS component to specify website information
- A BUTTON component to specify app information

The SWIPEABLE_MEDIA component must include a media_keys array where you can specify between 2 and 6 images or videos. The order in which the media keys are passed in determine the order in which they will be rendered.

{
  "type": "SWIPEABLE_MEDIA",
  "media_keys": [
    "13_1089771253848666112",
    "13_1191948012077092867"
  ]
}

As a reminder, you can obtain media keys by making a request to the GET accounts/:account_id/media_library endpoint.

The composition of the second component object depends on whether you wish to direct a user to a website or encourage them to install an app. The table below summarizes the two options. (Note: all of the listed keys are required.)

	Website	App
Specify the component type	"type": "DETAILS"	"type": "BUTTON"
The website carousel accepts a title (headline) that appears under the media The app carousel `label` object specifies the button label	"title": "Twitter"	"label": { "type": "ENUM", "value": "INSTALL" }
For website carousels, the destination is the website URL For app carousels, the destination is the app and its corresponding attributes	"destination": { "type": "WEBSITE", "url": "https://www.twitter.com" }	"destination": { "type": "APP", ... }

Putting this together, an example website carousel JSON POST body is shown below.

{
  "name": "website carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "DETAILS",
      "title": "Twitter",
      "destination": {
        "type": "WEBSITE",
        "url": "https://www.twitter.com"
      }
    }
  ]
}

App destination objects within BUTTON components require a country code and at least one app identifier. They optionally accept deep links. For a description of these fields, see the reference documentation.

Putting this together, an example app carousel JSON POST body is shown below.

{
  "name": "app carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "iphone_app_id": "333903271"
      }
    }
  ]
}

Example

This section demonstrates how to create a video website carousel card and how to use it in a Tweet. As mentioned above, the workflow is the same as what you're already used to: upload media, create the card, create the Tweet. The only difference is how the card is created.

Media

To start, either upload new media assets or use existing ones. For details on how to upload new media assets and add them to the Media Library, see our Media Library Guide.

Once your media assets are in the Media Library, fetch them using the GET accounts/:account_id/media_library endpoint. Use the media_type request parameter to scope the results to a particular media type.

$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_type": "VIDEO"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "tweeted": true,
      "duration": 5283,
      "name": "Sunrise",
      "file_name": "sunrise.mp4",
      "description": null,
      "media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9",
      "poster_media_key": "3_1089771253848666112",
      "media_key": "13_1089771253848666112",
      "created_at": "2019-01-28T06:24:48Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg",
      "title": null,
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2019-08-23T19:05:33Z",
      "deleted": false
    },
    {
      "tweeted": true,
      "duration": 15248,
      "name": "snow",
      "file_name": "snow.mp4",
      "description": "Two, three, and to the four",
      "media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13",
      "poster_media_key": "3_1191948012077092867",
      "media_key": "13_1191948012077092867",
      "created_at": "2019-11-06T05:18:46Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg",
      "title": "One",
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2020-03-27T22:23:18Z",
      "deleted": false
    }
  ]
}

Carousel Creation

Use the POST accounts/:account_id/cards endpoint to create your carousel. Use the media keys from the previous request. Remember, the order in which the media keys are passed in determine the order in which they are rendered.

$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "Twitter","destination":{"type":"WEBSITE", "url":"https://www.twitter.com"}}]}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "website carousel",
    "components": [
      {
        "type": "SWIPEABLE_MEDIA",
        "media_keys": [
          "13_1089771253848666112",
          "13_1191948012077092867"
        ]
      },
      {
        "type": "DETAILS",
        "title": "Twitter",
        "destination": {
          "type": "WEBSITE",
          "url": "https://www.twitter.com/",
          "tco_url": "https://t.co/dyTMHWKWZb"
        }
      }
    ],
    "id": "ars7m",
    "created_at": "2020-11-11T07:51:47Z",
    "card_uri": "card://1326432421105995776",
    "updated_at": "2020-11-11T07:51:47Z",
    "deleted": false,
    "card_type": "UNIFIED"
  }
}

Notice that like with other cards, the carousel card response includes a card_uri, which will be used when creating a Tweet.

Use the POST accounts/:account_id/tweet endpoint to create your Tweet. Use the card_uri from the previous request. (Response truncated for readability.)

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792"

{
  "data": {
    "created_at": "Wed Nov 11 07:58:27 +0000 2020",
    "id": 1326434098324385792,
    "id_str": "1326434098324385792",
    "text": "Swipe",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "Ads API Internal Test App",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691300,
      "id_str": "756201191646691328",
      ...
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": [
      2417045708
    ],
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "Swipe",
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}

Tweet Previews

Use the GET accounts/:account_id/tweet_previews endpoint to see your Tweet.

Swipe
— API McTestface (@apimctestface) November 11, 2020