Criações

​

Visão geral

Criativos são quaisquer entidades que podem ser promovidas em uma campanha. Posts podem incluir texto, imagens, GIFs, vídeos ou cards. Cards podem incluir imagens ou vídeos.

Criativos de imagem, GIF ou vídeo são enviados usando o POST media/upload — um endpoint de upload simples que oferece suporte apenas a imagens — ou os endpoints POST media/upload (chunked). Eles podem ser adicionados a

cards:

• POST accounts/:account_id/cards Tweets:
• POST accounts/:account_id/tweets - Para adicionar cards a Tweets, use o parâmetro card_uri. Tweets agendados:
• POST accounts/:account_id/scheduled_tweets

Para mais detalhes sobre cards, consulte a página Cards. A página Promoted Video fornece detalhes sobre como associar vídeos a cards ou Tweets.

​

Cards

A X Ads API oferece suporte a vários tipos de card que podem ser usados em Tweets, que depois podem ser promovidos em campanhas. Observação: depois de publicado como Tweet, os detalhes do card ficam visíveis publicamente. Isso pode incluir informações sobre o usuário proprietário do card.

​

Imagem

As seguintes especificações de imagem se aplicam aos assets usados em Cards. As imagens devem ter até 3 MB e largura de pelo menos 800 px. Além disso, oferecemos suporte às seguintes proporções de largura:altura.

• Website: 1:1 e 1,91:1
• Image App Download: 1:1 e 1,91:1
• Poll: 1,91:1
• Image Conversation: 1,91:1
• Image Direct Message: 1,91:1

Oferecemos suporte aos seguintes formatos de imagem: .bmp, .jpeg e .png.

​

Vídeo

As especificações de vídeo a seguir se aplicam aos assets usados em Cards. Suportamos as seguintes proporções de largura:altura.

• Vídeo de Website: 16:9 e 1:1
• Vídeo de Download de App: 16:9 e 1:1
• Enquete: 16:9
• Conversa em vídeo: 16:9
• Mensagem direta com vídeo: 16:9

​

Vídeo Promovido

Este documento apresenta uma breve visão geral do processo de upload e promoção de vídeo por meio da X Ads API.

A X Ads API oferece suporte a Vídeo Promovido em Tweets e nos seguintes cards:

• Video Website
• Video App Download
• Video Conversation

Primeiro, faça o upload do vídeo usando o endpoint POST media/upload (chunked). Usando o media_id, associe o vídeo a uma conta de anúncios usando o endpoint POST accounts/:account_id/videos. O id do vídeo, às vezes chamado de media_key, será usado em solicitações subsequentes. É uma string que começa com um inteiro, seguida por um sublinhado e terminada por um valor longo. Como exemplo: 13_875943225764098048.

​

Vídeo promovido em Tweets

Para criar um Tweet, use o endpoint POST accounts/:account_id/tweet junto com o id do vídeo. Nesta etapa, você também pode fornecer um título do vídeo, uma descrição e um call to action (CTA). Esses valores são exibidos para os usuários.

​

Vídeo promovido em cards

Os cards Video App Download e Video Conversation permitem adicionar uma imagem de poster. Envie uma imagem para usar nesses cards pelo endpoint POST media/upload.

Crie o card usando um dos seguintes endpoints:

• POST accounts/:account_id/cards/video_website
• POST accounts/:account_id/cards/video_app_download
• POST accounts/:account_id/cards/video_conversation

usando o id do vídeo e, opcionalmente, o media_id da imagem (para a imagem de poster).

Por fim, crie o Tweet usando o endpoint POST accounts/:account_id/tweet. Os cards são anexados a Tweets usando o parâmetro card_uri.

​

Informações gerais

Para obter orientações detalhadas sobre upload de vídeo pela API, consulte o Guia de Upload de Vídeo.

Os vídeos também podem ser promovidos como pre-roll. Consulte o Guia do Objetivo de Visualizações de Vídeo Pre-roll para uma explicação detalhada.

• (A partir de 2015-10-22) Ao enviar vídeos para uso em conteúdo promovido, o parâmetro media_category deve ser definido com o valor amplify_video em todas as solicitações do comando INIT ao endpoint POST media/upload (chunked). O uso desse parâmetro garante que o vídeo seja pré-processado de forma assíncrona e preparado para uso em conteúdo promovido. O comando STATUS pode ser usado para verificar a conclusão do processamento assíncrono após o upload do vídeo.
• A duração máxima atualmente permitida para vídeos promovidos é de 10 minutos, com tamanho de arquivo de 500 MB ou menos.
• O vídeo enviado deve estar nos formatos mp4 ou mov.
• O vídeo enviado geralmente é processado rapidamente, mas os tempos de processamento podem variar conforme a duração do vídeo e o tamanho do arquivo.
• As imagens de pôster enviadas devem estar nos formatos png ou jpg. Não há requisitos de proporção ou tamanho, mas a imagem do pôster será ajustada para se adequar ao player de vídeo.

​

Guias

​

Tweets programados

​

Introdução

Tweets agendados permitem que um anunciante ou usuário crie um Tweet para ser publicado em uma data posterior. Além de criar e gerenciar esses Tweets, a API permite associá-los a um line item, para que sejam promovidos quando o Tweet for publicado. Isso possibilita que anunciantes preparem Tweets nativos e planejem os criativos de suas campanhas com antecedência em relação a iniciativas-chave. Por exemplo, preparar um criativo de Tweet para ir ao ar imediatamente após o anúncio de um novo produto.

O conjunto completo de funcionalidades fornecido pelos endpoints da API de Tweets agendados está listado abaixo:

• Criar, modificar e visualizar novos Tweets agendados
• Associar um Tweet agendado a um line item
• Consultar e gerenciar Tweets agendados existentes
• Quando um Tweet agendado for publicado, recuperar o id do Tweet já no ar

​

Endpoints da API

A lista completa de endpoints relacionados à funcionalidade acima é apresentada abaixo:

​

Gerenciamento de Tweets agendados

• GET accounts/:account_id/scheduled_tweets (recupera a lista de todos os Tweets agendados)
• GET accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (consulta um Tweet agendado específico usando seu id)
• POST accounts/:account_id/scheduled_tweets (cria um novo Tweet agendado)
• PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (modifica um Tweet agendado existente)
• DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (exclui um Tweet agendado usando seu id)
• GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id (visualiza a prévia de um Tweet agendado existente)

​

Tweets promovidos agendados

• GET accounts/:account_id/scheduled_promoted_tweets (recupera a lista de todos os Tweets promovidos agendados)
• GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id (consulta um Tweet promovido agendado usando seu id)
• POST accounts/:account_id/scheduled_promoted_tweets (cria um novo Tweet promovido agendado)
• DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id (exclui um Tweet promovido agendado existente usando seu id)

​

Visualização de Tweet Programado

• GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id (visualizar um Tweet Programado existente)

Por serem entidades separadas dos Tweets “em tempo real”, os Tweets Programados passam por dois conjuntos distintos de validações em qualquer criação ou edição. O primeiro conjunto de regras de validação é executado durante a etapa de criação do Tweet Programado, especificamente:

​

Criação de Tweet agendado:

• Verifique se o usuário autenticado tem acesso para criar Tweets orgânicos para um determinado @handle. Os privilégios de criação de Tweet Promoted-Only exigem que o usuário autenticado seja um usuário da conta com permissões do Tweet composer
• Verifique se não há mais de 30 Tweets agendados para serem criados dentro de uma janela de 15 minutos em relação ao horário de scheduled_at. Uma mensagem de erro SCHEDULED_TWEET_LIMIT_EXCEEDED indica que muitos Tweets agendados foram programados dentro do mesmo intervalo futuro de 15 minutos. Os anunciantes precisarão remover um Tweet agendado existente ou alterar o horário de scheduled_at para mais cedo ou mais tarde.

​

Tweet programado entra no ar:

• Essas regras de validação são executadas no horário de scheduled_at e são idênticas às aplicadas na criação comum de Tweet na API. Por exemplo, um Tweet programado não entrará no ar e o scheduled_status será definido como FAILED se o Tweet programado contiver simultaneamente uma imagem e um gif

​

Fluxo de trabalho

Criar um novo Tweet agendado

Um novo Tweet agendado pode ser criado usando o endpoint POST accounts/:account_id/scheduled_tweets. Esse endpoint tem os seguintes parâmetros obrigatórios: o horário scheduled_at e o text do Tweet, caso nenhuma entidade de mídia seja incluída no Tweet. Além disso, esse endpoint oferece algumas opções adicionais que permitem criar um Tweet agendado em nome de outro @handle por meio do parâmetro as_user_id, bem como adicionar um card (card_uri) e mídias (media_ids). Observação: um Tweet pode conter apenas entidades de um mesmo tipo, ou seja, Vídeo, GIF ou Imagem. O parâmetro nullcast controla se o Tweet é “Promoted-Only” ou não. Todos os Tweets agendados recém-criados são “Promoted-Only” (nullcast=true) por padrão. Se nullcast=false, é criado um Tweet orgânico agendado.

Quando um Tweet agendado é criado com sucesso, a resposta conterá um campo id, que se refere ao identificador exclusivo do próprio Tweet agendado. Além desse campo, outro campo chamado tweet_id também é retornado. Esse campo é null inicialmente; no entanto, quando o Tweet é publicado, esse campo é preenchido com o ID do Tweet “publicado”.

twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Boas Festas!'

Isso criará o seguinte Tweet programado:

{
  "request": {
    "params": {
      "text": "Boas Festas!",
      "scheduled_at": "2017-12-24T23:59:00Z"
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "917507899668099072",
    "text": "Boas Festas!",
    "user_id": "3271358660",
    "scheduled_status": "SCHEDULED",
    "id": 917507899668099100,
    "nullcast": true,
    "created_at": "2017-10-09T21:51:44Z",
    "scheduled_at": "2017-12-24T23:59:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T21:51:44Z",
    "tweet_id": null,
    "media_keys": []
  }
}

Assim que esse Tweet agendado for publicado, o campo tweet_id será preenchido com o ID do Tweet “publicado”.

Visualizar um Tweet agendado

O endpoint GET accounts/:account_id/tweet_previews pode então ser usado com o id do Tweet agendado da etapa anterior para gerar uma prévia do Tweet. A resposta da API conterá uma URL de iframe pronta para ser usada para renderizar uma prévia do Tweet agendado. O CSS e as imagens relevantes serão fornecidos diretamente pela X.

twurl -H ads-api.x.com -X GET "/6/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072

{
  "request": {
    "params": {
      "tweet_type": "SCHEDULED",
      "tweet_ids": [
        "917507899668099072"
      ],
      "account_id": "18ce54bgxky"
    }
  },
  "data": [
    {
      "tweet_id": "1126633863155871744",
      "preview": "<\iframe class='tweet-preview' src='https://ton.smf1.x.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAK1WTW%2FjNhD9Kyyv9dqSZdmOgALJbhJsCyxaIDkUWBUEJY0lNhSpklRSN%2FV%2F71CyZbm297S%2BWJxPzpt5I71T9wbgaELeaW6AOygYxyN9rlryhW9JcEPmUbKIkuiG%2FBjgj8yD8IZOqChoEobz5TKK1ssojOP1KlwtFl7BrDMY4oIW%2FTatlMzB3z7JZ940W%2FJZS1Hwrf0Btc60Kve3oMmGSwsTWgjbSL7tXJjhqgSafA0mYfzHhIJywgmwNHmnFbeV4yU%2Bf0WN3daZlvtDa8Gw2htrdRCZXrlDU92aHIPStA2CKOekMrD5KaWVc02SztIZps%2Bh0rIAg27TXNcpJQYk2ii90VLqt7R3ht%2B4cQoMeVClUIAPd03Th01nvDfx0ClmoJFYk0aouGst82gqROaKskf03KCr7LLvXnXN02K3QTHFaziovYdH0seL5qswitfLZTBq6FGIRfSe9Lm1FTfkY%2BX%2FFcpPAlNRC7eufdFSY1%2BxASh84oo8YitzYXM9IZ%2FuaNcQ1HjMbQc61l0VXDmYlsJVbTYVGq0KwPCi2cf5tQFFnjR2zyDU6YycwX%2Fr3oRzvfKpwTaSZ8NfQUoU%2FUsetanxAV79VElhHbm1oIrSiILcvvgquqSN0Q7y8Uz2TQdjWa5bhZP8IUShEeh8IvIxkVB7SY%2FyKctaIL%2B0kgQrMp8n0SKJ10eWxZ4t%2FBXHUzg4idu6nOnNxsIQ1Yka2D9aDc0sQTNQPJP%2B2sgqvPUrGLERozL68ToNLRELvBj4VuZaOSOy1mmsdAi2dxaWOeyhlRzVl6TYozMnhHIjJLCM5y%2BlwaweHOn96afg%2FuHhnl60ETUvgR1HpJsQntkptrcuO0bOOhuLg1NBPfyH6Swrpw2W9O24rBu8kwH8DuEdns9Kv1hLc5rsxBaTLcN1HIdhHIVRuFov5wtMXH748vO2%2BP0jUzjFXE7%2FbMa3%2BFZl3z1ZxhWyjv2fwlfy9NaY6LhO0lm4WC3WcRSvlqO4UqiXYT7C%2B7vwcT7SWlFAxg3LtMHNfH2ODnZ4kIPVPRo9jnN1r5eDNup%2BIy2y5GxuDrQqYMNb6dje9or44HOyQYTnWs%2FXXoD7%2Ba8WrGO4hwZuK%2B2Qt%2F32tAPhB%2B4xt238qjVQtpIbuuvIP6wbjfAIhStncO3eZ0f9keMHmYHuo%2BCwFoJ%2BDfktdEF0JPfebbxgct30b%2BdhY%2B51u%2FGm2U2IR7rW%2FbJU%2FdcBfpEchHjwoO52%2FwENmVvErwgAAA%3D%3D'>"
    }
  ]
}

Uma visualização do novo Tweet agendado criado é mostrada acima

Associar um Tweet agendado a um item de linha

Embora Tweets agendados possam ser usados para criar Tweets orgânicos, também permitimos que parceiros criem um Tweet “Somente promovido” (nullcast=true), podendo qualquer um dos tipos ser associado a um item de linha. Para viabilizar isso, também fornecemos o endpoint POST accounts/:account_id/scheduled_promoted_tweets. Esse endpoint permite associar apenas um único Tweet agendado promovido a um item de linha por chamada de API. Para associar vários Tweets agendados ao mesmo item de linha, são necessárias múltiplas chamadas de API.

Observe que não é possível modificar um Tweet agendado promovido existente.

twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072'

{
  "data": {
    "line_item_id": "a44qc",
    "id": "26576",
    "created_at": "2017-10-09T22:24:16Z",
    "updated_at": "2017-10-09T22:24:16Z",
    "scheduled_tweet_id": "917507899668099072",
    "tweet_id": null,
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "a44qc",
      "scheduled_tweet_id": 917507899668099100,
      "account_id": "aaaaa"
    }
  }
}

Este endpoint apenas cria uma associação entre um Scheduled Tweet específico e um item de linha. Assim que as datas de veiculação da campanha/item de linha entrarem em vigor, o item de linha começará automaticamente a veicular o Tweet “ativo” correspondente. Embora validemos, nesta etapa, que o Scheduled Tweet está no estado SCHEDULED e que o Scheduled Tweet informado é válido para o objetivo definido, nenhuma outra validação é executada. Quaisquer regras de validação restantes que se aplicam ao item de linha e ao Scheduled Tweet são executadas quando o Tweet fica “ativo”.

Para garantir que não haja problemas com a veiculação da campanha, recomenda-se que o Scheduled Tweet esteja com scheduled_at definido para um horário anterior às datas de veiculação da campanha/item de linha.

Por exemplo, suponha que o Scheduled Tweet esteja definido para ficar ativo após a data de início da campanha (e que haja apenas um único Tweet associado a um único item de linha). Nesse caso, a campanha ficará ACTIVE; no entanto, como o Scheduled Tweet ainda não está ativo, não haverá criativos disponíveis para veiculação.

Gerenciamento de Scheduled Tweet

