Telegram Guide

Copy Markdown View Source

PingPong sends Telegram notifications through the Telegram Bot API. You need a bot token and the target chat ID.

Create a Bot

  1. Open Telegram and start a chat with @BotFather.
  2. Send /newbot.
  3. Follow the prompts to choose a bot name and username.
  4. Copy the bot token that BotFather gives you.

Keep the token private. Anyone with the token can use your bot.

Find a Chat ID

For a direct message:

  1. Start a chat with your new bot.
  2. Send any message to the bot.
  3. Open this URL in a browser, replacing BOT_TOKEN:
https://api.telegram.org/botBOT_TOKEN/getUpdates

Look for message.chat.id in the JSON response.

For a group:

  1. Add the bot to the group.
  2. Send a message in the group.
  3. Call getUpdates with the bot token.
  4. Use the group chat.id. Group IDs are often negative numbers.

Send a Message

Use service :telegram.

token = "123456:telegram-bot-token"
chat_id = "123456789"

PingPong.send(
  :telegram,
  %{content: "The nightly build completed successfully.", chat_id: chat_id},
  %{token: token}
)

A successful response usually looks like:

{:ok, %{"ok" => true, "result" => result}}

Message preview:

Telegram message preview

Payload

Telegram requires :content and :chat_id.

%{
  content: "Message text",
  chat_id: "123456789"
}

PingPong sends :content to Telegram as the text field.

Options

Telegram requires :token.

%{token: "123456:telegram-bot-token"}

Async Example

{:ok, task} =
  PingPong.send_async(
    :telegram,
    %{content: "Background job started.", chat_id: chat_id},
    %{token: token}
  )

Task.await(task)

Multiple Notifications

notifications = [
  admins: {:telegram, %{content: "Deploy started.", chat_id: admin_chat_id}, %{token: token}},
  alerts: {:telegram, %{content: "Disk usage is high.", chat_id: alerts_chat_id}, %{token: token}}
]

PingPong.send_multiple(notifications)

Common Errors

Missing :content, :chat_id, or :token:

{:error, {:missing_required_params}, nil}

Unknown service key:

{:error, {:unknown_service, :telegram_bot}}

Telegram API error:

{:error, {:error_response, response}}

Transport error:

{:error, {:error, reason}}

Troubleshooting

  • Make sure the bot token is copied exactly from BotFather.
  • Make sure the user or group has sent at least one message after the bot was created or added.
  • For groups, make sure the bot is still a member of the group.
  • If Telegram returns an error response, inspect the response body for the API description.
  • Do not commit bot tokens. Load them from runtime config or environment variables in real applications.