Retrieve pictures & user presence

Download pictures

Use Get a Chat Picture with a chat ID, or Get a User Picture with a user ID obtained from Telegram results. These endpoints return image data rather than a JSON object containing an image URL. Handle the response content type and forward the bytes from your backend when displaying an image; keep the API key on your server.

A missing or inaccessible photo may fail even when the chat or user exists. Do not assume a photo is present for every entity.

import { writeFile } from "node:fs/promises";

const response = await fetch(
  "https://api.unipile.com/v2/acc_123456789/chats/chat_id/picture",
  {
    method: "GET",
    headers: {
      "X-API-KEY": "YOUR_API_KEY",
    },
  },
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile("chat-picture.jpg", Buffer.from(await response.arrayBuffer()));

import requests

response = requests.get(
    "https://api.unipile.com/v2/acc_123456789/chats/chat_id/picture",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
with open("chat-picture.jpg", "wb") as image:
    image.write(response.content)

curl --request GET \
  --url "https://api.unipile.com/v2/acc_123456789/chats/chat_id/picture" \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --output chat-picture.jpg

Download a user picture

import { writeFile } from "node:fs/promises";

const response = await fetch(
  "https://api.unipile.com/v2/acc_123456789/users/user_id/picture",
  {
    method: "GET",
    headers: {
      "X-API-KEY": "YOUR_API_KEY",
    },
  },
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile("user-picture.jpg", Buffer.from(await response.arrayBuffer()));

import requests

response = requests.get(
    "https://api.unipile.com/v2/acc_123456789/users/user_id/picture",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
with open("user-picture.jpg", "wb") as image:
    image.write(response.content)

curl --request GET \
  --url "https://api.unipile.com/v2/acc_123456789/users/user_id/picture" \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --output user-picture.jpg

Retrieve user presence

Call Get a User Presence with the Telegram user ID. Presence depends on what Telegram exposes to the connected account. Handle unknown when no presence is reported; do not interpret missing presence as offline.

This reads another user's presence. Set Presence changes the connected account's own presence and is a separate operation.

const response = await fetch(
  "https://api.unipile.com/v2/acc_123456789/users/user_id/presence",
  {
    method: "GET",
    headers: {
      "X-API-KEY": "YOUR_API_KEY",
    },
  },
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.get(
    "https://api.unipile.com/v2/acc_123456789/users/user_id/presence",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
data = response.json()

curl --request GET \
  --url "https://api.unipile.com/v2/acc_123456789/users/user_id/presence" \
  --header 'X-API-KEY: YOUR_API_KEY'