Os conjuntos restantes de endpoints permitem que consumidores da API gerenciem todos os seus Scheduled Tweets e Scheduled Promoted Tweets. Essas APIs podem ser usadas para retornar uma lista de todos os Scheduled Tweets, opcionalmente filtrada por um determinado estado, bem como consultar um Scheduled Tweet específico pelo seu id.

​

O que acontece quando um Scheduled Tweet entra no ar?

Quando um Scheduled Tweet está prestes a entrar no ar, ou seja, no horário scheduled_at, as seguintes atualizações são aplicadas:

• O Tweet “ao vivo” é criado; no entanto, isso pode ter uma latência de até 1 segundo
• O tweet_id é adicionado às seguintes entidades:
• Scheduled Tweet
• Promoted Scheduled Tweet
• Uma nova entidade Promoted Tweet é criada

​

Melhores práticas

Recomenda-se observar as seguintes melhores práticas ao criar ou promover Tweets programados:

• Verifique se o Tweet é válido ao criar o Tweet programado (por exemplo, um Tweet pode conter apenas uma Imagem, um Vídeo ou um GIF, e não qualquer combinação dos três)
• Verifique se as datas do período da campanha (ou seja, start_time e end_time) estão alinhadas com o horário scheduled_at do Tweet programado
• Tweets programados não devem ser definidos para mais de um ano no futuro (365 dias)
• A visualização de Tweet atualmente não é compatível para Tweets programados (ou seja, a capacidade de pré-visualizar Tweets programados antes da criação)

​

Biblioteca de mídia

​

Introdução

Os endpoints da Media Library permitem gerenciar imagens, GIFs e vídeos para contas do X Ads. Os recursos de mídia na biblioteca podem ser usados em Tweets e na criação de cards. Eles também podem ser reutilizados em várias peças criativas, eliminando a necessidade de enviar o mesmo recurso várias vezes.

​

Endpoints da API

• POST media/upload ou POST media/upload (em partes) (fazer upload de mídia)
• POST accounts/:account_id/media_library (adicionar mídia à biblioteca de mídia)

​

Adicionando à biblioteca

Adicionar mídia à biblioteca é um processo em duas etapas. Primeiro, faça o upload do asset usando o endpoint POST media/upload ou o conjunto de endpoints POST media/upload (chunked). (Consulte o guia Chunked media upload para detalhes sobre nosso processo de upload em várias partes.)

twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"

{
   "media_id":966947208837742592,
   "media_id_string":"966947208837742592",
   "size":74194,
   "expires_after_secs":86400,
   "image":{
      "image_type":"image/jpeg",
      "w":800,
      "h":418
   }
}

Em seguida, usando o id da mídia, adicione a mídia à biblioteca da conta de anúncios usando o endpoint POST accounts/:account_id/media_library.

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte"

{
   "request":{
      "params":{
         "name":"Latte",
         "file_name":"latte.jpeg",
         "media_category":"TWEET_IMAGE",
         "account_id":"18ce54d4x5t",
         "media_key":966947208837742592
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

Observação: Publicar imagens, GIFs ou vídeos imediatamente após o upload também adiciona o conteúdo de mídia à biblioteca.

​

Parâmetros da solicitação

Todas as solicitações POST da Media Library exigem um identificador de mídia. Esse valor é retornado durante a etapa de upload. Ao usar o media_id, como no exemplo acima, também é necessário especificar um media_category. Há quatro valores de categoria possíveis: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE e TWEET_VIDEO.

Opcionalmente, é possível definir os valores name e file_name para objetos na Media Library. Esses atributos ajudam os usuários a diferenciar variantes de mídia na biblioteca.

Para vídeos, também é possível definir um título e uma descrição. Esses valores devem ser passados como os parâmetros de solicitação video_title e video_description com o endpoint POST accounts/:account_id/tweet. No Tweet, esse texto aparece abaixo do vídeo.

​

Atributos

A Media Library introduz formalmente o conceito de media_key. Esse é o identificador exclusivo dos objetos na biblioteca. As media keys são valores de string no seguinte formato: 13_875943225764098048. Elas são totalmente compatíveis em todos os nossos endpoints de cards.

Além disso, a resposta da Media Library inclui o media_id, representado como string. Ele é fornecido para recursos que atualmente não aceitam uma media key: Tweets, Prévia de Tweet e Tweets agendados. Estamos trabalhando para oferecer suporte a media keys em todos os lugares.

O atributo aspect_ratio é retornado para GIFs e vídeos. Ele pode ser usado para filtrar mídia para uso em cards que aceitam apenas determinadas proporções de aspecto.

*Esses endpoints oferecem suporte ao parâmetro video_id, que é uma media key.

​

Uso

Nesta seção, a imagem a seguir será usada em um Tweet e para criar um cartão de site.

twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592"

{
   "request":{
      "params":{
         "account_id":"18ce54d4x5t",
         "media_key":"3_966947208837742592"
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

Tweet

Podemos criar o Tweet referenciando as imagens por meio de media_keys.

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true"

{
   "data":{
      "created_at":"Fri Feb 23 08:20:05 +0000 2018",
      "id":966950781302665218,
      "id_str":"966950781302665218",
      "text":"café https://t.co/T772Hx5GNT",
      "truncated":false,
      "entities":{
         "hashtags":[

         ],
         "symbols":[

         ],
         "user_mentions":[

         ],
         "urls":[

         ],
         "media":[
            {
               "id":966947208837742592,
               "id_str":"966947208837742592",
               "indices":[
                  7,
                  30
               ],
               "media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "url":"https://t.co/T772Hx5GNT",
               "display_url":"pic.x.com/T772Hx5GNT",
               "expanded_url":"https://x.com/apimctestface/status/966950781302665218/photo/1",
               "type":"photo",
               "sizes":{
                  "thumb":{
                     "w":150,
                     "h":150,
                     "resize":"crop"
                  },
                  "large":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "medium":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "small":{
                     "w":680,
                     "h":355,
                     "resize":"fit"
                  }
               }
            }
         ]
      },
      "source":"App de Teste Interno do X Ads API",
      "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":756201191646691328,
         "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":{
         "as_user_id":756201191646691328,
         "text":"café",
         "account_id":"18ce54d4x5t",
         "media_keys":[
            966947208837742592
         ],
         "trim_user":true
      }
   }
}

Website Card

Todos os nossos endpoints de cards oferecem suporte a media keys. Vamos criar o website card referenciando a media_key da imagem.

twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards"

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

Em seguida, associamos esse card a um Tweet usando seu card_uri.

​

Identificando cards

​

Introdução

Cards são formatos de anúncio personalizáveis que usam mídia e podem ser associados a um site, a um App ou a chamadas para ação para incentivar determinados engajamentos do usuário, como iniciar uma Mensagem Direta. Eles podem ser anexados a Tweets, Tweets agendados ou Tweets em rascunho.

Cards podem ser referenciados em objetos de Tweet de duas maneiras: pelo card_uri do card ou pelo seu preview_url. Valores de exemplo para cada um são apresentados abaixo.

card_uri	preview_url
card://1043282691834048513	https://cards.x.com/cards/18ce54d4x5t/68w3s

Observação: A partir da versão 3 da X Ads API, somente o card_uri é gerado e retornado na resposta de cards para cards recém-criados.

Observação: A partir da versão 5 da X Ads API, o preview_url na resposta de cards não é mais retornado.

O tipo de referência na resposta do objeto Tweet dependerá da forma como o Tweet foi criado. Em outras palavras, se o Tweet foi criado usando o parâmetro de requisição card_uri, o valor do URI do card aparecerá na resposta. Por outro lado, se o preview_url foi incluído como parte do texto do Tweet, a URL de preview aparecerá na resposta.

​

Identificando Tweets com card_uri

Para Tweets criados usando o valor de URI do card, localize a referência ao card no atributo de resposta card_uri. O exemplo de resposta abaixo usa o endpoint GET accounts/:account_id/tweets.

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
  "request": {
    "params": {
      "tweet_ids": [
        "1043551275923591168"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "source": "App de Teste Interno da X Ads API",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        15
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1043551275923591168",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 1043551275923591168,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "card_uri": "card://1043282691834048513",
      "full_text": "Rastreando um card",
      "lang": "en",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1043551275923591168"
    }
  ]
}

Se estiver usando a API Standard, use include_card_uri=true na solicitação.

Independentemente do endpoint utilizado, o atributo de resposta card_uri só será retornado se o Tweet tiver sido criado usando um card URI.

Para objetos de Tweet agendados e rascunhos, a resposta sempre incluirá o atributo de resposta card_uri.

​

Identificando Tweets com preview_url

Para Tweets criados ao incluir a URL de prévia como parte do texto do Tweet, a URL pode ser encontrada em entities[“urls”][i][“expanded_url”] (o campo text inclui uma URL t.co encurtada), em que i é um índice do array (um Tweet pode conter várias URLs).

Para objetos de Tweet agendados e rascunhos, a URL de prévia sempre aparecerá no campo text.

​

Obtenção de cards

Para recuperar informações adicionais sobre um card específico, fornecemos dois endpoints: GET accounts/:account_id/cards/all e GET accounts/:account_id/cards/all/:card_id. O primeiro permite obter um card por card_uri e o segundo pelo id do card. O id do card é encontrado no final de preview_url. No exemplo acima, o id é 68w3s.

​

Identificação de mídia

​

Introdução

Mídia — imagens, GIFs e vídeos — pode ser adicionada a Tweets e cards. Além disso, vídeos podem ser usados como assets de pre-roll e imagens podem ser promovidas na X Audience Platform. Esta seção descreve como encontrar referências de mídia nessas entidades.

Existem dois tipos de identificadores de mídia: IDs e chaves. Valores de exemplo para cada um são apresentados abaixo.

ID de mídia	Chave de mídia
1029825579531807971	13_1029825579531807971

A chave de mídia é o ID acrescido de um prefixo numérico e um sublinhado.

​

Imagens

A tabela a seguir mostra os tipos de identificadores atualmente disponíveis na resposta de cada recurso relacionado a imagem, bem como o(s) nome(s) de atributo correspondente(s).

Recurso	Identificador	Atributo(s)
Image cards	None
Tweet	Both	entities["media"]["id_str"] entities["media"]["media_key"]
Scheduled Tweet	Both	media_ids and media_keys
Draft Tweet	Both	media_ids and media_keys
Account Media	None
Media Library	Both	media_id and media_key

Imagens de Image cards e Account Media não incluem referência a nenhum identificador de mídia. Tweets incluem apenas IDs de mídia. Scheduled e Draft Tweets incluem tanto o ID de mídia quanto a media key. Media Library também retorna ambos.

Para Tweets, os campos id e id_str no objeto dentro do array entities[“media”] correspondem ao ID de mídia. Nos casos em que um Tweet inclui várias imagens, as referências a cada entidade de mídia só podem ser encontradas em extended_entities[“media”].

Além das referências a identificadores, muitas vezes é importante ter acesso à URL da imagem.

Recurso	Atributo(s)	Formato
Image cards	image	.jpg
Tweet*	entities["media"][0]["media_url"] or extended_entities["media"][i]["media_url"]	.jpg
Scheduled Tweet	None
Draft Tweet	None
Account Media	media_url	.jpg
Media Library	media_url	.jpg

• A localização dessa URL depende de o Tweet conter uma única imagem ou várias imagens.

Todos os Image cards incluem um atributo de resposta de imagem que contém a URL da imagem no X. (Para image app download cards, o nome é wide_app_image.)

Para Tweets, a localização da media URL depende do tipo de mídia e do endpoint utilizado. Para Tweets com uma única imagem, a URL pode ser encontrada em entities[“media”][0][“media_url”]. Isso é válido tanto para a X Ads API quanto para a Standard API. Quando os Tweets contêm várias imagens, no entanto, as URLs só podem ser encontradas em extended_entities[“media”][i][“media_url”]. Isso está disponível apenas na Standard API.

​

Vídeos

A tabela a seguir mostra os tipos de identificadores atualmente disponíveis na resposta de cada recurso relacionado a vídeo, bem como os respectivos nomes de atributos.

Recurso	Identificador	Atributo(s)
Cartões de vídeo	Pode ser qualquer um dos dois	video_content_id
Cartões de enquete com vídeo	Nenhum
Tweet	Ambos	entities["media"]["id_str"] entities["media"]["media_key"]
Tweet agendado	Ambos	media_ids and media_keys
Rascunho de Tweet	Ambos	media_ids and media_keys
Mídia da conta	Chave de mídia	video_id
Biblioteca de mídia	Ambos	media_id and media_key

Embora os cartões de vídeo (com exceção dos cartões de enquete com vídeo) incluam um atributo de resposta video_content_id, há inconsistência no tipo de valor retornado. Em alguns casos, é um ID de mídia; em outros, é uma chave de mídia.

A seguir estão as informações sobre como acessar a URL do vídeo.

Recurso	Atributo(s)	Formato
Cartões de vídeo	video_url and video_hls_url	.vmap .m3u8
Tweet com vídeo	extended_entities["media"][i]["video_info"]["variants"][j]["url"]	.mp4
Tweet agendado	Nenhum
Rascunho de Tweet	Nenhum
Mídia da conta	Nenhum
Biblioteca de mídia	media_url	.mp4

Os cartões de vídeo incluem os atributos de resposta video_url e video_hls_url com URLs .vmap e .m3u8, respectivamente.

​

Biblioteca de Mídia

Às vezes é necessário obter informações adicionais sobre um ativo de mídia. Um caso de uso, para cartões de vídeo, é recuperar a URL em mp4 em vez da vmap. Isso está disponível na Biblioteca de Mídia. Para detalhes sobre as informações disponíveis, consulte nosso Guia da Biblioteca de Mídia. A maioria dos ativos pertencentes ao usuário FULL promotable da conta de anúncios pode ser encontrada na biblioteca. Há algumas exceções, porém.

Busca de mídia

Como mencionado acima, cartões de imagem não contêm referências a media IDs nem a chaves de mídia. Como resultado, não é possível buscar seus ativos por meio da Biblioteca de Mídia. Isso também vale para imagens de Account Media.

Cartões de vídeo exigem que o ativo de vídeo faça parte da Biblioteca de Mídia (ou do recurso Videos anteriormente) antes de sua criação. Como resultado, esses ativos sempre poderão ser recuperados na Biblioteca de Mídia. Isso também vale para ativos PREROLL de Account Media.

Por fim, mídias em Tweets sempre estão garantidamente na Biblioteca de Mídia.

A tabela a seguir resume quais ativos podem ser recuperados na Biblioteca de Mídia, levando em conta se a resposta do recurso inclui um identificador a ser usado na busca.

Recurso	Na Biblioteca de Mídia
Cartões de imagem	Não
Cartões de vídeo	Sim*
Tweets (qualquer mídia)**	Sim
Tweets agendados	Sim
Tweets em rascunho	Sim
Imagens de Account Media	Não
Vídeos de Account Media (PREROLL)	Sim

• Para cartões em que o video_content_id é uma chave de mídia. Quando o valor é um media ID, o ativo ainda existe na Biblioteca de Mídia, mas recuperá-lo envolve anexar um prefixo numérico e um sublinhado a ele. ** Tweets retornam apenas media IDs. Embora o ativo esteja garantido na Biblioteca de Mídia, buscá-lo envolve anexar um prefixo numérico e um sublinhado a ele.

Interações com Account Media

Há duas situações em que ativos de mídia adicionados à biblioteca são automaticamente adicionados ao recurso Account Media.

• Quando um ativo AMPLIFY_VIDEO é adicionado à Biblioteca de Mídia, ele é automaticamente adicionado como ativo de Account Media, com o tipo criativo PREROLL.
• Quando imagens com dimensões específicas (veja “Creative Types” em nossa página de enumerações) são adicionadas à Biblioteca de Mídia, elas são automaticamente adicionadas como ativos de Account Media. O tipo criativo (por exemplo, INTERSTITIAL) depende das dimensões da imagem.

​

Tweets

​

Introdução

A X Ads API oferece suporte a três tipos de Tweets: publicados, programados e rascunhos.

​

Tweets nullcast

Tweets podem ser nullcast (também chamados de “Promoted-only”) ou orgânicos. Tweets nullcast, após publicados, não aparecem na linha do tempo pública do usuário, embora sejam públicos. Tweets orgânicos, por outro lado, são entregues aos seguidores do usuário e aparecem na linha do tempo pública do usuário.

Criando Tweets

Cada um dos três endpoints de criação de Tweet oferece suporte a um parâmetro booleano nullcast que dá ao usuário da API a opção de criar Tweets nullcast ou orgânicos. Tweets nullcast podem ser criados pelo usuário ou por qualquer pessoa que tenha permissão para criar Tweets em nome do usuário. Tweets orgânicos só podem ser criados pelo full promotable user.

Atualizando Tweets

É possível atualizar a propriedade nullcast para Tweets agendados e rascunhos. Para Tweets agendados, edições podem ser feitas até o horário scheduled_at do Tweet. Rascunhos de Tweets podem ser editados indefinidamente. Depois de publicados, no entanto, não é possível alterar um Tweet de nullcast para orgânico ou vice-versa.

​

Promoção de Tweets

Somente Tweets publicados e agendados podem ser promovidos. Eles podem ser nullcast ou orgânicos; não há restrição. Um anunciante pode promover seus próprios Tweets ou os Tweets de outro usuário, desde que tenha obtido permissão para isso. (Consulte: Promoting another user’s Tweets para mais informações.)

Vários Tweets podem ser promovidos em uma única campanha. Da mesma forma, um único Tweet pode ser promovido em uma ou mais campanhas.

Para promover Tweets publicados, use o endpoint POST accounts/:account_id/promoted_tweets. Isso associa Tweets publicados a um item de linha. Para promover Tweets agendados, use o endpoint POST accounts/:account_id/scheduled_promoted_tweets.

​

IDs de Tweet

IDs de Tweet publicados, agendados e em rascunho são numéricos — são inteiros sem sinal de 64 bits. Por exemplo, o ID do seguinte Tweet publicado é 1166476031668015104.

Quando Tweets publicados ou agendados são promovidos, é criada uma entidade de Tweet promovido correspondente. Essas entidades têm seus próprios IDs, que são alfanuméricos e representados como valores codificados em base 36. Por exemplo, promover o Tweet publicado acima — ou seja, associá-lo a um line item 6c62d — retorna a seguinte resposta da API.

$ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104"
{
  "request": {
    "params": {
      "tweet_ids": [
        1166476031668015104
      ],
      "line_item_id": "6c62d",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "line_item_id": "6c62d",
      "id": "3qwlq6",
      "entity_status": "ACTIVE",
      "created_at": "2019-09-12T21:39:10Z",
      "updated_at": "2019-09-12T21:39:10Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "1166476031668015104",
      "deleted": false
    }
  ],
  "total_count": 1
}

Além do ID do Tweet e do ID do line item, que foram enviados na solicitação de criação, a resposta inclui um campo id com o valor 3qw1q6, que é o ID do Tweet promovido.

​

Carrossel

​

Introdução

A X Ads API oferece suporte à criação e recuperação de carrosséis de vídeo e de imagem. O carrossel é um tipo de card que pode conter entre 2 e 6 itens de mídia. O card de carrossel pode direcionar o usuário a um site ou incentivá-lo a instalar um aplicativo móvel. Para mais informações sobre carrosséis, seus benefícios, práticas recomendadas e perguntas frequentes, consulte nossa página Carousel Ads on X.

Um carrossel, como qualquer outro tipo de card, pode ser usado em Tweets e esses Tweets podem, então, ser promovidos. O fluxo de trabalho é o mesmo ao qual você já está acostumado:

1. Fazer upload da mídia
2. Criar o card
3. Criar o Tweet
4. Promover o Tweet

A única diferença está em como o card é criado. Enquanto outras solicitações de criação de card aceitam parâmetros de query, as solicitações de criação de card de carrossel aceitam apenas corpos de POST em JSON.

​

Endpoints

A X Ads API oferece suporte à criação e à recuperação de carrosséis.

Para criar um carrossel — de qualquer tipo — use o endpoint POST accounts/:account_id/cards. Para recuperar carrosséis, use o endpoint GET accounts/:account_id/cards.

​

Corpo de POST JSON

Os carrosséis são criados com dois componentes. O primeiro especifica os ativos de mídia que serão usados. O segundo especifica informações sobre o site ou o App.

Especificamente, um cartão de carrossel é criado usando os seguintes componentes, nesta ordem:

• Um componente SWIPEABLE_MEDIA, que aceita um array de chaves de mídia
• Um dos seguintes:
• Um componente DETAILS para especificar informações do site
• Um componente BUTTON para especificar informações do App

O componente SWIPEABLE_MEDIA deve incluir um array media_keys no qual você pode especificar entre 2 e 6 imagens ou vídeos. A ordem em que as chaves de mídia são passadas determina a ordem em que serão renderizadas.

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

Como lembrete, você pode obter chaves de mídia fazendo uma solicitação ao endpoint GET accounts/:account_id/media_library.

A composição do segundo objeto de componente depende de você querer direcionar o usuário a um site ou incentivá-lo a instalar um app. A tabela abaixo resume as duas opções. (Observação: todas as chaves listadas são obrigatórias.)

	Site	App
Especificar o tipo de componente	"type": "DETAILS"	"type": "BUTTON"
Título/Rótulo	"title": "X"	"label": { "type": "ENUM", "value": "INSTALL" }
Destino	"destination": { "type": "WEBSITE", "url": "https://www.x.com" }	"destination": { "type": "APP", ... }

Reunindo tudo, veja abaixo um exemplo de corpo de POST JSON para carrossel de site.

{
  "name": "carrossel do site",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "DETAILS",
      "title": "X",
      "destination": {
        "type": "WEBSITE",
        "url": "https://www.x.com"
      }
    }
  ]
}

Objetos de destino de App dentro de componentes BUTTON exigem um código de país e pelo menos um identificador de app. Eles também podem aceitar deep links de forma opcional. Para uma descrição desses fields, consulte a documentação de referência.

Com isso, abaixo segue um exemplo de corpo de POST JSON para um carrossel de app.

{
  "name": "carrossel do app",
  "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"
      }
    }
  ]
}

​

Exemplo

Esta seção demonstra como criar um card de carrossel de site de vídeo e como usá-lo em um Tweet. Como mencionado acima, o fluxo de trabalho é o mesmo ao qual você já está acostumado: fazer upload da mídia, criar o card e criar o Tweet. A única diferença é a forma como o card é criado.

Mídia

Para começar, faça upload de novos ativos de mídia ou use os existentes. Para saber como enviar novos ativos de mídia e adicioná-los à Biblioteca de Mídia, consulte nosso Guia da Biblioteca de Mídia.

Depois que seus ativos de mídia estiverem na Biblioteca de Mídia, recupere-os usando o endpoint GET accounts/:account_id/media_library. Use o parâmetro de requisição media_type para restringir os resultados a um tipo específico de mídia.

$ 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": "Nascer do sol",
      "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": "Neve",
      "file_name": "snow.mp4",
      "description": "Dois, três e quatro",
      "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": "Um"
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2020-03-27T22:23:18Z",
      "deleted": false
    }
  ]
}

