> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# X (Twitter) API Ruby media tweets & DM attachments

> Upload media with the Xquik Ruby SDK, post tweets with photos or video, and send DM attachments from a connected X (Twitter) account in your own apps and bots.

> For the complete documentation index, see [llms.txt](https://docs.xquik.com/llms.txt).

This guide builds on the [Ruby SDK setup](https://docs.xquik.com/sdks/ruby.md), 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.

```ruby theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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`.

```ruby theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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.

```ruby theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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](https://docs.xquik.com/api-reference/x-write/get-write-action-status.md). `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](https://docs.xquik.com/api-reference/x-write/delete-dm.md).




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](https://docs.xquik.com/api-reference/x-write/create-tweet.md) |
| Upload a local file | `POST /x/media` | [Upload media](https://docs.xquik.com/api-reference/x-write/upload-media.md) |
| Send a DM attachment | `POST /x/dm/{userId}` | [Send DM](https://docs.xquik.com/api-reference/x-write/send-dm.md) |
| Check a write action | `GET /x/write-actions/{id}` | [Write action status](https://docs.xquik.com/api-reference/x-write/get-write-action-status.md) |
| Delete a DM | `DELETE /x/dm/{userId}/messages/{messageId}` | [Delete DM](https://docs.xquik.com/api-reference/x-write/delete-dm.md) |

## Next steps

* [Ruby SDK setup](https://docs.xquik.com/sdks/ruby.md)
* [Tweet search](https://docs.xquik.com/sdks/ruby-tweet-search.md)
* [Follower export](https://docs.xquik.com/sdks/ruby-follower-export.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.