Extensions

Namespace: Signal.Bot

Full Name: Signal.Bot.Extensions

Summary

Provides extension methods for ISignalBotClient to simplify common Signal Bot API operations.

Methods

GetAboutAsync

GetAboutAsync(client, cancellationToken)

Retrieves general information about the Signal Bot API service.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: An About object containing service information.

GetConfigurationAsync

GetConfigurationAsync(client, cancellationToken)

Retrieves the current configuration settings of the Signal Bot API.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Configuration object containing the current settings.

SetConfigurationAsync

SetConfigurationAsync(client, level, cancellationToken)

Updates the logging level configuration of the Signal Bot API.

Parameters:

• client - The ISignalBotClient instance.
• level - The logging level to set (e.g., "debug", "info", "warn", "error").
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

GetDevicesAsync

GetDevicesAsync(client, cancellationToken)

Retrieves all linked devices associated with the bot's Signal account.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A collection of Device objects representing linked devices.

AddDeviceAsync

AddDeviceAsync(client, uri, cancellationToken)

Links a new device to the bot's Signal account using a provisioning URI.

Parameters:

• client - The ISignalBotClient instance.
• uri - The device provisioning URI obtained from the Signal app.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

GetQrCodeLinkAsync

GetQrCodeLinkAsync(client, deviceName, qrCodeVersion, cancellationToken)

Generates a QR code link for linking a new device to the Signal account.

Parameters:

• client - The ISignalBotClient instance.
• deviceName - The name to assign to the new device.
• qrCodeVersion - The QR code version to generate. Default is 10.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A string containing the QR code data or link.

GetRawDeviceLinkAsync

GetRawDeviceLinkAsync(client, deviceName, cancellationToken)

Retrieves the raw device linking information for provisioning a new device.

Parameters:

• client - The ISignalBotClient instance.
• deviceName - The name to assign to the new device.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A RawDeviceLink object containing provisioning details.

RegisterNumberAsync

RegisterNumberAsync(client, captcha, useVoice, cancellationToken)

Initiates the registration process for a phone number with Signal.

Parameters:

• client - The ISignalBotClient instance.
• captcha - Optional CAPTCHA token if required by Signal.
• useVoice - If true, requests a voice call instead of SMS for verification. Default is false.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

VerifyNumberAsync

VerifyNumberAsync(client, token, pin, cancellationToken)

Verifies a phone number registration using the verification code received via SMS or voice call.

Parameters:

• client - The ISignalBotClient instance.
• token - The verification code received from Signal.
• pin - Optional registration PIN if Signal account has PIN enabled.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A string containing the verification result or session information.

UnregisterDeviceAsync

UnregisterDeviceAsync(client, deleteAccount, deleteLocalData, cancellationToken)

Unregisters the current device from Signal and optionally deletes the account and local data.

Parameters:

• client - The ISignalBotClient instance.
• deleteAccount - If true, permanently deletes the Signal account. Default is false.
• deleteLocalData - If true, deletes local data stored by the bot. Default is false.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

GetAccountsAsync

GetAccountsAsync(client, cancellationToken)

Retrieves all registered Signal accounts managed by this bot instance.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A collection of phone numbers representing registered accounts.

SetPinAsync

SetPinAsync(client, pin, cancellationToken)

Sets or updates the registration lock PIN for the Signal account.

Parameters:

• client - The ISignalBotClient instance.
• pin - The PIN to set (typically 4-8 digits).
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

RemovePinAsync

RemovePinAsync(client, cancellationToken)

Removes the registration lock PIN from the Signal account.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

RateLimitChallengeAsync

RateLimitChallengeAsync(client, challengeToken, captcha, cancellationToken)

Completes a rate limit challenge when Signal requires additional verification.

Parameters:

• client - The ISignalBotClient instance.
• challengeToken - The challenge token provided by Signal.
• captcha - The solved CAPTCHA token.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

UpdateAccountSettingsAsync

UpdateAccountSettingsAsync(client, discoverableByNumber, shareNumber, cancellationToken)

Updates the account privacy and discoverability settings.

Parameters:

• client - The ISignalBotClient instance.
• discoverableByNumber - If true, allows others to find this account by phone number. Default is true.
• shareNumber - If true, shares the phone number with contacts. Default is true.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

SetUsernameAsync

SetUsernameAsync(client, username, cancellationToken)

Sets a unique username for the Signal account, allowing others to find you without sharing your phone number.

Parameters:

• client - The ISignalBotClient instance.
• username - The username to set (must be unique across Signal).
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A SetUsername object containing the username confirmation details.

RemoveUsernameAsync

RemoveUsernameAsync(client, cancellationToken)

Removes the username from the Signal account.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

GetGroupsAsync

GetGroupsAsync(client, cancellationToken)