Criação de carrossel

Use o endpoint POST accounts/:account_id/cards para criar seu carrossel. Utilize as media keys da solicitação anterior. Lembre-se de que a ordem em que as media keys são fornecidas determina a ordem em que serão renderizadas.

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

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "carrossel do site",
    "components": [
      {
        "type": "SWIPEABLE_MEDIA",
        "media_keys": [
          "13_1089771253848666112",
          "13_1191948012077092867"
        ]
      },
      {
        "type": "DETAILS",
        "title": "X",
        "destination": {
          "type": "WEBSITE",
          "url": "https://www.x.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"
  }
}

Observe que, assim como em outros cards, a resposta do card de carrossel inclui um card_uri, que será usado ao criar um Tweet.

Tweet

Use o endpoint POST accounts/:account_id/tweet para criar o seu Tweet. Utilize o card_uri da solicitação anterior. (Resposta truncada para facilitar a leitura.)

$ 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": "Deslizar",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "App de teste interna da X Ads API",
    "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": "Deslizar"
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}

Prévias de Tweet

Use o endpoint GET accounts/:account_id/tweet_previews para visualizar seu Tweet.

​

marcação-de-metadata-de-criativos

​

Introdução

Este guia é destinado a parceiros criativos, agências e desenvolvedores criativos para etiquetar ativos usados em campanhas na X, a fim de compreender melhor o valor e o desempenho de cada ativo.

Observação: Os ativos de mídia devem ser etiquetados apenas pelo parceiro ou desenvolvedor que os criou. Se o usuário do ativo de mídia não o criou, não implemente a marcação de metadata.

A Marcação de Metadata Criativa fornece atribuição para imagens e vídeos criados por parceiros criativos, independentemente de onde o ativo seja enviado à X ou de quem esteja fazendo o envio. Para estabelecer a conexão entre o ativo criativo e o parceiro criativo, utiliza-se o padrão XMP.

​

Marcação de ativos criativos

A tabela a seguir mostra os tipos de identificadores atualmente disponíveis na resposta de cada recurso relacionado a imagem, bem como os respectivos nomes de atributos. É necessário usar uma ferramenta de marcação para etiquetar ativos criativos. Recomendamos o ExifTool, uma biblioteca Perl multiplataforma e um aplicativo de linha de comando para ler, gravar e editar metadados. Veja todos os tipos de arquivo compatíveis.

Siga as instruções para instalar o ExifTool. Também há pacotes de software oferecidos pelo Homebrew para simplificar a instalação, fornecendo o comando exiftool de instalação para macOS e Linux. Confirme que a ferramenta foi instalada corretamente digitando exiftool -ver no terminal para exibir o número da versão. Saiba mais sobre os parâmetros de comando do ExifTool na documentação do ExifTool.

Parceiros criativos podem atribuir metadados a ativos criativos novos ou existentes definindo seu X app_id na tag XMP contributor e a data na tag date. Os ativos criativos seguirão as restrições de tamanho existentes ao fazer upload de mídia.

Observação: O uso da tag XMP contributor pela X garante que os metadados capturem valores exclusivamente para campanhas na X.

exiftool -contributor="<YOUR APP ID>" -creative_file.jpg

exiftool -date="<date>" -creative_file.jpg

O app_id pode ser encontrado no portal do desenvolvedor, em Projects & Apps. Exemplo: 16489123

O exemplo a seguir adiciona o app_id como a tag contributor e a data como a tag date para uma imagem:

app_id:858382169

date:2022-03-13

arquivo_criativo: eiffel_tower.jpg

exiftool -contributor=858382169 eiffel_tower.jpg

   1 arquivo de imagem atualizado

exiftool -date=2022-03-13 eiffel_tower.jpg

  1 arquivos de imagem atualizados

Verifique se sua imagem foi corretamente etiquetada:

exiftool -xmp:all -G1 <filename>

Exemplo:

exiftool -xmp:all -G1 eiffel_tower.jpg

[XMP]        XMP Toolkit            : Image::ExifTool 12.30

[XMP]        Colaborador            : 858382169

[XMP]        Data                   : 2022:03:13

​

Dúvidas?

Se você deseja confirmar que sua marcação e atribuição foram bem-sucedidas, envie ativos de exemplo que tenham sido marcados para [e-mail], para que um representante da X faça a revisão.

​

Referência da API

​

Mídia da conta

Executar no Postman

​

GET accounts/:account_id/account_media

Recupere detalhes de parte ou de toda a mídia da conta associada à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/account_media

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
account_media_ids opcional	Restrinja a resposta apenas às mídias de conta desejadas especificando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Type: string Example: 3wpx
count opcional	Especifica o número de registros a tentar recuperar por solicitação. Type: int Default: 200 Min, Max: 1, 1000
creative_types opcional	Restrinja a resposta apenas às mídias da conta que correspondam aos tipos criativos especificados. É possível especificar mais de um tipo criativo separando os valores do enum por vírgulas. Type: enum Possible values: BANNER, BANNER_TABLET, INTERSTITIAL, INTERSTITIAL_LANDSCAPE, INTERSTITIAL_LANDSCAPE_TABLET, INTERSTITIAL_TABLET, MEDIUM_RECTANGLE, PREROLL, VAST_PREROLL
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: 8x7v00oow
sort_by opcional	Ordena por um atributo compatível em ordem crescente ou decrescente. Consulte Sorting para mais informações. Type: string Example: created_at-asc
with_deleted opcional	Inclui resultados excluídos na sua solicitação. Type: boolean Default: false Possible values: true, false
with_total_count opcional	Inclui o atributo de resposta total_count. Observação: Este parâmetro e cursor são mutuamente exclusivos. Observação: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. Type: boolean Default: false Possible values: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media?account_media_ids=3wpx

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_media_ids": [
        "3wpx"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_id": "13_771791717175468032",
      "media_url": null,
      "creative_type": "PREROLL",
      "id": "3wpx",
      "created_at": "2016-09-02T19:27:52Z",
      "updated_at": "2016-09-02T19:27:52Z",
      "deleted": false
    }
  ]
}

Recupere um objeto de mídia específico da conta associado à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
account_media_id obrigatório	Uma referência à mídia da conta com a qual você está operando na solicitação. Tipo: string Exemplo: 2pnfd
with_deleted opcional	Inclui resultados excluídos na sua solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_media_id": "2pnfd",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-07-28T01:44:41Z",
    "deleted": false
  }
}

Exclua o objeto de mídia de conta especificado que pertence à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
account_media_id obrigatório	Uma referência à mídia da conta com a qual você está operando na solicitação. Type: string Example: 2pnfd

​

Exemplo de requisição

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd

​

Exemplo de resposta

{
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-08-25T17:16:26Z",
    "deleted": true
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "account_media_id": "2pnfd"
    }
  }
}

​

Cards

Executar no Postman

Observação: Para associar um card a um Tweet, use o parâmetro card_uri com um dos endpoints POST accounts/:account_id/tweet, POST statuses/update, POST accounts/:account_id/scheduled_tweets ou POST accounts/:account_id/draft_tweets.

Recupere os detalhes de alguns ou de todos os cards associados à conta atual.

Observação: Isso retorna apenas cards criados usando o endpoint POST accounts/:account_id/cards. Cards criados usando outros endpoints não são retornados.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
card_types opcional	Restrinja a resposta apenas aos tipos de card desejados especificando uma lista de valores enum separados por vírgula. Tipo: enum Valores possíveis: IMAGE_APP, IMAGE_CAROUSEL_APP, IMAGE_CAROUSEL_WEBSITE, IMAGE_MULTI_DEST_CAROUSEL_WEBSITE, IMAGE_WEBSITE, MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE, VIDEO_APP, VIDEO_CAROUSEL_APP, VIDEO_CAROUSEL_WEBSITE, VIDEO_MULTI_DEST_CAROUSEL_WEBSITE, VIDEO_WEBSITE
card_id opcional	Restrinja a resposta apenas aos cards desejados especificando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 IDs de card. Tipo: string Exemplo: 1044294149527166979,1044301099031658496
card_uris opcional	Restrinja a resposta apenas aos cards desejados especificando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 valores de URI de card. Tipo: string Exemplo: card://1044294149527166979,card://1044301099031658496
count opcional	Especifica o número de registros a tentar recuperar por solicitação. Tipo: int Padrão: 100 Mín., máx.: 1, 200
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Paginação para mais informações. Tipo: string Exemplo: 8x7v00oow
include_legacy_cards opcional	Inclui cards legados de website e app na resposta. Cards legados são aqueles cujo URL de recurso tem o seguinte formato: accounts/:account_id/cards/:card_type. Consulte esta publicação no fórum de desenvolvedores para mais contexto. Tipo: boolean Padrão: false Valores possíveis: true, false
q opcional	Uma query opcional para limitar cards por name. Omita este parâmetro para recuperar todos. Comprimento máximo: 80 caracteres. Observação: faz correspondência por prefixo sem diferenciar maiúsculas de minúsculas. Tipo: string Exemplo: dtc
sort_by opcional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Classificação para mais informações. Tipo: string Exemplo: created_at-asc
with_deleted opcional	Inclui resultados excluídos na solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1

​

Exemplo de resposta

