動画会話カード

: カードをツイートに関連付けるには、POST accounts/:account_id/tweetPOST statuses/update、またはPOST accounts/:account_id/scheduled_tweetsエンドポイントでcard_uriパラメーターを使います。

GET accounts/:account_id/cards/video_conversation

現在のアカウントに関連付けられている一部またはすべての動画会話カードの詳細を取得します。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/cards/video_conversation

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

card_ids
任意

カンマ区切りのIDリストを指定して、応答の範囲を目的の動画会話カードのみに設定します。最大200件のIDを指定できます。

タイプ: 文字列

例: 5a86h

count
任意

個別のリクエストごとに試行および取得するレコード数を指定します。

タイプ: 整数

デフォルト: 200
最小、最大: 11000
cursor
任意

結果の次のページを取得するためのカーソルを指定します。詳細については、「ページネーション」を参照してください。

タイプ: 文字列

例: 8x7v00oow

q
任意

nameでカード範囲を指定する省略可能なクエリです。このパラメーターを省略すると、すべてが取得されます。最大長: 80文字。

: プレフィックスの一致は大文字と小文字を区別します。

タイプ: 文字列

例: night sky

sort_by
任意

サポートされている属性で昇順または降順に並べ替えます。詳細については、「並べ替え」を参照してください。

タイプ: 文字列

例: created_at-asc

with_deleted
任意

削除した結果をリクエストに含めます。

タイプ: ブール値

デフォルト: false
使用可能な値: truefalse
with_total_count
任意

total_count応答属性を含めます。

: このパラメーターとcursorとは相互に排他的です。

: total_countを含むリクエストの場合、レート制限が低くなります。現在15分あたり200に設定されています。

タイプ: ブール値

デフォルト: false
使用可能な値: truefalse

リクエストの例

GET https://ads-api.x.com/10/accounts/18ce54d4x5t/cards/video_conversation?card_ids=5a86h

応答の例

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_ids": [
        "5a86h"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "id": "5a86h",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "created_at": "2018-01-30T17:53:04Z",
      "card_uri": "card://958397665015775232",
      "title": "Developers",
      "updated_at": "2018-01-30T17:53:04Z",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "deleted": false,
      "card_type": "VIDEO_CONVERSATION"
    }
  ]
}

GET accounts/:account_id/cards/video_conversation/:card_id

現在のアカウントに関連付けられている特定の動画会話カードを取得します。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/cards/video_conversation/:card_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

card_id
必須

リクエスト内で操作する動画会話カードへの参照。

タイプ: 文字列

例: 4i0ya

with_deleted
任意

削除した結果をリクエストに含めます。

タイプ: ブール値

デフォルト: false
使用可能な値: truefalse

リクエストの例

GET https://ads-api.x.com/10/accounts/18ce54d4x5t/cards/video_conversation/5a86h

応答の例

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  }
}

POST accounts/:account_id/cards/video_conversation

指定されたアカウントに関連付けられている新しい動画会話カードを作成します。

Twitterエンドポイントへの画像アップロードに関する役立つ情報については、「メディアのアップロード」を参照してください。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/cards/video_conversation

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

first_cta
必須

