X (Twitter) API Ruby media tweets & DM attachments

This guide builds on the Ruby SDK setup, which covers install and authentication.

Workflow to post media tweets and DM attachments

Use this workflow when Ruby code needs to post a media-backed tweet. That code can be a Ruby app, Rails job, Sidekiq worker, or agent service. Use it too when the code replies with media. It also covers sending one uploaded media item in a DM. Tweet and reply media posts use public media URLs directly on POST /x/tweets. Send up to 4 image URLs or exactly 1 MP4 video URL. The video can be up to 100 MB. Do not mix video with other media. Do not upload first when the media URL is already public. Use client.request to capture the durable write action. Send a unique Idempotency-Key. Store id, request.hash, billing, result, and statusUrl. Poll while terminal is false. Retry only when safeToRetry is true, using a new key.

def create_tweet_handoff(client, payload)
  response = client.request(
    method: :post,
    path: "x/tweets",
    body: payload
  )

  result = response.fetch(:result, {}) || {}
  {
    "status" => response.fetch(:status),
    "terminal" => response.fetch(:terminal),
    "safe_to_retry" => response.fetch(:safeToRetry),
    "write_action_id" => response.fetch(:id),
    "request_hash" => response.dig(:request, :hash),
    "tweet_id" => result[:id] || response[:tweetId],
    "charged" => response.dig(:billing, :charged),
    "charged_credits" => response.dig(:billing, :chargedCredits),
    "poll" => response.fetch(:terminal) ? nil : response.fetch(:statusUrl)
  }
end

tweet_handoff = create_tweet_handoff(
  client,
  {
    account: "@username",
    text: "New demo video is live.",
    media: ["https://example.com/product-demo.mp4"]
  }
)

puts(JSON.generate(tweet_handoff))

To post an image reply, add reply_to_tweet_id.

reply_handoff = create_tweet_handoff(
  client,
  {
    account: "@username",
    text: "Here is the requested screenshot.",
    reply_to_tweet_id: "1893704267862470862",
    media: ["https://example.com/export-preview.png"]
  }
)

puts(JSON.generate(reply_handoff))

For DM attachments, upload the local file first. Then pass the returned media.media_id as the only media_ids item.

File.open("./handoff.png", "rb") do |file|
  media = client.x.media.upload(
    account: "@username",
    file: file
  )

  dm = client.x.dm.send_(
    "44196397",
    account: "@username",
    text: "Here is the asset.",
    media_ids: [media.media_id]
  )

  dm_handoff = {
    message_id: dm.message_id,
    media_id: media.media_id,
    user_id: "44196397",
    account: "@username",
    status: "sent"
  }

  puts(JSON.generate(dm_handoff))
end

Store write_action_id and charged_credits. Before retrying a pending tweet or reply, poll Get Write Action Status. client.x.tweets.create returns tweet.tweet_id for confirmed-only flows. client.x.media.upload returns media.media_id for DM attachments. client.x.dm.send_ returns dm.message_id for support tickets, CRM records, queue jobs, or agent memory. Keep DM body text in private systems. Shared logs, public artifacts, queue status, and agent handoffs should omit full DM bodies. They should store message_id, optional media_id, account, user_id, and send status. Leave generated reply_to_message_id unset even if SDK params expose it. The REST endpoint rejects DM reply threading. client.x.dm.delete_message deletes a DM. Text-only tweet and reply writes cost 30 credits. Tweet media adds 2 credits per started MB across attached files. Uploading media costs 10 credits. Sending the DM costs 10 credits. Do not pass uploaded media.media_id values to client.x.tweets.create. That method uses media with public media URLs.

REST routes

Task	REST route	Reference
Post a media tweet or reply	`POST /x/tweets`	Create tweet
Upload a local file	`POST /x/media`	Upload media
Send a DM attachment	`POST /x/dm/{userId}`	Send DM
Check a write action	`GET /x/write-actions/{id}`	Write action status
Delete a DM	`DELETE /x/dm/{userId}/messages/{messageId}`	Delete DM

Overview

TypeScript

Python

Go

Java

Kotlin

C#

Ruby

PHP

X (Twitter) API Ruby media tweets & DM attachments

Workflow to post media tweets and DM attachments

REST routes

Next steps

​Workflow to post media tweets and DM attachments

​REST routes

​Next steps

Workflow to post media tweets and DM attachments

REST routes

Next steps