{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8wzvldqtc",
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "ABRIR",
          },
          "destination": {
            "type": "APP",
            "country_code": "US"
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

Recupere os detalhes de um único card associado à conta atual.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id obrigatório	O id dos cards. Type: string Example: 1044294149527166979
with_deleted opcional	Incluir resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN",
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

​

POST accounts/:account_id/cards

Crie um novo card associado à conta especificada.

As solicitações de criação de card aceitam apenas corpos de POST em JSON. O Content-Type deve ser definido como application/json.

Consulte o nosso Guia de Carrosséis para um exemplo de uso detalhado.

​

URL do recurso

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

​

Parâmetros

O corpo da requisição POST em JSON deve incluir um name do card e um array de components. Os componentes são representados como objetos e descrevem os atributos do card voltados ao anunciante.

O exemplo a seguir mostra a estrutura geral do payload (mas inclui informações não funcionais).

{
  "name": "um nome",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "valor"
    }
  ]
}

Informações adicionais sobre os componentes abaixo.

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
name required	O nome do card. Tamanho máximo: 80 caracteres. Type: string Example: component based card
components sometimes required	Descreve os componentes a serem usados para criar o card. Mais informações abaixo. Não pode ser especificado junto com slides. Observação: a ordem dos componentes é importante. Type: array of objects
slides sometimes required	Use este array de arrays para criar carrosséis com vários destinos (Multi-Destination Carousels). Descreve cada card como um agrupamento de componentes. Cada slide deve representar um card completo. Não pode ser especificado junto com components. Observação: a ordem de cada slide é importante. Type: array of array

​

Componentes

Todo componente deve incluir um campo type que determina o esquema do objeto. A X Ads API oferece suporte aos seguintes tipos de componente, agrupados em componentes baseados em mídia e em descrição.

• Mídia:
• MEDIA: vídeo ou imagem únicos
• SWIPEABLE_MEDIA: entre 2 e 6 vídeos ou imagens
• Descrição:
• DETAILS
• BUTTON

Cada componente possui um conjunto de campos obrigatórios (além da chave type). Eles estão listados na tabela a seguir.

type do componente	Campo	Tipo de valor
MEDIA	media_key	string
SWIPEABLE_MEDIA	media_keys	array of strings
DETAILS	title destination	string object
BUTTON	label destination	object object

A seguir está um exemplo de um componente BUTTON no contexto do array components (omitindo intencionalmente a chave name). (As reticências indicam locais onde mais informações precisam ser especificadas.)

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        ...
      },
      "destination": {
        ...
      }
    }
  ]
}

A ordem em que os objetos de componente são especificados define a ordem de cima para baixo em que serão renderizados. Cards devem ser criados usando um componente baseado em mídia e um componente DETAILS ou BUTTON. Componentes baseados em descrição são renderizados abaixo da mídia e têm destinos associados, que podem ser URLs ou apps móveis.

Label

Labels definem o texto exibido em botões e, portanto, aplicam-se apenas ao componente BUTTON. Objetos Label têm duas chaves obrigatórias: type e value. O type deve ser definido como ENUM e o value pode ser um dos seguintes: BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY ou SHOP.

Com base no exemplo anterior, o seguinte mostra o objeto label dentro do componente BUTTON.

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALAR"
      },
      "destination": {
        ...
      }
    }
  ]
}

Destino

Destinos são para onde os anunciantes pretendem levar os usuários. Eles são sempre exigidos nos componentes DETAILS ou BUTTON. Há dois tipos de destino: WEBSITE ou APP.

Observação: Destinos de website só podem ser usados com componentes DETAILS e destinos de app só podem ser usados com componentes BUTTON.

Destino de Website

Nome	Descrição
type obrigatório	O tipo de destino, que determina seu schema. Tipo: enum Valores possíveis: WEBSITE
url obrigatório	A URL do website para o qual o usuário será redirecionado. Tipo: string Exemplo: https://devcommunity.x.com/c/advertiser-api

Destino de App

Nome	Descrição
type obrigatório	O tipo de destino, que determina seu schema. Tipo: enum Valores possíveis: APP
country_code obrigatório	O código de duas letras ISO 3166-1 alpha-2 do país onde o app é distribuído. Tipo: string Exemplo: US
googleplay_app_id às vezes obrigatório	O nome do pacote do app no Google Play. Observação: Pelo menos um dos seguintes é obrigatório: ios_app_store_identifier ou googleplay_app_id. Tipo: string Exemplo: com.twitter.android
ios_app_store_identifier às vezes obrigatório	O identificador da App Store para iOS. Observação: Pelo menos um dos seguintes é obrigatório: ios_app_store_identifier ou googleplay_app_id. Tipo: string Exemplo: 333903271
googleplay_deep_link opcional	Um deep link para o app Android que você está promovendo. Observação: Só pode ser usado se um googleplay_app_id tiver sido fornecido. Tipo: string
ios_deep_link opcional	Um deep link para o app iOS que você está promovendo. Observação: Só pode ser usado se um ios_app_store_identifier tiver sido fornecido. Tipo: string

​

Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards

{
  "name": "components criar cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALAR"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "components create cards",
    "components": [
      {
        "type": "MEDIA",
        "media_key": "3_1323490622599176192"
      },
      {
        "type": "BUTTON",
        "label": {
          "type": "ENUM",
          "value": "INSTALL",
        },
        "destination": {
          "type": "APP",
          "country_code": "US",
          "googleplay_app_id": "com.twitter.android"
        }
      }
    ],
    "created_at": "2020-11-11T05:42:25Z",
    "card_uri": "card://1326399865065238531",
    "id": "1321554298900107264",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false,
    "card_type": "IMAGE_APP"
  }
}

Atualize o item especificado associado à conta atual.

Solicitações de edição de Card aceitam apenas corpos de requisição POST em JSON. O Content-Type deve ser definido como application/json.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264

​

Parâmetros

O corpo de uma solicitação POST em JSON deve incluir os parâmetros que serão atualizados. A solicitação substituirá cada campo pelos parâmetros especificados no payload. Os componentes são representados como objetos e descrevem os atributos voltados ao anunciante do card.

O exemplo a seguir mostra a estrutura geral do payload (mas contém informações não funcionais).

{
  "name": "um nome",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "valor"
    }
  ]
}

Informações adicionais sobre componentes e slides em POST accounts/:account_id/cards.

Nome	Descrição
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
name optional	O nome do card. Tamanho máximo: 80 caracteres. Type: string Example: component based card
components optional	Descreve os componentes a serem usados para atualizar o card. Informações adicionais abaixo. Não pode ser especificado junto com slides. Observação: A ordem dos componentes é importante. Type: array of objects
slides optional	Use este array de arrays para atualizar Multi-Destination Carousels. Descreve cada card como um agrupamento de componentes. Cada slide deve ser uma representação completa de um card. Não pode ser especificado junto com components. Observação: A ordem de cada slide é importante. Type: array of array

​

Exemplo de solicitação

Este exemplo atualiza o nome e remove uma das media_keys do campo components do exemplo acima.

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

{
  "name": "nome alterado",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "3_1075096386931052545"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "ABRIR"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
      }
    }
  ]
}

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "nome alterado",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN",
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

Exclua o cartão especificado que pertence à conta atual.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id obrigatório	O id do card a ser deletado. Type: string Example: 1044294149527166979

​

Exemplo de requisição

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": true,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

​

Busca de Cards

Executar no Postman

Recupere vários cards, pelo card_uri, associados à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/all

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
card_uris obrigatório	Restrinja a resposta apenas às cards desejadas, especificando uma lista de identificadores separados por vírgula. É possível fornecer até 200 valores de URI de card. Tipo: string Exemplo: card://1044294149527166979,card://1044301099031658496
with_deleted opcional	Inclua resultados excluídos na sua solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496

​

Exemplo de resposta

{
  "request": {
    "params": {
      "card_uris": [
        "card://1044294149527166979",
        "card://1044301099031658496"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "name": "X App",
      "googleplay_app_id": "com.twitter.android",
      "image_display_height": "836",
      "country_code": "US",
      "id": "692xn",
      "wide_app_image": "https://pbs.twimg.com/media/Dc263l9VwAAAeEH.jpg",
      "created_at": "2018-09-24T18:35:01Z",
      "image_display_width": "1600",
      "card_uri": "card://1044294149527166979",
      "updated_at": "2018-09-24T18:35:01Z",
      "app_cta": "INSTALAR",
      "deleted": false,
      "card_type": "DOWNLOAD_DE_APP_COM_IMAGEM"
    },
    {
      "video_poster_height": "9",
      "name": "Plataforma do Desenvolvedor",
      "website_shortened_url": "https://t.co/zadeUSVD18",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/991374284135137280.vmap",
      "content_duration_seconds": "24",
      "video_owner_id": "756201191646691328",
      "video_content_id": "13_991374284135137280",
      "website_display_url": "developer.x.com",
      "id": "6933h",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/991374284135137280/pl/sQrBsE9mFvNep9Cx.m3u8?tag=2",
      "website_dest_url": "https://developer.x.com",
      "created_at": "2018-09-24T19:02:38Z",
      "card_uri": "card://1044301099031658496",
      "title": "Plataforma do Desenvolvedor",
      "website_url": "https://developer.x.com",
      "updated_at": "2018-09-24T19:02:38Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/991374284135137280/img/YbbGQHvWRjoFgrLz.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VÍDEO_NO_SITE"
    }
  ]
}

Recupere um cartão específico, pelo card_id, associado à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id

​

Parâmetros

Name	Description
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id obrigatório	Uma referência ao card com o qual você está operando na solicitação. Type: string Example: 508pf
with_deleted opcional	Inclui resultados excluídos na sua solicitação. Type: boolean Default: false Possible values: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf

​

Exemplo de resposta

{
  "request": {
    "params": {
      "card_id": "508pf",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "cartão de site de vídeo",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/867520357225418752.vmap",
    "content_duration_seconds": "21",
    "video_owner_id": "756201191646691328",
    "video_content_id": "13_867520357225418752",
    "website_display_url": "developer.x.com",
    "id": "508pf",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/867520357225418752/pl/TPHeH5ZlHFCa2TeJ.m3u8",
    "website_dest_url": "https://developer.x.com/en/docs/ads/creatives/api-reference/video-website#post-accounts-account-id-cards-video-website",
    "created_at": "2017-11-10T09:00:35Z",
    "card_uri": "card://928910245920829440",
    "title": "VWC",
    "website_url": "https://t.co/F81hp59pUF"
    "updated_at": "2018-01-05T05:43:31Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/867520357225418752/img/E3pnXM0sCKnRsFih.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_WEBSITE"
  }
}

​

Tweets em rascunho

Executar no Postman

​

GET accounts/:account_id/draft_tweets

Recupere detalhes de alguns ou de todos os Draft Tweets associados à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/draft_tweets

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta usada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count opcional	Especifica quantos registros tentar recuperar por solicitação. Type: int Default: 100 Min, Max: 1, 200
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: c-jh1g0ryb
user_id opcional	Especifica o usuário para o qual recuperar Draft Tweets. O padrão é o usuário promovível FULL da conta quando não definido. Type: string Example: 756201191646691328

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1

​

Exemplo de resposta

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name" null,
      "text": "Olá, mundo",
      "user_id": "756201191646691328",
      "id": "994791681219231744",
      "nullcast": true,
      "created_at": "2018-05-11T04:09:53Z",
      "card_uri": null,
      "updated_at": "2018-05-11T04:09:53Z",
      "media_keys": []
    }
  ],
  "next_cursor": "c-jh1g0ryb"
}

Recupere um Draft Tweet específico associado à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
draft_tweet_id obrigatório	Uma referência ao Draft Tweet com o qual você está trabalhando na solicitação. Tipo: string Exemplo: 994788364334325760

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760

​

Exemplo de resposta

{
  "request": {
    "params": {
      "draft_tweet_id": "994788364334325760"
    }
  },
  "data": {
    "name": null,
    "text": "#TwitterDev",
    "user_id": "756201191646691328",
    "id": "994788364334325760",
    "nullcast": true,
    "created_at": "2018-05-11T03:56:42Z",
    "card_uri": "card://958225772740714496",
    "updated_at": "2018-05-11T03:56:42Z",
    "media_keys": []
  }
}

​

POST accounts/:account_id/draft_tweets

Cria um Draft Tweet para o usuário totalmente promovível da conta (padrão) ou para o usuário especificado no parâmetro as_user_id.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/draft_tweets

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
as_user_id obrigatório	O ID de usuário do anunciante em nome de quem você está publicando o Tweet. O anunciante deve conceder acesso ao seu handle (ou handles) à conta de anúncios dele via ads.x.com. Essa permissão permite chamar a API usando os tokens OAuth do seu próprio handle em vez dos do anunciante. Tipo: string Exemplo: 756201191646691328
text às vezes obrigatório	O texto da sua atualização de status. Obrigatório se nenhum media_keys for especificado. Tipo: string Exemplo: Just setting up my X.
card_uri opcional	Associe um card ao Tweet usando o valor card_uri de qualquer resposta de cards, se disponível. Tipo: string Exemplo: card://960880280705392541
media_keys opcional	Associe mídia ao Tweet especificando uma lista de identificadores separados por vírgula. Inclua até 4 imagens, 1 GIF animado ou 1 vídeo. Observação: o recurso de mídia deve estar na Media Library da conta. Tipo: string Exemplo: 13_1153584529292270722
nullcast opcional	Indica se deve criar um Tweet “nullcasted” (ou “Promoted-only”). Tipo: boolean Padrão: true Valores possíveis: true, false
name opcional	O nome do Draft Tweet. Comprimento máximo: 80 caracteres. Tipo: string Exemplo: Tweet with name

​

Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.

​

Exemplo de resposta

{
  "request": {
    "params": {
      "text": "Só configurando meu X.",
      "as_user_id": "756201191646691328"
    }
  },
  "data": {
    "name": null,
    "text": "Só configurando meu X.",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:14:13Z",
    "media_keys": []
  }
}

Atualize o Draft Tweet especificado que pertence à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as requisições da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
draft_tweet_id obrigatório	Uma referência ao Draft Tweet com o qual você está operando na requisição. Type: string Example: 994747471329873920
card_uri opcional	Associe um card ao Tweet usando o valor card_uri de qualquer resposta de cards, se disponível. Observação: desfaça a definição (remova) especificando o parâmetro sem valor. Type: string Example: card://970582057284129151
media_keys opcional	Associe mídia ao Tweet especificando uma lista de identificadores separados por vírgula. Inclua até 4 imagens, 1 GIF animado ou 1 vídeo. Observação: o ativo de mídia deve estar na Media Library da conta. Observação: desfaça a definição (remova) especificando o parâmetro sem valor. Type: string Example: 13_1153584529292270722
nullcast opcional	Indica se deve criar um Tweet nullcasted (ou “Promoted-only”). Type: boolean Possible values: true, false
text opcional	O texto da sua atualização de status. Type: string Example: just setting up my twttr
name opcional	O nome do Draft Tweet. Tamanho máximo: 80 caracteres. Type: string Example: Tweet with name

​

Exemplo de requisição

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr

​

Exemplo de resposta

{
  "request": {
    "params": {
      "draft_tweet_id": 994747471329873920,
      "text": "só configurando meu twttr"
    }
  },
  "data": {
    "name": null,
    "text": "só configurando meu twttr",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:16:59Z",
    "media_keys": []
  }
}

Exclua permanentemente o Rascunho de Tweet especificado que pertence à conta atual.

Observação: Recomendamos fortemente excluir os rascunhos assim que um Tweet ou um Tweet Agendado for criado usando seus metadata.

Observação: Esta é uma exclusão definitiva. Como resultado, não é possível recuperar Rascunhos de Tweet excluídos.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
draft_tweet_id obrigatório	Uma referência ao Draft Tweet com o qual você está operando na solicitação. Type: string Example: 994787835663155200

​

Exemplo de requisição

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200

​

Exemplo de resposta

{
  "request": {
    "params": {
      "draft_tweet_id": "994787835663155200"
    }
  },
  "data": {
    "name": null,
    "text": "olá, mundo",
    "user_id": "756201191646691328",
    "id": "994787835663155200",
    "nullcast": true,
    "status": "DELETED",
    "created_at": "2018-05-11T03:54:36Z",
    "card_uri": null,
    "updated_at": "2018-05-11T04:07:31Z",
    "media_keys": []
  }
}

