/// <summary>
/// Use this method to set the score of the specified user in a game.
/// </summary>
/// <param name="disableEditMessage">Pass True, if the game message should not be automatically edited to include the current scoreboard</param>
/// <param name="chatId">Required if inline_message_id is not specified. Unique identifier for the target chat</param>
/// <param name="inlineMessageId">Required if chat_id and message_id are not specified. Identifier of the inline message</param>
/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.</param>
/// <param name="userId">User identifier</param>
/// <param name="score">New score, must be non-negative</param>
/// <param name="force">Pass True, if the high score is allowed to decrease. This can be useful when fixing mistakes or banning cheaters</param>
/// <param name="messageId">Required if inline_message_id is not specified. Identifier of the sent message</param>
/// <returns>
/// On success, if the message was sent by the bot, returns the edited <see cref="Message" />., otherwise returns True. Returns an error, if the new score is not greater than the user's current score in the chat and force is False.
/// </returns>
public Task <object> SetGameScoreAsync(long userId, long score, bool force = false, bool disableEditMessage = false, string chatId = null, long messageId = 0, string inlineMessageId = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(userId, nameof(userId));
Contracts.EnsureNotNegativeNumber(score, nameof(score));
var parameters = new NameValueCollection();
if (string.IsNullOrWhiteSpace(chatId) && messageId == 0)
{
Contracts.EnsureNotNull(inlineMessageId, nameof(inlineMessageId));
parameters.Add("inline_message_id", inlineMessageId);
}
else if (string.IsNullOrWhiteSpace(inlineMessageId))
{
Contracts.EnsureNotNull(chatId, nameof(chatId));
Contracts.EnsureNotZero(messageId, nameof(messageId));
parameters.Add("chat_id", chatId);
parameters.Add("message_id", messageId);
}
parameters.Add("user_id", userId);
parameters.Add("score", score);
parameters.AddIf(force == true, "force", force);
parameters.AddIf(disableEditMessage == true, "disable_edit_message", disableEditMessage);
return(this.CallTelegramMethodAsync <object>(cancellationToken, "setGameScore", parameters));
}
/// <summary>
/// Use this method to get data for high score tables. Will return the score of the specified user and
/// several of his neighbors in a game. On success, returns an Array of GameHighScore objects.
/// </summary>
/// <param name="userId">Target user id</param>
/// <param name="chatId">Required if inline_message_id is not specified. Unique identifier for the target chat.</param>
/// <param name="inlineMessageId">Required if chat_id and message_id are not specified. Identifier of the inline message.</param>
/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.</param>
/// <param name="messageId">Required if inline_message_id is not specified. Identifier of the sent message.</param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
public Task <GameHighScore[]> GetGameHighScoresAsync(long userId, string chatId = null, long messageId = 0, string inlineMessageId = null, CancellationToken cancellationToken = default(CancellationToken))
{
var parameters = new NameValueCollection();
if (string.IsNullOrWhiteSpace(chatId) && messageId == 0)
{
Contracts.EnsureNotNull(inlineMessageId, nameof(inlineMessageId));
parameters.Add("inline_message_id", inlineMessageId);
}
else if (string.IsNullOrWhiteSpace(inlineMessageId))
{
Contracts.EnsureNotNull(chatId, nameof(chatId));
Contracts.EnsureNotZero(messageId, nameof(messageId));
parameters.Add("chat_id", chatId);
parameters.Add("message_id", messageId);
}
parameters.Add("user_id", userId);
return(this.CallTelegramMethodAsync <GameHighScore[]>(cancellationToken, "getGameHighScores", parameters, chatId));
}
/// <summary>
/// Sends a point on the map.
/// </summary>
/// <param name="chatId">Unique identifier for the message recipient.</param>
/// <param name="latitude">Latitude of location</param>
/// <param name="longitude">Longitude of location</param>
/// <param name="disableNotification">If set to <c>true</c> sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.</param>
/// <param name="replyToMessageId">If the message is a reply, ID of the original message.</param>
/// <param name="replyMarkup">Additional interface options. An <see cref="IReply" /> object for a custom reply keyboard,
/// instructions to hide keyboard or to force a reply from the user.</param>
/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.</param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
public Task <Message> SendLocationAsync(long chatId, double latitude, double longitude, bool disableNotification = false, long replyToMessageId = 0, IReply replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendLocationAsync(chatId.ToString(), latitude, longitude, disableNotification, replyToMessageId, replyMarkup, cancellationToken));
}
/// <summary>
/// Sends an audio file. If you want Telegram clients to display them in the music player. Your audio must be in the .mp3 format.
/// </summary>
/// <param name="chatId">Unique identifier for the message recipient.</param>
/// <param name="audioStream">A <see cref="Stream" /> to the audio file to send.</param>
/// <param name="caption">Audio caption, 0-200 characters</param>
/// <param name="fileName">A name for the file to be sent using <paramref name="audioStream" />.</param>
/// <param name="duration">Duration of the audio in seconds.</param>
/// <param name="performer">The performer of the audio.</param>
/// <param name="title">The track name.</param>
/// <param name="disableNotification">If set to <c>true</c> sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.</param>
/// <param name="replyToMessageId">If the message is a reply, ID of the original message.</param>
/// <param name="replyMarkup">Additional interface options. An <see cref="IReply" /> object for a custom reply keyboard,
/// instructions to hide keyboard or to force a reply from the user.</param>
/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.</param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
public Task <Message> SendAudioAsync(long chatId, [NotNull] Stream audioStream, string caption, string fileName, int duration, string performer = null, string title = null, bool disableNotification = false, long replyToMessageId = 0, IReply replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendAudioAsync(chatId.ToString(), audioStream, caption, fileName, duration, performer, title, disableNotification, replyToMessageId, replyMarkup, cancellationToken));
}
/// <summary>Forwards message of any kind.</summary>
/// <param name="chatId">Unique identifier for the message recipient.</param>
/// <param name="fromChatId">
/// Unique identifier for the chat where the original message was sent.
/// </param>
/// <param name="messageId">Unique message identifier</param>
/// <param name="disableNotification">If set to <c>true</c> sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.</param>
/// <param name="cancellationToken">
/// A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.
/// </param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
public Task <Message> ForwardMessageAsync(long chatId, long fromChatId, long messageId, bool disableNotification = false, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.ForwardMessageAsync(chatId.ToString(), fromChatId.ToString(), messageId, disableNotification, cancellationToken));
}
/// <summary>
/// Sends a text message.
/// </summary>
/// <param name="chatId">Unique identifier for the message recipient.</param>
/// <param name="text">Text of the message to be sent.</param>
/// <param name="parseMode">Indicates the way that the Telegram should parse the sent message.</param>
/// <param name="disableWebPagePreview">if set to <c>true</c> disables link previews for links in this message.</param>
/// <param name="disableNotification">If set to <c>true</c> sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.</param>
/// <param name="replyToMessageId">If the message is a reply, ID of the original message.</param>
/// <param name="replyMarkup">Additional interface options. An <see cref="IReply" /> object for a custom reply keyboard,
/// instructions to hide keyboard or to force a reply from the user.</param>
/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.</param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
public Task <Message> SendMessageAsync(long chatId, [NotNull] string text, ParseMode parseMode = ParseMode.Normal, bool disableWebPagePreview = false, bool disableNotification = false, long replyToMessageId = 0, IReply replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendMessageAsync(chatId.ToString(), text, parseMode, disableWebPagePreview, disableNotification, replyToMessageId, replyMarkup, cancellationToken));
}
/// <summary>
/// Sends a chat action. Use this method when you need to tell the user that something is happening on
/// the bot's side.
/// </summary>
/// <param name="chatId">Unique identifier for the message recipient.</param>
/// <param name="action">Type of action to broadcast.</param>
/// <param name="cancellationToken">
/// A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.
/// </param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
/// <remarks>
/// Use this method when you need to tell the user that something is happening on the bot's side. The
/// status is set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear
/// its typing status).
/// <example>
/// The <c>ImageBot</c> needs some time to process a request and upload the image. Instead of sending a
/// text message along the lines of "Retrieving image, please wait…", the bot may use
/// <see cref="SendChatActionAsync(long,ChatAction,CancellationToken)" />
/// with action = upload_photo. The user will see a "sending photo" status for the bot.
/// </example>
/// </remarks>
public Task <bool> SendChatActionAsync(long chatId, ChatAction action, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendChatActionAsync(chatId.ToString(), action, cancellationToken));
}
/// <summary>
/// Sends <c>.webp</c> sticker.
/// </summary>
/// <param name="chatId">Unique identifier for the message recipient.</param>
/// <param name="stickerStream">A <see cref="Stream" /> to the sticker file to send.</param>
/// <param name="fileName">A name for the file to be sent using <paramref name="stickerStream" />.</param>
/// <param name="disableNotification">If set to <c>true</c> sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.</param>
/// <param name="replyToMessageId">If the message is a reply, ID of the original message.</param>
/// <param name="replyMarkup">Additional interface options. An <see cref="IReply" /> object for a custom reply keyboard,
/// instructions to hide keyboard or to force a reply from the user.</param>
/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.</param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
public Task <Message> SendStickerAsync(long chatId, [NotNull] Stream stickerStream, string fileName, bool disableNotification = false, long replyToMessageId = 0, IReply replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendStickerAsync(chatId.ToString(), stickerStream, fileName, disableNotification, replyToMessageId, replyMarkup, cancellationToken));
}
/// <summary>
/// Edits captions of the message with the provided identifier sent by the bot or via the bot (for
/// inline bots).
/// </summary>
/// <param name="chatId">
/// Unique identifier for the target chat or username of the target channel (in the format
/// @channelusername).
/// </param>
/// <param name="messageId">Unique identifier of the sent message.</param>
/// <param name="caption">New caption of the message.</param>
/// <param name="replyMarkup">
/// An <see cref="InlineKeyboardMarkup" /> object for a custom reply keyboard.
/// </param>
/// <param name="cancellationToken">
/// A <see cref="T:System.Threading.CancellationToken" /> to observe while waiting for the task to
/// complete.
/// </param>
/// <returns>
/// A task that represents the asynchronous operation. On success the task results contains the edited
/// Message is returned.
/// </returns>
public Task <Message> EditMessageCaptionAsync(long chatId, long messageId, [NotNull] string caption, InlineKeyboardMarkup replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.EditMessageCaptionAsync(chatId.ToString(), messageId, caption, replyMarkup, cancellationToken));
}
/// <summary>
/// Edits text messages sent by the bot or via the bot (for inline bots).
/// </summary>
/// <param name="chatId">
/// Unique identifier for the target chat or username of the target channel (in the format
/// @channelusername).
/// </param>
/// <param name="messageId">Unique identifier of the sent message.</param>
/// <param name="text">New text of the message</param>
/// <param name="parseMode">
/// A value from <see cref="ParseMode" /> enum indicates the way that the Telegram should parse the
/// sent message. Send <see cref="ParseMode.Markdown" />, if you want Telegram apps to show bold,
/// italic, fixed-width text or inline URLs in your bot's message.
/// </param>
/// <param name="disableWebPagePreview">Disables link previews for links in this message</param>
/// <param name="replyMarkup">
/// An <see cref="InlineKeyboardMarkup" /> object for a custom reply keyboard.
/// </param>
/// <param name="cancellationToken">
/// A <see cref="T:System.Threading.CancellationToken" /> to observe while waiting for the task to
/// complete.
/// </param>
/// <returns>
/// A task that represents the asynchronous operation. The task results contains the edited
/// <see cref="Message" /> on success.
/// </returns>
public Task <Message> EditMessageTextAsync(long chatId, long messageId, [NotNull] string text, ParseMode parseMode = ParseMode.Normal, bool disableWebPagePreview = false, InlineKeyboardMarkup replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.EditMessageTextAsync(chatId.ToString(), messageId, text, parseMode, disableWebPagePreview, replyMarkup, cancellationToken));
}
/// <summary>Send phone contacts.</summary>
/// <param name="chatId">
/// Unique identifier for the target chat or username of the target channel (in the format
/// @channelusername)
/// </param>
/// <param name="phoneNumber">Contact's phone number.</param>
/// <param name="firstName">Contact's first name.</param>
/// <param name="lastName">Contact's last name.</param>
/// <param name="disableNotification">
/// If set to <c>true</c> sends the message silently. iOS users will not receive a notification,
/// Android users will receive a notification with no sound.
/// </param>
/// <param name="replyToMessageId">
/// If the message is a reply, ID of the original message.
/// </param>
/// <param name="replyMarkup">
/// Additional interface options. An <see cref="IReply" /> object for a custom reply keyboard,
/// instructions to hide keyboard or to force a reply from the user.
/// </param>
/// <param name="cancellationToken">
/// A <see cref="T:System.Threading.CancellationToken" /> to observe while waiting for the task to
/// complete.
/// </param>
/// <returns>
/// A task that represents the asynchronous operation. The task results contains sent
/// <see cref="Message" /> on success.
/// </returns>
/// <exception cref="System.ArgumentNullException">
/// chatId cannot be null -or- phoneNumber cannot be null -or- firstName cannot be null.
/// </exception>
public Task <Message> SendContactAsync(long chatId, [NotNull] string phoneNumber, [NotNull] string firstName, string lastName = null, bool disableNotification = false, long replyToMessageId = 0, IReply replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendContactAsync(chatId.ToString(), phoneNumber, firstName, lastName, disableNotification, replyToMessageId, replyMarkup, cancellationToken));
}
/// <summary>
/// Unbans a previously kicked user in a supergroup. The user will not return to the group
/// automatically, but will be able to join via link, etc. The bot must be an administrator in the
/// group for this to work.
/// </summary>
/// <param name="chatId">Unique identifier for the target group.</param>
/// <param name="userId">Unique identifier of the target user.</param>
/// <param name="cancellationToken">
/// A <see cref="T:System.Threading.CancellationToken" /> to observe while waiting for the task to
/// complete.
/// </param>
/// <returns>
/// A task that represents the asynchronous operation. The task results contains <c>true</c> on
/// success.
/// </returns>
/// <remarks>
/// Note: This will method only work if the ‘All Members Are Admins’ setting is off in the target
/// group. Otherwise members may only be removed by the group's creator or by the member that added
/// them.
/// </remarks>
/// <exception cref="System.ArgumentNullException">chatId cannot be null.</exception>
/// <exception cref="System.ArgumentException">userId must be a number greater than zero.</exception>
public Task <bool> UnbanChatMemberAsync(long chatId, long userId, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.KickChatMemberAsync(chatId.ToString(), userId, cancellationToken));
}
/// <summary>
/// Sends a photo.
/// </summary>
/// <param name="chatId">Unique identifier for the message recipient.</param>
/// <param name="documentId">A file id as string to resend a photo that is already on the Telegram servers.</param>
/// <param name="caption">Photo caption (may also be used when resending photos by file id).</param>
/// <param name="disableNotification">If set to <c>true</c> sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.</param>
/// <param name="replyToMessageId">If the message is a reply, ID of the original message.</param>
/// <param name="replyMarkup">Additional interface options. An <see cref="IReply" /> object for a custom reply keyboard,
/// instructions to hide keyboard or to force a reply from the user.</param>
/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.</param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
public Task <Message> SendPhotoAsync(long chatId, [NotNull] string documentId, string caption = null, bool disableNotification = false, long replyToMessageId = 0, IReply replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendPhotoAsync(chatId.ToString(), documentId, caption, disableNotification, replyToMessageId, replyMarkup, cancellationToken));
}
/// <summary>
/// Sends an audio file to be displayed as a playable voice message on Telegram clients.
/// </summary>
/// <param name="chatId">Unique identifier for the message recipient.</param>
/// <param name="filePath">Fully qualified path to the audio file.</param>
/// <param name="caption">Voice message caption, 0-200 characters</param>
/// <param name="duration">Duration of sent audio in seconds.</param>
/// <param name="disableNotification">If set to <c>true</c> sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.</param>
/// <param name="replyToMessageId">If the message is a reply, ID of the original message.</param>
/// <param name="replyMarkup">Additional interface options. An <see cref="IReply" /> object for a custom reply keyboard,
/// instructions to hide keyboard or to force a reply from the user.</param>
/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of
/// cancellation.</param>
/// <returns>
/// On success, returns the sent <see cref="Message" />.
/// </returns>
/// <remarks>
/// For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent
/// as <see cref="Audio" /> or <see cref="Document" />). Bots can currently send audio files of up to
/// 50 MB in size, this limit may be changed in the future.
/// </remarks>
public Task <Message> SendVoiceFromFileAsync(long chatId, [NotNull] string filePath, string caption, int duration = 0, bool disableNotification = false, long replyToMessageId = 0, IReply replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendVoiceFromFileAsync(chatId.ToString(), filePath, caption, duration, disableNotification, replyToMessageId, replyMarkup, cancellationToken));
}
/// <summary>Send information about a venue.</summary>
/// <param name="chatId">Unique identifier for the target chat.</param>
/// <param name="latitude">Latitude of the venue.</param>
/// <param name="longitude">Longitude of the venue.</param>
/// <param name="title">Name of the venue.</param>
/// <param name="address">Address of the venue.</param>
/// <param name="forsquareId">Foursquare identifier of the venue.</param>
/// <param name="disableNotification">
/// If set to <c>true</c> sends the message silently. iOS users will not receive a notification,
/// Android users will receive a notification with no sound.
/// </param>
/// <param name="replyToMessageId">
/// If the message is a reply, ID of the original message.
/// </param>
/// <param name="replyMarkup">
/// Additional interface options. An <see cref="IReply" /> object for a custom reply keyboard,
/// instructions to hide keyboard or to force a reply from the user.
/// </param>
/// <param name="cancellationToken">
/// A <see cref="T:System.Threading.CancellationToken" /> to observe while waiting for the task to
/// complete.
/// </param>
/// <returns>
/// A task that represents the asynchronous operation. The task results contains sent
/// <see cref="Message" /> on success.
/// </returns>
public Task <Message> SendVenueAsync(long chatId, float latitude, float longitude, [NotNull] string title, [NotNull] string address, string forsquareId = null, bool disableNotification = false, long replyToMessageId = 0, IReply replyMarkup = null, CancellationToken cancellationToken = default(CancellationToken))
{
Contracts.EnsureNotZero(chatId, nameof(chatId));
return(this.SendVenueAsync(chatId.ToString(), latitude, longitude, title, address, forsquareId, disableNotification, replyToMessageId, replyMarkup, cancellationToken));
}