Retrieves all Signal groups that the bot is a member of.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A collection of Group objects.

CreateGroupAsync

CreateGroupAsync(client, createGroupBuilder, cancellationToken)

Creates a new Signal group with specified settings and initial members.

Parameters:

• client - The ISignalBotClient instance.
• createGroupBuilder - An action to configure the group creation using CreateGroupBuilder.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Group object representing the newly created group.

GetGroupAsync

GetGroupAsync(client, groupId, cancellationToken)

Retrieves detailed information about a specific Signal group.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Group object containing the group details.

UpdateGroupAsync

UpdateGroupAsync(client, groupId, updateGroupBuilder, cancellationToken)

Updates the settings of an existing Signal group.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group to update.
• updateGroupBuilder - An action to configure the group updates using UpdateGroupBuilder.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

RemoveGroupAsync

RemoveGroupAsync(client, groupId, cancellationToken)

Deletes a Signal group. Only group administrators can perform this action.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group to delete.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

AddGroupAdminAsync

AddGroupAdminAsync(client, groupId, admins, cancellationToken)

Promotes one or more group members to administrator status.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group.
• admins - The phone numbers of members to promote to admin.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

RemoveGroupAdminAsync

RemoveGroupAdminAsync(client, groupId, admins, cancellationToken)

Removes administrator privileges from one or more group admins.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group.
• admins - The phone numbers of admins to demote.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

BlockGroupAsync

BlockGroupAsync(client, groupId, cancellationToken)

Blocks all messages from a specific Signal group.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group to block.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

JoinGroupAsync

JoinGroupAsync(client, groupId, cancellationToken)

Joins an existing Signal group using a group link or invitation.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group to join.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

AddGroupMemberAsync

AddGroupMemberAsync(client, groupId, members, cancellationToken)

Adds one or more members to a Signal group.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group.
• members - The phone numbers of members to add to the group.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

RemoveGroupMemberAsync

RemoveGroupMemberAsync(client, groupId, members, cancellationToken)

Removes one or more members from a Signal group.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group.
• members - The phone numbers of members to remove from the group.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

QuitGroupAsync

QuitGroupAsync(client, groupId, cancellationToken)

Leaves a Signal group, removing the bot from the member list.

Parameters:

• client - The ISignalBotClient instance.
• groupId - The unique identifier of the group to leave.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

RemoteDeleteAsync

RemoteDeleteAsync(client, recipient, timestamp, cancellationToken)

Remotely deletes a message from the conversation for all participants.

Parameters:

• client - The ISignalBotClient instance.
• recipient - The phone number or group ID where the message should be deleted.
• timestamp - The timestamp of the message to delete. If null, uses current UTC time.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: An Acknowledged response confirming the deletion request.

SetTypingIndicatorAsync

SetTypingIndicatorAsync(client, recipient, groupId, isTyping, cancellationToken)

Sends or removes a typing indicator to show that the bot is composing a message.

Parameters:

• client - The ISignalBotClient instance.
• recipient - The phone number of the recipient to send the typing indicator to.
• groupId - The group ID if sending the typing indicator to a group.
• isTyping - If true, shows typing indicator; if false, removes it. Default is true.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

SendMessageAsync

SendMessageAsync(client, recipient, message, cancellationToken)

Sends a simple text message to a recipient.

Parameters:

• client - The ISignalBotClient instance.
• recipient - The phone number or group ID of the recipient.
• message - The text message to send.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: An Acknowledged response confirming the message was sent.

Exceptions:

• System.ArgumentException - Thrown when recipient or message is null or whitespace.

SendMessageAsync

SendMessageAsync(client, messageBuilder, cancellationToken)

Sends a message with advanced configuration options such as attachments, mentions, and formatting.

Parameters:

• client - The ISignalBotClient instance.
• messageBuilder - An action to configure the message using SendMessageRequestBuilder.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: An Acknowledged response confirming the message was sent.

GetAttachmentsAsync

GetAttachmentsAsync(client, cancellationToken)

Retrieves a list of all attachment IDs stored by the bot.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A collection of attachment ID strings.

GetAttachmentAsync

GetAttachmentAsync(client, attachmentId, cancellationToken)

Downloads an attachment as a byte array.

Parameters:

• client - The ISignalBotClient instance.
• attachmentId - The unique identifier of the attachment to download.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A byte array containing the attachment data, or an empty array if the request fails.

Exceptions:

• System.ArgumentException - Thrown when attachmentId is null or whitespace.

GetAttachmentStreamAsync

GetAttachmentStreamAsync(client, attachmentId, cancellationToken)

Downloads an attachment as a stream for efficient memory usage with large files.

Parameters:

• client - The ISignalBotClient instance.
• attachmentId - The unique identifier of the attachment to download.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Stream containing the attachment data.

Exceptions:

• System.ArgumentException - Thrown when attachmentId is null or whitespace.

RemoveAttachmentAsync

RemoveAttachmentAsync(client, attachmentId, cancellationToken)

Deletes an attachment from the bot's storage.

Parameters:

• client - The ISignalBotClient instance.
• attachmentId - The unique identifier of the attachment to delete.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

UpdateProfileAsync

UpdateProfileAsync(client, name, about, avatar, cancellationToken)

Updates the bot's Signal profile information including name, about text, and avatar image.

Parameters:

• client - The ISignalBotClient instance.
• name - The display name to set for the profile.
• about - The about/status text to set for the profile.
• avatar - The avatar image as a byte array (JPEG or PNG format recommended).
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

GetIdentitiesAsync

GetIdentitiesAsync(client, cancellationToken)

Retrieves all known identity keys for contacts, used for verifying end-to-end encryption.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A collection of Identity objects containing identity key information.

TrustIdentityAsync

TrustIdentityAsync(client, verifiedNumber, trustAllKnownKeys, verifiedSafetyNumber, cancellationToken)

Marks a contact's identity key as trusted after verifying their safety number.

Parameters:

• client - The ISignalBotClient instance.
• verifiedNumber - The phone number of the contact whose identity is being verified.
• trustAllKnownKeys - If true, trusts all known keys for this contact. Default is null.
• verifiedSafetyNumber - The safety number to verify, obtained through QR code or manual comparison.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

AddReactionAsync

AddReactionAsync(client, reaction, recipient, targetAuthor, timestamp, cancellationToken)

Adds an emoji reaction to a specific message.

Parameters:

• client - The ISignalBotClient instance.
• reaction - The emoji to react with (e.g., "👍", "❤️", "😂").
• recipient - The phone number or group ID of the conversation.
• targetAuthor - The phone number of the message author.
• timestamp - The timestamp of the message to react to. If null, uses current UTC time.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

RemoveReactionAsync

RemoveReactionAsync(client, reaction, recipient, targetAuthor, timestamp, cancellationToken)

Removes an emoji reaction from a specific message.

Parameters:

• client - The ISignalBotClient instance.
• reaction - The emoji reaction to remove (e.g., "👍", "❤️", "😂").
• recipient - The phone number or group ID of the conversation.
• targetAuthor - The phone number of the message author.
• timestamp - The timestamp of the message. If null, uses current UTC time.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A string containing the result of the removal operation.

SendReceiptAsync

SendReceiptAsync(client, recipient, timestamp, receiptType, cancellationToken)

Sends a read receipt, delivery receipt, or viewed receipt for a message.

Parameters:

• client - The ISignalBotClient instance.
• recipient - The phone number of the message sender.
• timestamp - The timestamp of the message. If null, uses current UTC time.
• receiptType - The type of receipt to send (Read, Delivery, or Viewed). Default is Read.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

SearchNumbersAsync

SearchNumbersAsync(client, numbers, cancellationToken)

Searches for Signal users by their phone numbers to check if they are registered on Signal.

Parameters:

• client - The ISignalBotClient instance.
• numbers - The phone numbers to search for (in international format).
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A collection of Search objects containing registration status for each number.

GetStickerPacksAsync

GetStickerPacksAsync(client, cancellationToken)

Retrieves all sticker packs installed or available to the bot.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A collection of StickerPack objects.

AddStickerPackAsync

AddStickerPackAsync(client, packId, packKey, cancellationToken)

Installs a sticker pack to the bot's account using the pack ID and decryption key.

Parameters:

• client - The ISignalBotClient instance.
• packId - The unique identifier of the sticker pack.
• packKey - The decryption key for the sticker pack.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

GetContactsAsync

GetContactsAsync(client, cancellationToken)

Retrieves all contacts stored in the bot's Signal account.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A collection of Contact objects.

UpdateContactAsync

UpdateContactAsync(client, recipient, name, expirationTimeInSeconds, cancellationToken)

Updates contact information including display name and disappearing message timer.

Parameters:

• client - The ISignalBotClient instance.
• recipient - The phone number of the contact to update.
• name - The display name to set for this contact.
• expirationTimeInSeconds - The disappearing message timer in seconds (0 to disable).
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

SyncContactsAsync

SyncContactsAsync(client, cancellationToken)

Synchronizes the local contact list with Signal's servers to update profile information and registration status.

Parameters:

• client - The ISignalBotClient instance.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Task representing the asynchronous operation.

GetContactAsync

GetContactAsync(client, contactId, cancellationToken)

Retrieves detailed information about a specific contact.

Parameters:

• client - The ISignalBotClient instance.
• contactId - The phone number or unique identifier of the contact.
• cancellationToken - A CancellationToken to observe for cancellation requests.

Returns: A Contact object containing the contact's details.