​

POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id

Visualize a prévia de um Draft Tweet em um dispositivo móvel.

Uma solicitação bem-sucedida envia uma notificação para cada dispositivo em que o usuário autenticado está conectado. Ao clicar na notificação, abre-se uma linha do tempo que permite ao usuário ver e interagir com o Draft Tweet, possibilitando testar reprodução automática, volume, tela cheia, ancoragem de video website card e outros comportamentos.

Observação: As prévias no dispositivo são visíveis apenas para o usuário que recebe a notificação.

Observação: As notificações são enviadas apenas para os apps oficiais do X.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Ads API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
draft_tweet_id obrigatório	Uma referência ao Draft Tweet com o qual você está operando na solicitação. Type: string Example: 996132315829948416

​

Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "draft_tweet_id": "996132315829948416"
    }
  },
  "message": "Confira as notificações de @apimctestface no X App para pré-visualizar seu Tweet."
}

​

Cartões de conversa com imagem

Executar no Postman

Observação: Para associar um cartão a um Tweet, use o parâmetro card_uri com um dos endpoints POST accounts/:account_id/tweet, POST statuses/update ou POST accounts/:account_id/scheduled_tweets.

​

GET accounts/:account_id/cards/image_conversation

Recupere detalhes de alguns ou de todos os cartões de conversa por imagem associados à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
card_ids opcional	Restrinja a resposta apenas às image conversation cards desejadas especificando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 IDs. Tipo: string Exemplo: 59woh
count opcional	Especifica o número de registros a tentar recuperar por solicitação. Tipo: int Padrão: 200 Mín., máx.: 1, 1000
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Tipo: string Exemplo: 8x7v00oow
q opcional	Uma query opcional para filtrar cards por name. Omita este parâmetro para recuperar todos. Comprimento máximo: 80 caracteres. Observação: realiza correspondência por prefixo sem diferenciar maiúsculas de minúsculas. Tipo: string Exemplo: night
sort_by opcional	Ordena por um atributo compatível em ordem crescente ou decrescente. Consulte Sorting para mais informações. Tipo: string Exemplo: created_at-asc
with_deleted opcional	Inclui resultados excluídos na solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false
with_total_count opcional	Inclui o atributo de resposta total_count. Observação: este parâmetro e cursor são mutuamente exclusivos. Observação: solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. Tipo: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh

​

Exemplo de resposta

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_ids": [
        "59woh"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "cartão de conversa com imagem",
      "first_cta": "#moon",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "obrigado",
      "id": "59woh",
      "first_cta_tweet": "estrelas",
      "media_key": "3_957113581522141184",
      "created_at": "2018-01-27T04:58:42Z",
      "image_display_width": "1280",
      "card_uri": "card://923498485702009837",
      "title": "Lua cheia"
      "updated_at": "2018-01-27T04:58:42Z",
      "deleted": false,
      "card_type": "IMAGE_CONVERSATION"
    }
  ]
}

Recupera um cartão de conversa com imagem específico associado à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta usada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id obrigatório	Uma referência ao image conversation card com o qual você está operando na solicitação. Type: string Example: 59woh
with_deleted opcional	Incluir resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh

​

Exemplo de resposta

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_id": "59woh",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "card de conversa com imagem",
    "first_cta": "#lua",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "obrigado",
    "id": "59woh",
    "first_cta_tweet": "estrelas",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Lua cheia"
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  }
}

​

POST accounts/:account_id/cards/image_conversation

Crie um novo card de conversa com imagem associado à conta especificada.

Veja Uploading Media para informações úteis sobre como enviar imagens para nossos endpoints.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation

​

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
first_cta required	A hashtag de Call-To-Action (CTA) para a primeira opção. Comprimento máximo: 20 caracteres (sem contar o #). Type: string Example: #ShareNow
first_cta_tweet required	O texto do Tweet a ser usado quando o primeiro CTA for clicado. Type: string Example: I Heart @AdsAPI
media_key required	A media key de uma imagem a ser usada neste card. Note: A imagem deve estar na Media Library da conta. Note: É necessária uma largura mínima de 800 px e uma proporção largura:altura de 1,91:1. Type: string Example: 3_1151345051104991073
name required	O nome do card. Type: string Example: image conversation card
thank_you_text required	O texto exibido após o clique no CTA. Comprimento máximo: 23 caracteres. Type: string Example: Thank you
second_cta sometimes required	A hashtag de Call-To-Action (CTA) para a segunda opção. Comprimento máximo: 20 caracteres (sem contar o #). Type: string Note: Obrigatório se title não estiver definido. Example: #ShareAgain
second_cta_tweet sometimes required	O texto do Tweet a ser usado quando o segundo CTA for clicado. Note: Obrigatório se second_cta estiver definido. Type: string Example: I Heart @AdsAPI Again
title sometimes required	O título do card, exibido abaixo da imagem e acima dos CTAs. Comprimento máximo: 23 caracteres. Type: string Note: Obrigatório se second_cta não estiver definido. Example: Start a conversation
third_cta optional	A hashtag de Call-To-Action (CTA) para a terceira opção. Comprimento máximo: 20 caracteres (sem contar o #). Type: string Example: #ShareMore
third_cta_tweet sometimes required	O texto do Tweet a ser usado quando o terceiro CTA for clicado. Type: string Note: Obrigatório se third_cta estiver definido. Example: I Heart @TwitterDev
fourth_cta optional	A hashtag de Call-To-Action (CTA) para a quarta opção. Comprimento máximo: 20 caracteres (sem contar o #). Type: string Example: #ShareExtra
fourth_cta_tweet sometimes required	O texto do Tweet a ser usado quando o quarto CTA for clicado. Type: string Note: Obrigatório se fourth_cta estiver definido. Example: I Heart @TwitterDev Again
unlocked_image_media_key optional	Um media_key de uma imagem que será usada no cenário de desbloqueio instantâneo. Este é um campo somente de escrita. Na resposta, a API fornecerá uma URL do X para essa imagem. Note: A imagem deve estar na Media Library da conta. Note: É necessária uma largura mínima de 800 px e uma proporção largura:altura de 5:2. Type: string Example: 3_883112887618682880
thank_you_url optional	A URL a ser exibida com o texto de agradecimento. Type: string Example: https://example.com/thankyou

​

Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon

​

Exemplo de resposta

{
  "data": {
    "name": "cartão de conversa com imagem",
    "first_cta": "#lua",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "obrigado",
    "id": "59woh",
    "first_cta_tweet": "estrelas",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Lua cheia",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "name": "cartão de conversa com imagem",
      "first_cta": "#lua",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "obrigado",
      "media_key": "3_957113581522141184",
      "account_id": "18ce54d4x5t",
      "first_cta_tweet": "estrelas",
      "image_display_width": "1280",
      "title": "Lua cheia"
      "card_type": "IMAGE_CONVERSATION"
    }
  }
}

Atualiza o cartão de conversa com imagem especificado, pertencente à conta atual.

Consulte Uploading Media para informações úteis sobre como fazer upload de imagens para nossos endpoints.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parâmetros

Name	Description
account_id required	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id required	Uma referência ao image conversation card com o qual você está operando na solicitação. Type: string Example: 4i0qg
first_cta optional	A hashtag de Call-To-Action (CTA) para a primeira opção. Comprimento máximo: 20 caracteres (sem contar o #). Type: string Example: #ShareNow
first_cta_tweet optional	O texto do Tweet a ser usado quando a primeira CTA for clicada. Type: string Example: I Heart @AdsAPI
second_cta optional	A hashtag de Call-To-Action (CTA) para a segunda opção. Comprimento máximo: 20 caracteres (sem contar o #). Type: string Observação: Obrigatório se title não estiver definido. Example: #ShareAgain
second_cta_tweet optional	O texto do Tweet a ser usado quando a segunda CTA for clicada. Observação: Obrigatório se second_cta estiver definido. Type: string Example: I Heart @AdsAPI Again
third_cta optional	A hashtag de Call-To-Action (CTA) para a terceira opção. Comprimento máximo: 20 caracteres (sem contar o #). Type: string Example: #ShareMore
third_cta_tweet optional	O texto do Tweet a ser usado quando a terceira CTA for clicada. Type: string Observação: Obrigatório se third_cta estiver definido. Example: I Heart @TwitterDev
fourth_cta optional	A hashtag de Call-To-Action (CTA) para a quarta opção. Comprimento máximo: 20 caracteres (sem contar o #). Type: string Example: #ShareExtra
fourth_cta_tweet optional	O texto do Tweet a ser usado quando a quarta CTA for clicada. Type: string Observação: Obrigatório se fourth_cta estiver definido. Example: I Heart @TwitterDev Again
media_key optional	A media key de uma imagem a ser usada neste card. Observação: A imagem deve estar na Media Library da conta. Observação: É necessária uma largura mínima de 800px e uma proporção largura:altura de 1,91:1. Type: string Example: 3_1151345051104991073
name optional	O nome do card. Type: string Example: moon card
thank_you_text optional	O texto a ser exibido após a CTA ser clicada. Comprimento máximo: 23 caracteres. Type: string Example: Thank you
thank_you_url optional	A URL a ser exibida com o texto de agradecimento. Type: string Example: https://example.com/thankyou
title optional	O título do card, que aparece abaixo da imagem e acima das CTAs. Comprimento máximo: 23 caracteres. Type: string Observação: Obrigatório se second_cta não estiver definido. Example: Start a conversation
unlocked_image_media_key optional	Um media_key de uma imagem que será usada no cenário de desbloqueio instantâneo. Este é um campo somente de escrita. Na resposta, a API fornecerá uma URL da X para essa imagem. Observação: A imagem deve estar na Media Library da conta. Observação: É necessária uma largura mínima de 800px e uma proporção largura:altura de 5:2. Type: string Example: 3_883112887618682880

​

Exemplo de requisição

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card

​

Exemplo de resposta

{
  "data": {
    "name": "Moon Card",
    "id": "59woh",
    "created_at": "2018-01-27T04:58:42Z",
    "card_uri": "card://923498485702009837",
    "updated_at": "2018-01-29T21:04:39Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION",
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "IMAGE_CONVERSATION",
      "card_id": "59woh",
      "name": "Moon Card"
    }
  }
}

Excluir permanentemente o cartão de conversa com imagem especificado que pertence à conta atual.

Observação: Trata-se de um DELETE definitivo. Portanto, não é possível recuperar cartões excluídos.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id required	Uma referência ao Image Conversation Card usado na solicitação. Type: string Example: 4i0qe

​

Exemplo de requisição

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe

​

Exemplo de resposta

{
  "data": {
    "name": "cartão de conversa com imagem",
    "id": "4i0qe",
    "created_at": "2017-07-07T00:03:01Z",
    "updated_at": "2017-08-23T13:26:23Z",
    "deleted": true,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0qe",
      "card_type": "image_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

Biblioteca de Mídia

Executar no Postman

​

GET accounts/:account_id/media_library

Recupera detalhes de alguns ou de todos os objetos da biblioteca de mídia associados à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/media_library

​

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
count optional	Especifica a quantidade de registros a tentar recuperar por solicitação. Type: int Default: 20 Min, Max: 1, 50
cursor optional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Example: c-1
media_type optional	Restringe a resposta apenas ao tipo de mídia desejado. Type: enum Possible values: GIF, IMAGE, VIDEO
q optional	Uma query opcional para restringir o recurso pelos fields name, title, file_name e description. Note: Isso realiza correspondência de termos sem diferenciar maiúsculas de minúsculas. Type: string Min, Max length: 1, 255

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "count": 1
    }
  },
  "data": [
    {
      "tweeted": true,
      "name": null,
      "file_name": "coffee https://t.co/4tcPU9XUon",
      "media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
      "media_category": "TWEET_IMAGE",
      "media_key": "3_908573900237180928",
      "created_at": "2017-09-15T06:11:12Z",
      "media_status": "TRANSCODE_COMPLETED",
      "media_type": "IMAGE"
      "updated_at": "2017-11-16T06:00:01Z",
      "deleted": false
    }
  ],
  "next_cursor": "c-1"
}

Recupere um objeto específico da biblioteca de mídia associado à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

Parâmetros

Nome	Descrição
account_id required	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
media_key required	Uma referência ao objeto da biblioteca de mídias usado na solicitação. Tipo: string Exemplo: 13_909110614026444802

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "13_909110614026444802"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 39973,
    "name": null,
    "file_name": "buildings https://t.co/xFdzrHM5QG",
    "description": null,
    "media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
    "media_category": "AMPLIFY_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
    "poster_media_key": "3_909110614026444802",
    "media_key": "13_909110614026444802",
    "created_at": "2017-09-16T17:43:55Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "buildings",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-09-27T13:04:00Z",
    "deleted": false
  }
}

Associe um objeto de mídia à conta atual. Para mais detalhes, consulte nosso guia da Media Library.

Observação: Ao adicionar um vídeo com a categoria de mídia AMPLIFY_VIDEO à Media Library, ele passa a ficar automaticamente disponível como um ativo PREROLL de account_media.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/media_library

​

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
media_key required	O media_key do conteúdo enviado. Um media_key é retornado na resposta de POST media/upload quando um media_category é especificado. Type: string Example: 3_931236738554519552
description optional	A descrição que aparece abaixo do vídeo quando publicado em um Tweet. Comprimento máximo: 200 caracteres. Isso não é exibido no Tweet por padrão. Para exibir a description do vídeo, use o parâmetro video_description com o endpoint POST accounts/:account_id/tweet. Observação: Só pode ser usado com vídeos. Type: string Example: This is the description under the video.
file_name optional	O nome do arquivo do objeto da biblioteca de mídia. Comprimento máximo: 255. O nome do arquivo pode ser visto nos detalhes de mídia de cada ativo na interface da Media Library em ads.x.com. Ficará vazio quando file_name não estiver definido. Type: string Example: coffee.jpeg
name optional	O nome do objeto da biblioteca de mídia. Comprimento máximo: 100. Este é o rótulo abaixo de cada ativo de mídia na interface da Media Library em ads.x.com. O rótulo será “Untitled” quando name não estiver definido. Type: string Example: Latte
poster_media_key optional	Especifique uma imagem de pôster para o vídeo usando o media_key de uma imagem enviada. Se não for especificado, o primeiro quadro será usado. Observação: Só pode ser usado com vídeos. Type: string Example: 3_890599134483242005
title optional	O título (headline) que aparece abaixo do vídeo quando publicado em um Tweet. Comprimento máximo: 70 caracteres. Isso não é exibido no Tweet por padrão. Para exibir o title do vídeo, use o parâmetro video_title com o endpoint POST accounts/:account_id/tweet. Observação: Só pode ser usado com vídeos. Type: string Example: Video title

​

Exemplo de solicitação

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "3_931236738554519552"
    }
  },
  "data": {
    "tweeted": false,
    "name": null,
    "file_name": null,
    "media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
    "media_category": "TWEET_IMAGE",
    "media_key": "3_931236738554519552",
    "created_at": "2017-11-16T19:05:14Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_type": "IMAGE",
    "updated_at": "2017-11-16T19:05:23Z",
    "deleted": false
  }
}

Atualize o objeto da biblioteca de mídia especificado que pertence à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
media_key obrigatório	Uma referência ao objeto da biblioteca de mídia que você está usando na solicitação. Type: string Example: 16_844800354743074820
description opcional	A descrição que aparece abaixo do vídeo quando o Tweet é publicado. Comprimento máximo: 200 caracteres. Isso não é exibido no Tweet por padrão. Para mostrar o description do vídeo, use o parâmetro video_description com o endpoint POST accounts/:account_id/tweet. Observação: somente para vídeos. Type: string Example: This is the description under the video.
file_name opcional	O nome de arquivo do objeto na biblioteca de mídia. Comprimento máximo: 255. O nome de arquivo pode ser visto nos detalhes de mídia de cada ativo na interface da Media Library em ads.x.com. Este campo ficará vazio quando file_name não estiver definido. Type: string Example: coffee.jpeg
name opcional	O nome do objeto na biblioteca de mídia. Comprimento máximo: 100. Este é o rótulo exibido sob cada ativo na interface da Media Library em ads.x.com. O rótulo será “Untitled” quando name não estiver definido. Type: string Example: Latte
poster_media_key opcional	Especifique uma imagem de pôster para o vídeo usando o media_key de uma imagem enviada. Observação: somente para vídeos. Type: string Example: 3_885003359340375465
title opcional	O título (headline) que aparece abaixo do vídeo quando o Tweet é publicado. Comprimento máximo: 70 caracteres. Isso não é exibido no Tweet por padrão. Para mostrar o title do vídeo, use o parâmetro video_title com o endpoint POST accounts/:account_id/tweet. Observação: somente para vídeos. Type: string Example: Video title