最初のオプションのアクション誘導(CTA)ハッシュタグ。最大長: 20文字(#は文字数に含まれません)。

タイプ: 文字列

例: #APIs

first_cta_tweet
必須

最初のCTAがクリックされたときに使われるツイートテキスト。

タイプ: 文字列

例: Ads API

media_key
必須

このカードでは動画のメディアキーが使用されます。

: このビデオはアカウントのメディアライブラリ内にある必要があります。

: アスペクト比は16:9である必要があります。

タイプ: 文字列

例: 13_1168079965037467209

name
必須

カードの名前。

タイプ: 文字列

例: video conversation card

thank_you_text
必須

CTAがクリックされたときに表示されるテキスト。最大長: 23文字。

タイプ: 文字列

例: Build it

title
必須の場合あり

動画の下、CTAの上に表示される、カードのタイトル。最大長: 23文字。

タイプ: 文字列

: second_ctaが設定されてnot場合は必須です。

例: Developers

second_cta
必須の場合あり

2番目のオプションのアクション誘導(CTA)ハッシュタグ。最大長: 20文字(#は文字数に含まれません)。

タイプ: 文字列

: titleが設定されてnot場合は必須です。

例: #ShareAgain

second_cta_tweet
必須の場合あり

2番目のCTAがクリックされたときに使われるツイートテキスト。

: second_ctaが設定されている場合は必須です。

タイプ: 文字列

例: I Heart @AdsAPI Again

poster_media_key
任意

このカードではポスター画像のメディアキーが使用されます。指定しない場合は、最初のフレームが使われます。

: このビデオはアカウントのメディアライブラリ内にある必要があります。

タイプ: 長整数型

例: 3_882726458191298561

third_cta
任意

3番目のオプションのアクション誘導(CTA)ハッシュタグ。最大長: 20文字(#は文字数に含まれません)。

タイプ: 文字列

例: #ShareMore

third_cta_tweet
必須の場合あり

3番目のCTAがクリックされたときに使われるツイートテキスト。

タイプ: 文字列

: third_ctaが設定されている場合は必須です。

例: I Heart @TwitterDev

fourth_cta
任意

4番目のオプションのアクション誘導(CTA)ハッシュタグ。最大長: 20文字(#は文字数に含まれません)。

タイプ: 文字列

例: #ShareExtra

fourth_cta_tweet
必須の場合あり

4番目のCTAがクリックされたときに使われるツイートテキスト。

タイプ: 文字列

: fourth_ctaが設定されている場合は必須です。

例: I Heart @TwitterDev Again

thank_you_url
任意

サンキューテキストと一緒に表示されるURL。

タイプ: 文字列

例: https://example.com/thankyou

unlocked_image_media_key
任意

インスタントアンロックのシナリオで使われる画像のmedia_key

このフィールドは書き込み専用です。応答でAPIからこの画像のTwitter URLが提供されます。

: この画像はアカウントのメディアライブラリ内にある必要があります。

タイプ: 文字列

例: 3_883112887618682880

unlocked_video_media_key
任意

インスタントアンロックのシナリオで使われるGET accounts/:account_id/media_libraryエンドポイントの動画のID。

タイプ: 文字列

例: 13_867520357225418752

リクエストの例

POST https://ads-api.x.com/10/accounts/18ce54d4x5t/cards/video_conversation?first_cta=#APIs&first_cta_tweet=Ads API&name=video conversation card&thank_you_text=Build it&title=Developers&media_key=13_958388276489895936

応答の例

{
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "video_poster_height": "9",
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "title": "Developers",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_CONVERSATION"
    }
  }
}

PUT accounts/:account_id/cards/video_conversation/:card_id

現在のアカウントに属する、指定した動画会話カードを更新します。

Twitterエンドポイントへの画像アップロードに関する役立つ情報については、「メディアのアップロード」を参照してください。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/cards/video_conversation/:card_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

card_id
必須

リクエスト内で操作する動画会話カードへの参照。

タイプ: 文字列

例: 5a86h

first_cta
任意

最初のオプションのアクション誘導(CTA)ハッシュタグ。最大長: 20文字(#は文字数に含まれません)。

タイプ: 文字列

例: #APIs

first_cta_tweet
任意

最初のCTAがクリックされたときに使われるツイートテキスト。

タイプ: 文字列

例: Ads API

second_cta
任意

2番目のオプションのアクション誘導(CTA)ハッシュタグ。最大長: 20文字(#は文字数に含まれません)。

タイプ: 文字列

: titleが設定されてnot場合は必須です。

例: #ShareAgain

second_cta_tweet
任意

2番目のCTAがクリックされたときに使われるツイートテキスト。

: second_ctaが設定されている場合は必須です。

タイプ: 文字列

例: I Heart @AdsAPI Again

third_cta
任意

3番目のオプションのアクション誘導(CTA)ハッシュタグ。最大長: 20文字(#は文字数に含まれません)。

タイプ: 文字列

例: #ShareMore

third_cta_tweet
任意

3番目のCTAがクリックされたときに使われるツイートテキスト。

タイプ: 文字列

: third_ctaが設定されている場合は必須です。

例: I Heart @TwitterDev

fourth_cta
任意

4番目のオプションのアクション誘導(CTA)ハッシュタグ。最大長: 20文字(#は文字数に含まれません)。

タイプ: 文字列

例: #ShareExtra

fourth_cta_tweet
任意

4番目のCTAがクリックされたときに使われるツイートテキスト。

タイプ: 文字列

: fourth_ctaが設定されている場合は必須です。

例: I Heart @TwitterDev Again

media_key
任意

このカードでは動画のメディアキーが使用されます。

: このビデオはアカウントのメディアライブラリ内にある必要があります。

: アスペクト比は16:9である必要があります。

タイプ: 文字列

例: 13_1168079965037467209

name
任意

カードの名前。

タイプ: 文字列

例: developers card

poster_media_key
任意

このカードではポスター画像のメディアキーが使用されます。指定しない場合は、最初のフレームが使われます。

: このビデオはアカウントのメディアライブラリ内にある必要があります。

タイプ: 長整数型

例: 3_882726458191298561

thank_you_text
任意

CTAがクリックされたときに表示されるテキスト。最大長: 23文字。

タイプ: 文字列

例: Build it

thank_you_url
任意

サンキューテキストと一緒に表示されるURL。

タイプ: 文字列

例: https://example.com/thankyou

title
任意

動画の下、CTAの上に表示される、カードのタイトル。最大長: 23文字。

タイプ: 文字列

: second_ctaが設定されてnot場合は必須です。

例: Start a conversation

unlocked_image_media_key
任意

インスタントアンロックのシナリオで使われる画像のmedia_key

このフィールドは書き込み専用です。応答でAPIからこの画像のTwitter URLが提供されます。

: この画像はアカウントのメディアライブラリ内にある必要があります。

タイプ: 文字列

例: 3_883112887618682880

unlocked_video_media_key
任意

インスタントアンロックのシナリオで使われるGET accounts/:account_id/media_libraryエンドポイントの動画のID。

タイプ: 文字列

例: 13_867520357225418752

リクエストの例

PUT https://ads-api.x.com/10/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card

応答の例

{
  "data": {
    "name": "developers card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T18:02:15Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_CONVERSATION",
      "card_id": "5a86h",
      "name": "developers card"
    }
  }
}

DELETE accounts/:account_id/cards/video_conversation/:card_id

現在のアカウントに属する、指定した動画会話カードを完全に削除します。

: これは物理的な削除です。このため、削除したカードを取得することはできません。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/cards/video_conversation/:card_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

card_id
必須

リクエスト内で操作する動画会話カードへの参照。

タイプ: 文字列

例: 4i0ya

リクエストの例

DELETE https://ads-api.x.com/10/accounts/18ce54d4x5t/cards/video_conversation/4i0ya

応答の例

{
  "data": {
    "name": "video conversation card",
    "id": "4i0ya",
    "created_at": "2017-07-07T01:36:39Z",
    "updated_at": "2017-08-23T13:29:13Z",
    "deleted": true,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0ya",
      "card_type": "video_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}