Sexy.Bot.Api (Sexy v0.10.1)

Copy Markdown View Source

Low-level HTTP client for the Telegram Bot API.

Every method builds a JSON (or multipart) body and POSTs it to https://api.telegram.org/bot<TOKEN>/<method>.

Most users don't need to call this module directly — use Sexy.Bot which delegates here. For any Telegram method not explicitly wrapped, call request/2:

body = Jason.encode!(%{chat_id: 123, text: "hi"})
Sexy.Bot.Api.request(body, "sendMessage")

Timeouts

  • JSON requests: 5 seconds (configurable via opts)
  • Multipart uploads: 20 seconds
  • Polling (get_updates): 10 seconds

Return values

All methods return decoded JSON as a map:

%{"ok" => true, "result" => %{...}}
%{"ok" => false, "description" => "..."}

Summary

Types

tg_response()

Functions

answer_callback(obj)
answer_callback(callback_id, text, alert)
answer_pre_checkout(pre_checkout_query_id)
copy_message(chat_id, from_chat_id, message_id)
delete_commands()
delete_message(chat_id, message_id, opts \\ [])

Delete a message from a chat.

edit_media(body)
edit_reply_markup(body)
edit_text(body)
forward_message(body)
get_chat(chat_id)
get_chat_member(chat_id, user_id)
get_me()
get_updates(offset)
get_user_photo(user_id)
refund_star_payment(user_id, telegram_payment_charge_id)
request(body, method)
send_animation(body)
send_animation(chat_id, file, filename, text, reply_markup)
send_chat_action(chat_id, action)

Show a chat action indicator. action is a Telegram action string, e.g. "typing", "upload_photo", "upload_video", "record_voice".

send_dice(chat_id, emoji)

Send a dice animation. emoji is one of Telegram's dice emoji: "🎲", "🎯", "🏀", "⚽", "🎳", "🎰".

send_document(chat_id, file, filename, text, reply_markup)
send_invoice(chat_id, title, description, payload, currency, prices)
send_message(body)
send_message(chat_id, text)
send_photo(body)
send_photo(chat_id, file, filename, text, reply_markup)
send_poll(body)
send_video(body)
send_video(chat_id, file, filename, text, reply_markup)
set_commands(string)
with_429_retry(fun)

Run fun (an API call returning a tg_response) and, on a Telegram 429 rate limit, sleep the advertised retry_after and try once more.

Types

tg_response()

@type tg_response() :: map()

Functions

answer_callback(obj)

@spec answer_callback(map()) :: tg_response()

answer_callback(callback_id, text, alert)

@spec answer_callback(String.t(), String.t(), boolean()) :: tg_response()

answer_pre_checkout(pre_checkout_query_id)

@spec answer_pre_checkout(String.t()) :: tg_response()

copy_message(chat_id, from_chat_id, message_id)

@spec copy_message(integer(), integer(), integer()) :: tg_response()

delete_commands()

@spec delete_commands() :: tg_response()

delete_message(chat_id, message_id, opts \\ [])

@spec delete_message(integer(), integer(), keyword()) :: tg_response() | {:ok, pid()}

Delete a message from a chat.

Options

  • :after — delay in seconds before deleting. Accepts integers and floats. When provided, deletion runs asynchronously in a supervised background task. Best-effort: pending deletions are lost if the node restarts before the delay elapses.

Examples

# Immediate deletion
delete_message(chat_id, message_id)

# Delete after 5 seconds
delete_message(chat_id, message_id, after: 5)

# Delete after half a second
delete_message(chat_id, message_id, after: 0.5)

edit_media(body)

@spec edit_media(String.t()) :: tg_response()

edit_reply_markup(body)

@spec edit_reply_markup(String.t()) :: tg_response()

edit_text(body)

@spec edit_text(map()) :: tg_response()

forward_message(body)

@spec forward_message(String.t()) :: tg_response()

get_chat(chat_id)

@spec get_chat(integer()) :: tg_response()

get_chat_member(chat_id, user_id)

@spec get_chat_member(integer(), integer()) :: tg_response()

get_me()

@spec get_me() :: tg_response()

get_updates(offset)

@spec get_updates(integer()) :: {:ok, [map()]} | :error | {:error, term()}

get_user_photo(user_id)

@spec get_user_photo(integer()) :: String.t() | nil

refund_star_payment(user_id, telegram_payment_charge_id)

@spec refund_star_payment(integer(), String.t()) :: tg_response()

request(body, method)

@spec request(String.t(), String.t()) :: tg_response()

send_animation(body)

@spec send_animation(String.t()) :: tg_response()

send_animation(chat_id, file, filename, text, reply_markup)

@spec send_animation(integer(), binary(), String.t(), String.t(), String.t()) ::
  tg_response()

send_chat_action(chat_id, action)

@spec send_chat_action(integer(), String.t()) :: tg_response()

Show a chat action indicator. action is a Telegram action string, e.g. "typing", "upload_photo", "upload_video", "record_voice".

send_dice(chat_id, emoji)

@spec send_dice(integer(), String.t()) :: tg_response()

Send a dice animation. emoji is one of Telegram's dice emoji: "🎲", "🎯", "🏀", "⚽", "🎳", "🎰".

send_document(chat_id, file, filename, text, reply_markup)

@spec send_document(integer(), binary(), String.t(), String.t(), String.t()) ::
  tg_response()

send_invoice(chat_id, title, description, payload, currency, prices)

@spec send_invoice(integer(), String.t(), String.t(), String.t(), String.t(), list()) ::
  tg_response()

send_message(body)

@spec send_message(String.t()) :: tg_response()

send_message(chat_id, text)

@spec send_message(integer(), String.t()) :: tg_response()

send_photo(body)

@spec send_photo(String.t()) :: tg_response()

send_photo(chat_id, file, filename, text, reply_markup)

@spec send_photo(integer(), binary(), String.t(), String.t(), String.t()) ::
  tg_response()

send_poll(body)

@spec send_poll(String.t()) :: tg_response()

send_video(body)

@spec send_video(String.t()) :: tg_response()

send_video(chat_id, file, filename, text, reply_markup)

@spec send_video(integer(), binary(), String.t(), String.t(), String.t()) ::
  tg_response()

set_commands(string)

@spec set_commands(String.t()) :: tg_response()

with_429_retry(fun)

@spec with_429_retry((-> tg_response())) :: tg_response()

Run fun (an API call returning a tg_response) and, on a Telegram 429 rate limit, sleep the advertised retry_after and try once more.

Safe to retry: a 429 means the request was rejected, not executed, and both send and edit are idempotent. Non-429 responses (incl. permanent errors like BUTTON_DATA_INVALID) are returned unchanged — no retry.