Telegram

Telegram publishing goes through a bot that is an administrator of your channel or group. There is no OAuth: you connect with a short access code, then publish with POST /v1/posts using the platform id telegram. The same bot handles direct messages in the Inbox and the "/" command menu.

#What you will be able to do

#Connect

The bot must be an administrator of the channel or group, with permission to post messages, before you connect. A bot that is a plain member, or an admin without the post permission, is the most common setup failure: every post then fails with "Bot is not a member of the channel".

#With an access code

curl "https://api.pozy.ai/v1/connect/telegram?profileId=66a1f0c2a4b9d3e8f1a2b3c4" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/telegram?profileId=66a1f0c2a4b9d3e8f1a2b3c4", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.code, data.botUsername, data.instructions);

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/connect/telegram",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": "66a1f0c2a4b9d3e8f1a2b3c4"},
)
data = resp.json()
print(data["code"], data["botUsername"], data["instructions"])

curl -X PATCH "https://api.pozy.ai/v1/connect/telegram?code=$CODE" \
  -H "Authorization: Bearer $POZY_API_KEY"

#Directly with a chat id

If the bot is already an administrator and you know the chat id, skip the code and call Connect Telegram directly:

curl -X POST https://api.pozy.ai/v1/connect/telegram \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "@acmenews", "profileId": "66a1f0c2a4b9d3e8f1a2b3c4" }'

chatId is @username for a public channel. For a private channel or a group it is the numeric id; private channel ids start with -100, group ids are negative. One way to find a numeric id is to forward a message from the channel to an id-lookup bot in Telegram.

In a channel, posts appear under the channel's name and logo. In a group, they appear as sent by the bot.

#Post types

The media decides the message type:

curl -X POST https://api.pozy.ai/v1/posts \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<b>Release 2.4</b> is out.\nRead the notes: <a href=\"https://example.com/changelog\">changelog</a>",
    "platforms": [{
      "platform": "telegram",
      "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
      "platformSpecificData": { "parseMode": "HTML", "disableNotification": true }
    }],
    "publishNow": true
  }'

const res = await fetch("https://api.pozy.ai/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: '<b>Release 2.4</b> is out.\nRead the notes: <a href="https://example.com/changelog">changelog</a>',
    platforms: [{
      platform: "telegram",
      accountId: "66b2e19d8c3f5a7e9d0b1c2d",
      platformSpecificData: { parseMode: "HTML", disableNotification: true },
    }],
    publishNow: true,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.post.platforms[0].status);

resp = requests.post(
    "https://api.pozy.ai/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "content": '<b>Release 2.4</b> is out.\nRead the notes: <a href="https://example.com/changelog">changelog</a>',
        "platforms": [{
            "platform": "telegram",
            "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
            "platformSpecificData": {"parseMode": "HTML", "disableNotification": True},
        }],
        "publishNow": True,
    },
)
print(resp.json()["post"]["platforms"][0]["status"])

#Formatting

parseMode sets how Telegram reads content. HTML is the default.

#Platform fields

Edit the text or caption of a published message with Edit published post. The media cannot be changed.

#Media requirements

URLs must be direct HTTPS links with no redirects. Telegram rejects HTTP and redirecting links with "Wrong file identifier/HTTP URL specified". Media gives you URLs that qualify.

#Limits

#Analytics

Telegram's Bot API exposes no view or engagement counts, so Telegram has no analytics in Pozy.

#Inbox

People who message the bot show up in the Inbox.

When someone taps an inline keyboard button, the callback data arrives on the incoming message in metadata.callbackData. Reactions arrive as reaction.received when the bot is an admin of the chat; reactions in private chats are not delivered.

#Bot commands

Bot commands are the entries in the "/" menu people see when they chat with the bot. Manage them with Get, Set and Delete TG bot commands.

curl -X PUT https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/telegram-commands \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "commands": [{ "command": "help", "description": "How to reach support" }, { "command": "status", "description": "Check your order status" }] }'

See Conversation starters for menus and starters on other channels.

#Errors you may see

Errors covers the error format.

#Endpoints

#Webhook events