​

Exemplo de requisição

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "16_844800354743074820",
      "title": "GIF de gato",
      "description": "no espaço",
    }
  },
  "data": {
    "tweeted": true,
    "duration": null,
    "name": null,
    "file_name": null,
    "description": "no espaço",
    "media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4",
    "media_category": "TWEET_GIF",
    "poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg",
    "poster_media_key": "3_844800354743074820",
    "media_key": "16_844800354743074820",
    "created_at": "2017-10-20T09:51:54Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "GIF de gato"
    "media_type": "GIF",
    "aspect_ratio": "125:79",
    "updated_at": "2017-10-23T06:37:56Z",
    "deleted": false
  }
}

Exclui o objeto especificado da biblioteca de mídia pertencente à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
media_key obrigatório	Uma referência ao objeto da biblioteca de mídia com o qual você está operando na solicitação. Tipo: string Exemplo: 7_860318603387600896

​

Exemplo de requisição

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "7_860318603387600896"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 14330,
    "name": "mountains-on-ads.x.com",
    "file_name": "mountains.mp4",
    "description": "",
    "media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4",
    "media_category": "TWEET_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg",
    "poster_media_key": "3_860318839740915712",
    "media_key": "7_860318603387600896",
    "created_at": "2017-05-05T02:21:53Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "carregado em ads.x.com",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-05-05T02:26:58Z",
    "deleted": true
  }
}

​

Cartões de Enquete

Executar no Postman

​

GET accounts/:account_id/cards/poll

Recupere detalhes de alguns ou de todos os cartões de enquete associados à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/poll

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
card_ids opcional	Limite a resposta apenas aos poll cards desejados especificando uma lista de identificadores separados por vírgulas. Até 200 IDs podem ser fornecidos. Tipo: string Exemplo: 57i77
count opcional	Especifica quantos registros tentar recuperar por solicitação. Tipo: int Padrão: 200 Mín., máx.: 1, 1000
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Tipo: string Exemplo: 8x7v00oow
q opcional	Uma query opcional para filtrar cards por name. Omita este parâmetro para recuperar todos. Comprimento máximo: 80 caracteres. Observação: Realiza correspondência de prefixo sem diferenciar maiúsculas de minúsculas. Tipo: string Exemplo: night
sort_by opcional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Tipo: string Exemplo: created_at-asc
with_deleted opcional	Inclui resultados excluídos na sua solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false
with_total_count opcional	Inclui o atributo de resposta total_count. Observação: Este parâmetro e cursor são mutuamente exclusivos. Observação: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos. Tipo: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77

​

Exemplo de resposta

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_ids": [
        "57i77"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_poster_height": "9",
      "name": "enquete melhor costa",
      "start_time": "2018-01-09T04:51:34Z",
      "first_choice": "Leste",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
      "content_duration_seconds": "8",
      "second_choice": "Oeste",
      "end_time": "2018-01-16T04:51:34Z",
      "id": "57i77",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
      "created_at": "2018-01-09T04:51:34Z",
      "duration_in_minutes": "10080",
      "card_uri": "card://950590850777497601",
      "updated_at": "2018-01-09T04:51:34Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_POLLS"
    }
  ]
}

Recupere um card de enquete específico associado à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Ads API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
card_id obrigatório	Referência ao poll card utilizado na solicitação. Tipo: string Exemplo: 57i8t
with_deleted opcional	Inclui resultados excluídos na solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t

​

Exemplo de resposta

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_id": "57i8t",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "enquete apenas de texto",
    "start_time": "2018-01-09T05:03:05Z",
    "first_choice": "Manhã",
    "second_choice": "Noite"
    "end_time": "2018-01-11T05:03:05Z",
    "id": "57i8t",
    "created_at": "2018-01-09T05:03:05Z",
    "duration_in_minutes": "2880",
    "card_uri": "card://950593749658189824",
    "updated_at": "2018-01-09T05:03:05Z",
    "deleted": false,
    "card_type": "TEXT_POLLS"
  }
}

​

POST accounts/:account_id/cards/poll

Crie um novo cartão de enquete associado à conta especificada. Este endpoint oferece suporte à criação de cartões de enquete com imagem, com vídeo ou sem mídia. Enquetes com mídia são chamadas de Media Forward Polls.

Observação: O produto Media Forward Polls está em beta e requer o recurso de conta PROMOTED_MEDIA_POLLS.

Observação: Não é possível atualizar (PUT) cartões de enquete.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/poll

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
duration_in_minutes obrigatório	O tempo (em minutos) que a enquete permanecerá aberta. Após o duration_in_minutes especificado, a enquete será encerrada e votos não serão mais aceitos. Isso corresponde a end_time na resposta. Observação: Isso começa assim que o card é criado, e não quando ele é adicionado a um Tweet. Type: int Min, Max: 5, 10080
first_choice obrigatório	A primeira opção da enquete. Comprimento máximo: 25 caracteres. Type: string Example: One
name obrigatório	O nome do card. Type: string Example: poll card
second_choice obrigatório	A segunda opção da enquete. Comprimento máximo: 25 caracteres. Type: string Example: Two
fourth_choice opcional	A quarta opção da enquete. Comprimento máximo: 25 caracteres. Observação: As opções primeira, segunda e terceira devem ser definidas ao usar este parâmetro. Type: string Example: Four
media_key opcional	O media_key de uma imagem ou vídeo da biblioteca de mídia que será usado neste card. Este é um campo somente de escrita. Na resposta, a API fornecerá uma URL do X para essa mídia. Observação: A imagem ou o vídeo deve estar na biblioteca de mídia da conta. Observação: É necessária uma largura mínima de 800 px e uma proporção largura:altura de 1,91:1.
third_choice opcional	A terceira opção da enquete. Comprimento máximo: 25 caracteres. Observação: As opções primeira e segunda devem ser definidas ao usar este parâmetro. Type: string Example: Three

​

Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll

​

Exemplo de resposta

{
  "request": {
    "params": {
      "first_choice": "Leste",
      "name": "enquete da melhor costa",
      "second_choice": "Oeste",
      "media_key": "13_950589518557540353",
      "duration_in_minutes": 10080
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "enquete da melhor costa",
    "start_time": "2018-01-09T04:51:34Z",
    "first_choice": "Leste",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
    "content_duration_seconds": "8",
    "second_choice": "Oeste",
    "end_time": "2018-01-16T04:51:34Z",
    "id": "57i77",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
    "created_at": "2018-01-09T04:51:34Z",
    "duration_in_minutes": "10080",
    "card_uri": "card://950590850777497601",
    "updated_at": "2018-01-09T04:51:34Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_POLLS"
  }
}

Exclua permanentemente o card de enquete especificado pertencente à conta atual.

Observação: Trata-se de um hard delete. Como resultado, não é possível recuperar cards excluídos.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id

​

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id required	Uma referência ao poll card com o qual você está operando na solicitação. Type: string Example: 57i9t

​

Exemplo de requisição

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t

​

Exemplo de resposta

{
  "data": {
    "name": "enquete com imagem",
    "start_time": "2018-01-09T05:10:51Z",
    "id": "57i9t",
    "created_at": "2018-01-09T05:10:51Z",
    "updated_at": "2018-01-09T05:11:04Z",
    "deleted": true,
    "card_type": "IMAGE_POLLS"
  },
  "request": {
    "params": {
      "card_id": "57i9t",
      "card_type": "poll"
      "account_id": "18ce54d4x5t"
    }
  }
}

​

Chamadas à ação de pré‑roll

Executar no Postman

​

GET accounts/:account_id/preroll_call_to_actions

Recupere detalhes de algumas ou todas as chamadas para ação (CTAs) de preroll associadas a itens de linha da conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
line_item_ids opcional	Limite a resposta apenas aos CTAs de preroll associados aos line items especificados, informando uma lista de identificadores separados por vírgulas. Podem ser fornecidos até 200 IDs. Tipo: string Exemplo: 8v53k
count opcional	Especifica a quantidade de registros a tentar recuperar por solicitação. Tipo: int Padrão: 200 Mín., máx.: 1, 1000
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Tipo: string Exemplo: 8x7v00oow
preroll_call_to_action_ids opcional	Limite a resposta apenas aos CTAs de preroll desejados, informando uma lista de identificadores separados por vírgulas. Podem ser fornecidos até 200 IDs. Tipo: string Exemplo: 8f0
sort_by opcional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Tipo: string Exemplo: created_at-asc
with_deleted opcional	Inclua resultados excluídos na sua solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false
with_total_count opcional	Inclua o atributo de resposta total_count. Observação: este parâmetro e cursor são mutuamente exclusivos. Observação: solicitações que incluem total_count terão limites de requisições menores, atualmente definidos como 200 por 15 minutos. Tipo: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k

​

Exemplo de resposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_ids": [
        "8v53k"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8v53k",
      "call_to_action_url": "https://www.x.com",
      "call_to_action": "VISIT_SITE",
      "id": "8f0",
      "created_at": "2017-07-07T19:28:40Z",
      "updated_at": "2017-07-07T19:28:40Z",
      "deleted": false
    }
  ]
}

Recupere uma chamada para ação (CTA) específica associada a esta conta.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Exemplo: 18ce54d4x5t
preroll_call_to_action_id obrigatório	Referência ao call to action do preroll com o qual você está operando na solicitação. Type: string Exemplo: 8f0
with_deleted opcional	Incluir resultados excluídos na solicitação. Type: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

​

Exemplo de resposta

{
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  }
}

​

POST accounts/:account_id/preroll_call_to_actions

Define a Call-to-Action (CTA) opcional para um line item PREROLL_VIEWS.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Exemplo: 18ce54d4x5t
call_to_action obrigatório	O texto do CTA do botão exibido no anúncio. Type: enum Valores possíveis: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url obrigatório	A URL para a qual o usuário será redirecionado quando o botão de CTA for clicado. Type: string Exemplo: https://www.x.com
line_item_id obrigatório	Uma referência ao item de linha com o qual você está operando na solicitação. Type: string Exemplo: 8v53k

​

Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.x.com

​

Exemplo de resposta

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "8v53k",
      "call_to_action": "VISIT_SITE",
      "call_to_action_url": "https://www.x.com",
      "account_id": "18ce54d4x5t"
    }
  }
}

Atualize a Call-to-Action (CTA) opcional de um item de linha PREROLL_VIEWS.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id obrigatório	Uma referência ao CTA de preroll com o qual você está trabalhando na solicitação. Type: string Example: 8f0
call_to_action opcional	O texto do CTA para o botão exibido no anúncio. Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url opcional	A URL para a qual o usuário será redirecionado quando o botão de CTA for clicado. Type: string Example: https://www.x.com

​

Exemplo de requisição

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW

​

Exemplo de resposta

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "WATCH_NOW",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-09-09T05:51:26Z",
    "deleted": false
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "call_to_action": "WATCH_NOW",
      "account_id": "18ce54d4x5t"
    }
  }
}

Exclua a Chamada para ação (CTA) de preroll especificada que pertence à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as requisições da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
preroll_call_to_action_id obrigatório	Referência ao CTA de preroll utilizado na requisição. Tipo: string Exemplo: 8f0

​

Exemplo de requisição

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

​

Exemplo de resposta

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-08-30T06:08:21Z",
    "deleted": true
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

Tweets programados

Executar no Postman

​

GET accounts/:account_id/scheduled_tweets

Recupera detalhes de alguns ou de todos os Tweets agendados associados à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Exemplo: 18ce54d4x5t
count opcional	Especifica a quantidade de registros a tentar recuperar por solicitação. Type: int Padrão: 100 Mín., Máx.: 1, 200
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Exemplo: c-j3cn6n40
user_id opcional	Especifica o usuário para o qual recuperar Scheduled Tweets. Por padrão, usa o usuário promovível FULL da conta quando não definido. Type: long Exemplo: 756201191646691328

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1

​

Exemplo de resposta

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name": "nome de teste",
      "completed_at": "2017-06-18T22:00:05Z",
      "text": "onde você quer estar",
      "user_id": "756201191646691328",
      "scheduled_status": "SUCCESS",
      "id": "875828692081037312",
      "nullcast": true,
      "created_at": "2017-06-16T21:33:27Z",
      "scheduled_at": "2017-06-18T22:00:00Z",
      "card_uri": null,
      "updated_at": "2017-06-19T18:02:20Z",
      "tweet_id": "876560168963645440",
      "media_keys": []
    }
  ],
  "next_cursor": "c-j41uw400"
}

Recupere um Tweet agendado específico associado à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
scheduled_tweet_id obrigatório	Uma referência ao Scheduled Tweet utilizado na solicitação. Type: string Example: 917438609065623552

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552

​

Exemplo de resposta

