Sending message in telegram bot with images

Sending message in telegram bot with images

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Adding Image Previews to Telegram Bot Messages

Your current implementation uses replyWithMessage to push a payload containing only text and a URL. While this works for simple notifications, it misses the opportunity to leverage Telegram's rich media capabilities. Specifically, you can inject an image directly into the message body so that users see a preview alongside your text, rather than having to click the link to view the content.

To achieve this in PHP, you need to modify the request payload sent to the sendMessage method (or keep using replyWithMessage if it wraps sendMessage). The key is including an photo parameter or a caption_image parameter depending on the specific SDK version and wrapper logic you are employing.

In raw HTTP requests using cURL, this is straightforward: you send a POST request to https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage. Inside the JSON body, you add a "photo" field pointing to the URL of your image file. Telegram will then render that image immediately above the text content.

$response = $this->replyWithMessage([
    'chat_id'      => $chatId,
    'text'         => $item['title'] . "\n\n" . $url,
    'parse_mode'   => 'Markdown', // Optional: enables bold/italic formatting
    'photo'        => $imageUrl    // The URL to the image file
]);

If you are using a custom method named replyWithMessage in your codebase, ensure that this wrapper actually accepts and forwards additional fields like photo. If your current signature only allows text, you will need to update that method's implementation to pass these extra parameters through to the underlying sendMessage call.

Handling Image Sources

When passing an image URL, Telegram has specific requirements regarding the source. The image must be hosted on a server that allows direct access via HTTP or HTTPS. It cannot be served from a local file path (e.g., /images/logo.png) unless you are running the bot code directly on the same machine where the image resides and using a reverse proxy to serve it publicly.

For most production scenarios, you should host images on a CDN or a static asset server. A common pitfall is uploading the image to your own storage (like S3) and then trying to access it via an internal endpoint like http://internal-lambda-url/image.jpg. Telegram's API will reject this because the request comes from outside that internal network. You must ensure the URL is publicly resolvable by any external client, including mobile devices on cellular networks where your bot might be hosted.

Caption vs. Photo Mode

There is a nuance in how images are displayed depending on whether you treat them as a primary attachment or as a background for text. By adding the photo key to the payload, Telegram treats the image as a standard photo message with a caption. This is usually the desired behavior for "preview" scenarios where an image accompanies a news snippet or product link.

If your goal is purely decorative—where the image serves only as a background and text overlays it—you would need to use replyWithMarkup combined with Telegram's Inline Keyboard functionality, which allows you to send a photo followed by text without changing the message type, but this adds complexity regarding inline keyboard layouts. For a simple preview, the direct photo parameter is the most efficient approach.

Code Optimization Tips

If you are wrapping this logic in a Laravel application, consider utilizing Laravel's HTTP facade or your existing client to handle the request. However, if you are using a third-party SDK (like vlucas/phpdotenv or similar wrappers), double-check the documentation for supported payload keys. Some older wrappers might have hardcoded the message structure and ignore extra fields like photo.

Finally, remember that Telegram caches images. If you update an image URL but expect it to change instantly in the chat history, users may still see the cached version until they pull-to-refresh or leave and re-enter the chat. This is standard behavior across all clients and should be factored into your design if real-time visual updates are critical.

For deeper insights into building robust Telegram bots in PHP, you might find useful patterns at https://laravelcompany.com regarding API integration strategies.

Our network