{
  "request": {
    "params": {
      "scheduled_tweet_id": "917438609065623552"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

​

POST accounts/:account_id/scheduled_tweets

Crie um Tweet agendado para o usuário totalmente promovível da conta (padrão) ou para o usuário especificado no parâmetro as_user_id.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
scheduled_at obrigatório	O horário, expresso em ISO 8601, em que o Tweet deve ser publicado (ou ir ao ar). Observação: Tweets só podem ser agendados com até um ano de antecedência. Observação: Tweets devem ser agendados apenas com granularidade de minuto; os segundos serão ignorados. Tipo: string Exemplo: 2017-12-31T23:59:00Z
as_user_id obrigatório	O ID de usuário do anunciante em nome de quem você está publicando o Tweet. O anunciante deve conceder à sua conta (ou contas) acesso à conta de anúncios dele via ads.x.com. Essa permissão permite que você chame a API usando os tokens OAuth da sua própria conta, em vez dos do anunciante. Tipo: long Exemplo: 756201191646691328
text às vezes obrigatório	O texto da sua atualização de status. Obrigatório se nenhum media_keys for especificado. Tipo: string Exemplo: just setting up my twttr
card_uri opcional	Associe um card ao Tweet usando o valor card_uri de qualquer resposta de cards, se disponível. Tipo: string Exemplo: card://855591459410511943
media_keys opcional	Associe mídia ao Tweet especificando uma lista de identificadores separada por vírgulas. Inclua até 4 imagens, 1 GIF animado ou 1 vídeo. Observação: o ativo de mídia deve estar na Media Library da conta. Tipo: string Exemplo: 13_1153584529292270722
nullcast opcional	Indica se um Tweet nullcast (ou “Promoted-only”) deve ser criado. Tipo: boolean Padrão: true Valores possíveis: true, false
name opcional	O nome do Scheduled Tweet. Comprimento máximo: 80 caracteres. Tipo: string Exemplo: Tweet with name

​

Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01

​

Exemplo de resposta

{
  "request": {
    "params": {
      "media_keys": [
        "3_917438348871983104"
      ],
      "scheduled_at": "2018-01-01T00:00:00Z",
      "as_user_id": 756201191646691328
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

Atualize o Tweet agendado especificado que pertence à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

Parâmetros

Nome	Descrição
account_id required	O identificador da conta em uso. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	Referência ao Scheduled Tweet com o qual você está operando na solicitação. Type: string Example: 870321875435442177
card_uri optional	Associe um card ao Tweet usando o valor card_uri de qualquer resposta de cards, se disponível. Observação: remova especificando o parâmetro sem valor. Type: string Example: card://875146925316386347
media_keys optional	Associe mídia ao Tweet especificando uma lista de identificadores separados por vírgulas. Inclua até 4 imagens, 1 GIF animado ou 1 vídeo. Observação: o ativo de mídia deve estar na Media Library da conta. Observação: remova especificando o parâmetro sem valor. Type: string Example: 13_1153584529292270722
nullcast optional	Define se o Tweet será nullcasted (ou “Promoted-only”). Type: boolean Possible values: true, false
scheduled_at optional	A data e hora, em ISO 8601, em que o Tweet deve ser publicado (ou ficar disponível). Type: string Example: 2017-12-31T23:59:59Z
text optional	O texto da atualização de status. Type: string Example: just setting up my twttr
name optional	O nome do Scheduled Tweet. Comprimento máximo: 80 caracteres. Type: string Example: Tweet with name

​

Exemplo de requisição

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice

​

Exemplo de resposta

{
  "request": {
    "params": {
      "scheduled_tweet_id": "875057751231037440",
      "text": "solstício de inverno"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "SCHEDULED",
    "text": "solstício de inverno",
    "user_id": "756201191646691328",
    "id": "875057751231037440",
    "nullcast": true,
    "created_at": "2017-06-14T18:30:00Z",
    "scheduled_at": "2017-12-21T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T18:30:00Z",
    "tweet_id": null,
    "media_keys": []
  }
}

Exclua permanentemente o Tweet agendado especificado que pertence à conta atual.

Observação: Esta é uma exclusão permanente (hard delete). Como resultado, não é possível recuperar Tweets agendados que tenham sido excluídos.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta de anunciante. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
scheduled_tweet_id obrigatório	Uma referência ao Scheduled Tweet com o qual você está operando na solicitação. Type: string Example: 870321875435442177

​

Exemplo de requisição

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776

​

Exemplo de resposta

{
  "request": {
    "params": {
      "scheduled_tweet_id": 875064008595787776
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "DELETED",
    "text": "olá, mundo",
    "user_id": "756201191646691328",
    "id": "875064008595787776",
    "nullcast": true,
    "created_at": "2017-06-14T18:54:52Z",
    "scheduled_at": "2017-06-15T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T19:01:16Z",
    "tweet_id": null,
    "media_keys": []
  }
}

​

Prévias de Tweet

Executar no Postman

​

GET accounts/:account_id/tweet_previews

Pré-visualize Tweets publicados, agendados ou em rascunho.

• Suporta a pré-visualização de múltiplos Tweets — até 200 — em uma única solicitação à API
• Renderização precisa e atualizada do layout e do estilo do Tweet
• Suporta todos os formatos e tipos de cartão mais recentes
• Retorna um iframe

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/tweet_previews

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
tweet_ids obrigatório	Uma lista de identificadores separados por vírgulas. É possível informar até 200 IDs. Observação: os IDs devem corresponder ao tweet_type especificado. Por exemplo, se for enviado o ID de um Scheduled Tweet e tweet_type=PUBLISHED for especificado, a prévia para esse ID não será retornada. Tipo: long Exemplo: 1122911801354510336,1102836745790316550
tweet_type obrigatório	O tipo de Tweet para os tweet_ids especificados. Tipo: enum Valores possíveis: DRAFT, PUBLISHED, SCHEDULED

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED

​

Exemplo de resposta

{
  "request": {
    "params": {
      "tweet_ids": [
        "1122911801354510336",
        "1102836745790316550"
      ],
      "tweet_type": "PUBLISHED",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "tweet_id": "1122911801354510336",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAANVYW2%2FbNhT%2BKwJf59iiZDuSgWLI0suyrUXbZBuGaiAoibbZUKRGUk7TIP99h6Jsy4mdC5CX%2BiUiz%2F0cfueQuUH2ijGLZsENKjSjlpWEwhK9VzI4qXUQpQE%2BnuF4FofBTyH8gijEKRogXqIZxlGUYpyEOJ6MJziM46kjEGM1qNhDBbl5IwSx7JszsuIlU8EVyw23DGhWN7JwPqDZnArDBqjkphb0uhUgmsoFQ7Mv4QDH%2Fw4Qk5Zbzgya3aAlNUtLF%2FD9BSjmusqV6BaNYZpUjlnJ9Zb2xFtgVY0uQCnKmjCMCxosNZu%2FytDS2trMslE2oqU5ojUf2ituLdPDQlUZCjQTwCXVXAmhrjIvzi48T3BSmuBUVbUC214x6PEsLnWSaFYLiEpBqqhtDHHZlJCZA0Sf0fsMbWz7ZTvSIUkD1WaSSFqxNdlJuFw6fceTKdQZp3g6nk5THEdJr7D3iRCU14ROPp4F74sLZuycFi7YHUMIElkVdksVCuoNhQHSOZXBWyhxwU2hBsHpCWoLtfauZKCJ1x3zmbQqcHq4XARUlgHYNSBQa2VZ0T9BvkBMG1KoRsKpO8KwqTmT5c6W4MYd%2Fm7H29xBxMWyCX5rRBDhACezyXQWJVtEtCebruAwwUne0dvYgqj53LCNVssrRr4ruUn8ginCJM1Fz%2B0V03zOexv%2BLOzqFgAI8IxJsF4oaTXPG6sg1LvauCEWUmsEBfK%2BXcjqPSHI5ZwLRnJaXC40WHXZEU4ehe0P7eXhFV0w0lauRZEHUW4cgKpFC59Ry2OykV2yavMXZ6N8MawhpIf1khabnXbzUuotrO%2BFvjeWetfYDi8YA3TE4yTGx%2BNJMgnTJJpko9cXvxefT%2BtzIpWuqBh%2BrftePBTZixvLqZTQGbYxPWjHc3tDdzCfjfAYvqbROMY9%2FYLLy8PnxEDHz6kmudIlePEoHyzEYa52KhykAlrunZ%2FtYGFz2ghLOuZD%2B3ekfDPhDnUeun4D2up%2FDTQjYti2eUhlAcG%2BvZkN9jcoJPa6dh1RukZw2zaBTdtRkB0uofVs5GAIFmxL30J9vadZO8jX3SH07ch1oz1bW4x3Yn3UK2N4DkMCYoGxzFfb6KEv137cbppqRwP%2FC6pLR%2BoafTRJpnEaHuPpDFJZKdLOerKd9f4AOqn2%2FOFwPI5DHKZpGOPpJBmnrqU6cpuouxh0hCNHOALCETdHJas1a%2B8OQy5XVMAQG6CcS8jjgsC68Y539olZKm2ZhN7eKr5BXTXOLz6ffXjnxhZkeC25AxQLAMlG32nJ%2Fjz%2F6zVOXO1cQaDypGy0b6WGwVZpnqA4GjsF7o4DcLjipV0%2BQQjGzVZobZyXT5GMSQroPR5HyRiuZfAVJWFP2ZLxxdI%2BQVHqhFZUcnv9xBSWbMUEHCDdv0k5LeualA5Bzy3HQa1dQOpKdlekR5Xuudb0EiPMs31rj3y%2Fq9KqFnx%2B7bGQje5XAhqvyEbmk%2F7FvEmrt6sPrE5Pvw2ruEl%2Bhuvtq8h5BLde17AedeT1OjXBR%2Bg4cxgG%2FWy%2FdKJBkNHqxXO0qmi9L1NDR%2BiZ9zPUwLzr2z97f%2FLujbtxt9TO%2Bg16ZPjtuEDssqny%2FcUCiWz0T56%2F%2B%2FTr6u%2FPX9Xbhf7jezdvOyxjYBygNayOI1hQ0c2I2zvu%2F7COE0H1j%2Bz%2Btx8wgHY0Pnt49aDbPs14zsglu%2B4mcatvo7xedw2w0P%2BGTsAL1pv18No9qTlqHy3Gv89w7LBJmxLeWTu8cBkom6J9xcF8bopLtonJGd6%2BaG4HAWpvDv5VJv2%2FDIKbzSYsrG7Y7e3%2FCm%2FIC8QQAAA%3D'>"
    },
    {
      "tweet_id": "1102836745790316550",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAO1YbW%2FbNhD%2BK4K%2Bzo3eZdlAMQQttqZrt6FNEXRVIVASJTOhSIWkHDeB%2F%2FuOomXLb%2BuHdQWGzV8s3T13vCOPz539ZKsHjJU9t57sQmCkcJkheLWvO2y9RcJyI8udzkN%2F7ofWDy58LN%2F1ZvbEJqU99zzXT4J4GkbTmRt4cRS5WpFJJcDFCS3YVR2lmcIrvcgNWmJpLZRq5Tx1UkddFDx16mUU8Lv4UhQAV6JjhQ7LnleISjyxSyJbir70PjKBWI3t%2BSd3En2e2JgpogiW9vzJXiC5UKiG50%2BgkV%2BanNPNSyexyBoN5mwQiUHZ4JIgeHwyGbpumLjh1PcDfxZ6XpSE4wyPtXpnWEkKHcSneOLPBpcZLAEmOtk%2B1zaXF%2BqBNDXk3KSOTkY9ZEtSYp6pRdfkqXPCPdh1qQNWYPFz%2BfHls7v7y6s3dZm%2Fci9u29oeLZb1%2B7pZUv6ja%2B5SO3uOw6kZaEsKHYhSWJhQ9rB41SJWQiUe%2BR2boJY0hcJSVajAqSMVUp2EBI6rLnX6FEGnC%2BpLi3UEC644vEryaOqlz18%2FPMCp6zpebL4F1hgwKQRv7bXZ4a4ZoL5rsPE0GmErojRUNojSDTJODDBIgmMgRULX8cblBjn13UMkQCu4pZ3og16vP6%2F1dincb9e4%2FP8v4%2F9EGfeSf2UZm%2BMirOIaj2SLC03nwMlQcV480RVXdr2AZQ2hlEhdx9MYnC2RIIgp2dd3ThSgwHUSQBKgLTiDCwE1Mdqi1Gna8MQR98pzxfQXZQT61IlDdxXEcC7Rm1fsHl96H8sau%2Fer1xew2I%2FQfJ4HsCmjCP0o%2Fr4Rwo6svAQivLvqXn14mRD%2FD%2BnWuX91NkJv%2Bp1D1GWyghJJnbD56HePt%2FjXG%2FJbVd3cHsR4EBFqW0qKvjxSZ%2FWsaXH94d2bbxhdS1Nn5r17CF7cTMurt6%2Ffh7fJRRN0yRDT5wMyntioLIkOCNHM8NdQ3sDLVAetGQTLQpBWw4wANzkuS5RrAEw7MOE0nGFFHo2on3oM0UveiUK7STvXDQpkLQSunqejXFEp9wjJtgSmgGC84pTyh9SY4muDsS5LaXyBqdH0xJ8J3FKYsHhm6CjTPYTB4HZGafrIMaAftE7bblTnLGGPMGYZQw0e1NpC76X2N41iGEO9mReHcTzzAj8ZtbNjJSRlPNmXv19Zb4vrDd1q4hwvZO%2BRMWgpNxUGqveIWT%2FBuFkQWfCJ9eJyKDUT3f6xXjHFLe2HsNqCJmDBuhIMWsEV8NxomjXngoXMCt4xGIqfeSAUBDr6ngjoT8%2FmG4lZc39gX3TW645avmd5yTyK536yG9hjPXijJdQPgajGfjtVZLyqJN56VaTB2SOU4CCogacx09W4C3uJBanISGBqYd83heEcIsPMNnwiSN4pDqkeeiMyA%2F5hkiJQn5LqHnBoBHtZEYqzHBV3tYBV9e5QbW%2B7%2Fcc%2BiSENqvHhFIP2J4oeA01YLXCz%2FfZSJ68vWlZ%2Fxe%2BJgeUbuFdkSwY7%2FclcDqajPSwsBrcjCJPAg8kiidxZ4kep8%2FL6l%2BLdi%2FZ9xriAVr8Zh45W%2Bfoo9vcXyxFjwAyHJH5mHYM2Cx3ceWD2EJ5iPwy8kX9K2N35OpHQE3IkspyLEqL4Kg5e6HlU%2Fwv1rBZuy1H97H7k4gp1VGUb8Dn5gZUhE6Jvnbm6RgC0et8BGWUS78iDcQU32NCb3N797S0c2izTRLDuSWBLOxx2hzCgnq0dzMQF3ul3V32QCdz%2FzzCwg2voSLPRCdHujm%2FMxreeS0lyaBKQi4Rmu9xlD7zcmiF4S6pD%2Bxxz0Xpi6TNouOFTZv6LsJ62QnjRfXi9%2FhONbe6QHREAAA%3D%3D'>"
    }
  ]
}

​

Tweets

Executar no Postman

​

GET accounts/:account_id/tweets

Recupere os detalhes do Tweet para o usuário totalmente promovível da conta (padrão) ou para o usuário especificado no parâmetro user_id. Pode ser qualquer um dos promotable users da conta.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/tweets

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Exemplo: 18ce54d4x5t
tweet_type obrigatório	O tipo de Tweet para os tweet_ids especificados. Type: enum Valores possíveis: DRAFT, PUBLISHED, SCHEDULED
count opcional	Especifica o número de registros a tentar recuperar por solicitação. Type: int Padrão: 200 Mín., máx.: 1, 1000
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Type: string Exemplo: AAAAAFhLRpQLNF-sGBSgAA
include_mentions_and_replies opcional	Indica se menções e respostas devem ser filtradas da lista de Tweets disponíveis. Type: boolean Padrão: false Valores possíveis: true, false
name opcional	Uma query opcional para delimitar os Tweets por name. Omita este parâmetro para recuperar todos. Comprimento máximo: 80 caracteres. Observação: faz correspondência por prefixo sem diferenciar maiúsculas e minúsculas. Type: string Exemplo: dtc
timeline_type opcional	Indica se devem ser retornados Tweets nullcasted (também chamados de “Promoted-only”), Tweets orgânicos ou ambos. Type: enum Padrão: NULLCAST Valores possíveis: ALL, NULLCAST, ORGANIC
trim_user opcional	Indica se o objeto de usuário deve ser excluído na resposta do Tweet. Quando habilitado, a única parte do objeto de usuário que será retornada é o ID do autor do Tweet. Type: boolean Padrão: false Valores possíveis: true, false
tweet_ids opcional	Uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 IDs. Observação: os IDs devem corresponder ao tweet_type especificado. Por exemplo, se for passado um ID de Tweet agendado, então o tweet_type deve ser SCHEDULED para que esse Tweet seja retornado na resposta. Type: long Exemplo: 1122911801354510336,1102836745790316550
user_id opcional	Especifica o usuário ao qual os Tweets devem ser delimitados. Quando não definido, o padrão é o usuário promovível FULL da conta. Type: long Exemplo: 756201191646691328

​

Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true

​

Exemplo de resposta

{
  "request": {
    "params": {
      "tweet_ids": [
        "1166476031668015104"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "name": null,
      "source": "<a href="https://ads-api.x.com" rel="nofollow">App de Teste Interno da X Ads API</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        9
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1166476031668015104",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "id": 1166476031668015104,
      "in_reply_to_status_id": null,
      "conversation_settings": "TODOS",
      "nullcast": true,
      "created_at": "Tue Aug 27 22:22:12 +0000 2019",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "olá, v6",
      "lang": "es",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1166476031668015104"
    }
  ]
}

​

POST accounts/:account_id/tweet

Crie um Tweet para o usuário promovível completo da conta (padrão) ou para o usuário especificado no parâmetro as_user_id. A criação de Tweets nullcast (padrão) e orgânicos é compatível. Tweets nullcast não aparecem na timeline pública e não são exibidos aos seguidores. Ambos os tipos podem ser usados em campanhas.

Se o usuário autenticado não for o usuário promovível FULL nesta conta, verifique se ele tem permissão para publicar Tweets em nome desse usuário fazendo uma solicitação ao endpoint GET accounts/:account_id/authenticated_user_access. A permissão TWEET_COMPOSER indica que o usuário pode usar este endpoint para criar Tweets nullcast em nome do usuário promovível FULL.

Ao usar o endpoint upload.x.com para mídia, forneça o mesmo valor de user_id no parâmetro additional_owners que o valor de as_user_id que você envia para este endpoint.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/tweet

​

Parâmetros

Name	Description
account_id required	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Ads API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
as_user_id required	O ID do usuário do anunciante em nome de quem você está publicando o Tweet. O anunciante deve conceder acesso ao seu @ (ou @s) à conta de anúncios dele via ads.x.com. Essa permissão permite que você chame a API usando os tokens OAuth do seu próprio @ em vez dos do anunciante. Type: long Example: 756201191646691328
text sometimes required	O texto da sua atualização de status. Obrigatório se nenhum media_keys for especificado. Type: string Example: hello, world
card_uri optional	Associe um card ao Tweet usando o valor card_uri de qualquer resposta de cards, se disponível. Type: string Example: card://853503245793641682
conversation_settings optional	Escolha quem pode responder a este Tweet. Qualquer pessoa mencionada sempre pode responder. Observação: este campo não será retornado na resposta da solicitação POST, mas será retornado ao fazer uma solicitação GET. Observação: este parâmetro só funciona na Ads API v8 e superiores. Type: enum Default: EVERYONE Possible values: EVERYONE, FOLLOWING, MENTIONED_USERS
media_keys optional	Associe mídia ao Tweet especificando uma lista de identificadores separados por vírgulas. Inclua até 4 imagens, 1 GIF animado ou 1 vídeo. Type: string Example: 13_1153584529292270722
name optional	O nome do Tweet. Tamanho máximo: 80 caracteres. Type: string Example: Tweet with name
nullcast optional	Define se o Tweet será nullcasted (ou “Promoted-only”). Observação: Tweets orgânicos (nullcast=false) só podem ser criados para o usuário autenticado. Type: boolean Default: true Possible values: true, false
trim_user optional	Define se o objeto de usuário será excluído da resposta do Tweet. Quando ativado, a única parte do objeto de usuário retornada será o ID do autor do Tweet. Type: boolean Default: false Possible values: true, false
tweet_mode optional	Define se a resposta deve estar em modo de compatibilidade ou estendido. Consulte este artigo para mais informações. Type: string Possible values: compat, extended
video_cta optional	A CTA do vídeo. Type: enum Possible values: VISIT_SITE, WATCH_NOW
video_cta_value optional	O valor da CTA correspondente no vídeo. Type: string Example: https://dev.x.com
video_description optional	A descrição exibida abaixo do vídeo. Tamanho máximo: 200 caracteres. Type: string Example: Integre com a plataforma de publicidade do X
video_title optional	O título (headline) exibido abaixo do vídeo. Tamanho máximo: 70 caracteres. Type: string Example: X Ads API

​

Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet?text=hello, world&as_user_id=756201191646691328&trim_user=true

​

Exemplo de resposta

{
  "data": {
    "created_at": "Sat Jun 24 05:08:30 +0000 2017",
    "id": 878479925472251906,
    "id_str": "878479925472251906",
    "text": "olá, mundo",
    "name": null,
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "<a href='"https://ads-api.x.com"' rel='"nofollow"'>App de Teste Interno do X Ads API</a>",
    "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": 756201191646691328,
      "id_str": "756201191646691328"
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "olá, mundo",
      "trim_user": true,
      "as_user_id": 756201191646691328,
      "account_id": "18ce54d4x5t"
    }
  }
}

Atualize o name do Tweet especificado que pertence à conta atual.

​

URL do recurso

https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
tweet_id obrigatório	Uma referência ao Tweet com o qual você está operando na solicitação. Tipo: long Exemplo: 994747471329873920
name opcional	O nome do Tweet. Comprimento máximo: 80 caracteres. Tipo: string Exemplo: Tweet with name

​

Exemplo de requisição

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name

​

Exemplo de resposta

{
  "request": {
    "params": {
      "tweet_id": 994747471329873920,
      "name": "novo nome do Tweet",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
      "coordinates": null,
      "retweeted": false,
      "name": "novo nome do Tweet",
      "conversation_settings": "TODOS",
      "source": "<a href="https://ads-api.x.com" rel="nofollow">App de Teste Interno do X Ads API</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        5
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "994747471329873920",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 994747471329873920,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Wed Jan 01 00:00:00 +0000 2020",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "olá",
      "lang": "en",
      "contributors": null,
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "utc_offset": null,
        "name": "Tushar Bhushan",
        "friends_count": 1065,
        "screen_name": "imit8me",
      "location": "São Francisco, CA",
        "protected": false,
        "url": "https://tushdante.github.io",
        "profile_image_url": "http://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_background_color": "C0DEED",
        "profile_use_background_image": true,
        "is_translator": false,
        "geo_enabled": true,
      "description": "Desenvolvedor Open Source / Engenheiro de Parcerias @twitter / Viajante Espacial | Ex-evangelista @sendgrid @keen_io",
        "profile_link_color": "1DA1F2",
        "id_str": "3271358660",
        "listed_count": 31,
        "default_profile_image": false,
        "followers_count": 407,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_sidebar_border_color": "C0DEED",
        "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
        "favourites_count": 5993,
        "following": null,
        "default_profile": true,
        "withheld_in_countries": [],
        "id": 3271358660,
        "profile_background_tile": false,
        "contributors_enabled": false,
        "follow_request_sent": null,
        "created_at": "Tue Jul 07 22:34:58 +0000 2015",
        "profile_sidebar_fill_color": "DDEEF6",
      "translator_type": "regular",
        "lang": null,
        "profile_text_color": "333333",
        "notifications": null,
        "verified": false,
        "time_zone": null,
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/3271358660/1474853576",
        "statuses_count": 500,
        "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
        "is_translation_enabled": false
      },
      "tweet_id": "994747471329873920"
    }
}

​

Video Conversation Cards

Executar no Postman

Observação: Para associar um card a um Tweet, use o parâmetro card_uri com um dos endpoints POST accounts/:account_id/tweet, POST statuses/update ou POST accounts/:account_id/scheduled_tweets.

​

GET accounts/:account_id/cards/video_conversation

Recupera detalhes de alguns ou de todos os Video Conversation Cards associados à conta atual.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
card_ids opcional	Limita a resposta apenas às video conversation cards desejadas, especificando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Tipo: string Exemplo: 5a86h
count opcional	Especifica a quantidade de registros a tentar recuperar por solicitação. Tipo: int Padrão: 200 Mín., máx.: 1, 1000
cursor opcional	Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações. Tipo: string Exemplo: 8x7v00oow
q opcional	Uma query opcional para filtrar cards por name. Omita este parâmetro para recuperar todos. Comprimento máximo: 80 caracteres. Observação: realiza correspondência por prefixo sem diferenciar maiúsculas de minúsculas. Tipo: string Exemplo: night sky
sort_by opcional	Ordena por um atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações. Tipo: string Exemplo: created_at-asc
with_deleted opcional	Inclui resultados excluídos na sua solicitação. Tipo: boolean Padrão: false Valores possíveis: true, false
with_total_count opcional	Inclui o atributo de resposta total_count. Observação: este parâmetro e cursor são mutuamente exclusivos. Observação: solicitações que incluem total_count terão limites de requisições menores, atualmente definidos como 200 por 15 minutos. Tipo: boolean Padrão: false Valores possíveis: true, false

​

Exemplo de requisição

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

​

Exemplo de resposta

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_ids": [
        "5a86h"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "cartão de conversa em vídeo",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Construa",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "id": "5a86h",
      "video_width": "16",
      "first_cta_tweet": "X Ads API",
      "created_at": "2018-01-30T17:53:04Z",
      "card_uri": "card://958397665015775232",
      "title": "Desenvolvedores",
      "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"
    }
  ]
}

Recupere um cartão de conversação em vídeo específico associado à conta atual.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id obrigatório	Uma referência ao video conversation card com o qual você está operando na solicitação. Type: string Example: 4i0ya
with_deleted opcional	Incluir resultados excluídos na solicitação. Type: boolean Default: false Possible values: true, false

​

Exemplo de requisição

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

​

Exemplo de resposta

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "cartão de conversa em vídeo",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Crie",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "X Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Desenvolvedores",
    "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

Crie um novo card de conversa em vídeo associado à conta especificada.

Consulte Uploading Media para obter informações úteis sobre como enviar imagens aos nossos endpoints.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da API do Anunciante, excluindo GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
first_cta obrigatório	A hashtag de Call-To-Action (CTA) para a primeira opção. Comprimento máximo: 20 caracteres (sem contar o #). Tipo: string Exemplo: #APIs
first_cta_tweet obrigatório	O texto do Tweet a ser usado quando o primeiro CTA for clicado. Tipo: string Exemplo: X Ads API
media_key obrigatório	A chave de mídia para um vídeo a ser usado neste cartão. Nota: O vídeo deve estar na Biblioteca de Mídia da conta. Nota: É necessária uma proporção de aspecto de 16:9. Tipo: string Exemplo: 13_1168079965037467209
name obrigatório	O nome do cartão. Tipo: string Exemplo: cartão de conversa de vídeo
thank_you_text obrigatório	O texto a ser exibido após o CTA ser clicado. Comprimento máximo: 23 caracteres. Tipo: string Exemplo: Construa isso
title às vezes obrigatório	O título do cartão, que aparece abaixo do vídeo e acima dos CTAs. Comprimento máximo: 23 caracteres. Tipo: string Nota: Obrigatório se second_cta não estiver definido. Exemplo: Desenvolvedores
second_cta às vezes obrigatório	A hashtag de Call-To-Action (CTA) para a segunda opção. Comprimento máximo: 20 caracteres (sem contar o #). Tipo: string Nota: Obrigatório se title não estiver definido. Exemplo: #ShareAgain
second_cta_tweet às vezes obrigatório	O texto do Tweet a ser usado quando o segundo CTA for clicado. Nota: Obrigatório se second_cta estiver definido. Tipo: string Exemplo: I Heart @AdsAPI Again
poster_media_key opcional	A chave de mídia para uma imagem de pôster a ser usada neste cartão. Se não especificada, o primeiro quadro será usado. Nota: A imagem deve estar na Biblioteca de Mídia da conta. Tipo: long Exemplo: 3_882726458191298561
third_cta opcional	A hashtag de Call-To-Action (CTA) para a terceira opção. Comprimento máximo: 20 caracteres (sem contar o #). Tipo: string Exemplo: #ShareMore
third_cta_tweet às vezes obrigatório	O texto do Tweet a ser usado quando o terceiro CTA for clicado. Tipo: string Nota: Obrigatório se third_cta estiver definido. Exemplo: I Heart @TwitterDev
fourth_cta opcional	A hashtag de Call-To-Action (CTA) para a quarta opção. Comprimento máximo: 20 caracteres (sem contar o #). Tipo: string Exemplo: #ShareExtra
fourth_cta_tweet às vezes obrigatório	O texto do Tweet a ser usado quando o quarto CTA for clicado. Tipo: string Nota: Obrigatório se fourth_cta estiver definido. Exemplo: I Heart @TwitterDev Again
thank_you_url opcional	A URL a ser exibida com o texto de agradecimento. Tipo: string Exemplo: https://example.com/thankyou
unlocked_image_media_key opcional	Uma media_key de uma imagem que será usada no cenário de desbloqueio instantâneo. Este é um campo somente para escrita. Na resposta, a API fornecerá uma URL do X para esta imagem. Nota: A imagem deve estar na biblioteca de mídia da conta. Tipo: string Exemplo: 3_883112887618682880
unlocked_video_media_key opcional	O identificador de um vídeo do endpoint GET accounts/:account_id/media_library que será usado no cenário de desbloqueio instantâneo. Tipo: string Exemplo: 13_867520357225418752

​

Exemplo de requisição

POST https://ads-api.x.com/12/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

​

Exemplo de resposta

{
  "data": {
    "name": "cartão de conversa em vídeo",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Construa",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "X Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Desenvolvedores",
    "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": "cartão de conversa em vídeo",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Construa",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "first_cta_tweet": "X Ads API",
      "title": "Desenvolvedores",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_CONVERSATION"
    }
  }
}

Atualize o cartão de conversa em vídeo especificado que pertence à conta atual.

Consulte Uploading Media para obter informações úteis sobre como fazer upload de imagens para nossos endpoints.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da API do Anunciante, excluindo GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
card_id obrigatório	Uma referência ao cartão de conversa de vídeo com o qual você está operando na solicitação. Tipo: string Exemplo: 5a86h
first_cta opcional	A hashtag de Chamada para Ação (CTA) para a primeira opção. Comprimento máximo: 20 caracteres (sem contar o #). Tipo: string Exemplo: #APIs
first_cta_tweet opcional	O texto do Tweet a ser usado quando a primeira CTA for clicada. Tipo: string Exemplo: X Ads API
second_cta opcional	A hashtag de Chamada para Ação (CTA) para a segunda opção. Comprimento máximo: 20 caracteres (sem contar o #). Tipo: string Nota: Obrigatório se title não estiver definido. Exemplo: #ShareAgain
second_cta_tweet opcional	O texto do Tweet a ser usado quando a segunda CTA for clicada. Nota: Obrigatório se second_cta estiver definido. Tipo: string Exemplo: I Heart @AdsAPI Again
third_cta opcional	A hashtag de Chamada para Ação (CTA) para a terceira opção. Comprimento máximo: 20 caracteres (sem contar o #). Tipo: string Exemplo: #ShareMore
third_cta_tweet opcional	O texto do Tweet a ser usado quando a terceira CTA for clicada. Tipo: string Nota: Obrigatório se third_cta estiver definido. Exemplo: I Heart @TwitterDev
fourth_cta opcional	A hashtag de Chamada para Ação (CTA) para a quarta opção. Comprimento máximo: 20 caracteres (sem contar o #). Tipo: string Exemplo: #ShareExtra
fourth_cta_tweet opcional	O texto do Tweet a ser usado quando a quarta CTA for clicada. Tipo: string Nota: Obrigatório se fourth_cta estiver definido. Exemplo: I Heart @TwitterDev Again
media_key opcional	A chave de mídia para um vídeo a ser usado neste cartão. Nota: O vídeo deve estar na Biblioteca de Mídia da conta. Nota: É necessária uma proporção de aspecto de 16:9. Tipo: string Exemplo: 13_1168079965037467209
name opcional	O nome do cartão. Tipo: string Exemplo: developers card
poster_media_key opcional	A chave de mídia para uma imagem de pôster a ser usada neste cartão. Se não especificada, o primeiro quadro será usado. Nota: A imagem deve estar na Biblioteca de Mídia da conta. Tipo: long Exemplo: 3_882726458191298561
thank_you_text opcional	O texto a ser exibido após a CTA ser clicada. Comprimento máximo: 23 caracteres. Tipo: string Exemplo: Build it
thank_you_url opcional	A URL a ser exibida com o texto de agradecimento. Tipo: string Exemplo: https://example.com/thankyou
title opcional	O título do cartão, que aparece abaixo do vídeo e acima das CTAs. Comprimento máximo: 23 caracteres. Tipo: string Nota: Obrigatório se second_cta não estiver definido. Exemplo: Start a conversation
unlocked_image_media_key opcional	Um media_key de uma imagem que será usada no cenário de desbloqueio instantâneo. Este é um campo somente para escrita. Na resposta, a API fornecerá uma URL do X para esta imagem. Nota: A imagem deve estar na biblioteca de mídia da conta. Tipo: string Exemplo: 3_883112887618682880
unlocked_video_media_key opcional	O identificador de um vídeo do endpoint GET accounts/:account_id/media_library que será usado no cenário de desbloqueio instantâneo. Tipo: string Exemplo: 13_867520357225418752

​

Exemplo de requisição

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

​

Exemplo de resposta

{
  "data": {
    "name": "cartão de desenvolvedores",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Construa",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "X Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Desenvolvedores",
    "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": "cartão de desenvolvedores"
    }
  }
}

Exclua permanentemente o cartão de conversa em vídeo especificado pertencente à conta atual.

Observação: Esta é uma exclusão permanente (hard delete). Portanto, não é possível recuperar cartões excluídos.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta em uso. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta informada deve estar associada ao usuário autenticado. Type: string Example: 18ce54d4x5t
card_id obrigatório	Referência ao cartão de conversa em vídeo com o qual você está operando na solicitação. Type: string Example: 4i0ya

​

Exemplo de requisição

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

​

Exemplo de resposta

{
  "data": {
    "name": "cartão de conversa em vídeo",
    "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"
    }
  }
}