Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/greg-kennedy/p5-webservice-discord-webhook

Perl module for posting messages to Discord chat service via Webhook resources.
https://github.com/greg-kennedy/p5-webservice-discord-webhook

discord perl perl-module perl5 webhook

Last synced: 14 days ago
JSON representation

Perl module for posting messages to Discord chat service via Webhook resources.

Awesome Lists containing this project

README 

        
=pod



=head1 NAME



WebService::Discord::Webhook - A module for posting messages to Discord chat service



=head1 VERSION



version 1.10



=head1 SYNOPSIS



    use WebService::Discord::Webhook;



    my $webhook = WebService::Discord::Webhook->new( $url );



    $webhook->get();

    print "Webhook posting as '" . $webhook->{name} .

      "' in channel " . $webhook->{channel_id} . "\n";



    $webhook->execute( content => 'Hello, world!', tts => 1 );



    sleep(30);



    $webhook->execute( 'Goodbye, world!' );



=head1 DESCRIPTION



This module posts messages to the Discord chat service, using their Webhook

interface.  Webhooks are a simple way to add post-only functions to external

clients, without the need to create a full-fledged client or "bot".



Normally, Webhooks are used to issue a notification to chat channels when an

external event from another site or service occurs, e.g. when a commit is made

to a Git repository, a story is posted to a news site, or a player is fragged

in a game.



An example Discord Webhook URL looks like this:



    https://discord.com/api/webhooks/2237...5344/3d89...cf11



where the first magic number ("2237...5344") is the C and the second

("3d89...cf11") is the C.



For more information on Discord Webhooks, see the Discord API documentation

located at L.



=head1 METHODS



=head2 new



Constructs and returns a new WebService::Discord::Webhook object using the

specified parameters.



This function should be passed a hash, containing either a C key, or

C plus C keys, with values matching the Webhook created via the

Discord web UI.



The following optional parameters are also available:



=over



=item * timeout



Override the default timeout of the underlying L object used for

making web requests.



=item * verify_SSL



Enable SSL certificate verification on the underlying L object.

Note that this will probably require a trusted CA certificate list installed.



=item * wait



Webhook execution will block before returning, until the server confirms that

the message was sent.  By default this is disabled (webhook execution is NOT

synchronized), so the function may return success although a message does not

actually post.  See C for more details.



=back



As a special case, if C is called with a scalar parameter, it is assumed

to be a C.



=head2 get



Retrieves server-side information for the Webhook, and caches the result in

the WebService::Discord::Webhook object.  No parameters are expected.



Information which can be returned from the remote service include:



=over



=item * guild_id:

The guild ("server") which the Webhook currently posts to, if set



=item * channel_id:

The specific channel which the Webhook posts to



=item * name:

The current display name of the Webhook



=item * avatar:

A URL pointing to the current avatar used by the Webhook



=back



A hash containing the data is returned.  Additionally, the hash values are

copied into the object itself, so they can be later retrieved by calling code

(as in C<$webhook-E{channel_id}>).



=head2 modify



Modifies the server-side information for the Webhook.  This can be used to

alter the name the Webhook uses, the avatar, or both.



This function should be passed a hash, containing (at least) a

C key or C key (or both).



For C, the value should be the raw data bytes of a png, jpeg, or gif

image.



As a special case, if C is called with a scalar parameter, it is

assumed to be a new username.



The return value for this function is the same as C, and the results are

also cached as above.



=head2 destroy



Deletes the Webhook from the Discord service.  There is no return value.



B  Once a Webhook is deleted, the existing token and ID are no

longer valid.  A server administrator will need to re-create the endpoint

through the Discord UI.  Unless you have very good reason to do this, it is

probably best to leave this function alone.



=head2 execute



Executes a Webhook (posts a message).



The function should be passed a hash containing a Discord webhook

structure.  Discord allows several different methods to post to a channel.

At least one of the following components is required:



=over



=item * content



Post a message to the channel.  The message can be up to 2000 Unicode

characters in length.  Discord may format the message after receipt according

to its usual Markdown rules.



The value should be a scalar containing the message to post.



C can be combined with the other post methods as well, to attach

a message along with an embed or file.



=item * file



Upload a file to the channel.



The value should be a hash reference with two keys: C for the desired

filename, and C for the raw data bytes of the file.  Discord uses

the file extension to determine whether to display it as an image, video,

download, etc.



C cannot be combined with C.



=item * files



Similar to C, but accepts an array of file hashref instead.  (Do not

combine C with C.)



Discord allows up to 10 file attachments in one request.



=item * embed



Post "embedded rich content" to the channel.  This is useful for posting

messages with image attachments, colorful borders or backgrounds, etc.



The value should be an embed object (hashref) to post.  These values are

not checked by WebService::Discord::Webhook.  For information on the expected

data structure, refer to Discord's documentation on Channel Embed Objects:

L



C cannot be combined with C.



=item * embeds



Similar to C, but accepts an array of embed hashref instead.  (Do not

combine C with C.)



=back



Additionally, these optional parameters can be used to change the behavior

of the webhook:



=over



=item * username:

Override the default username of the webhook (i.e. post this message under a

different name).  To make a permanent username change, see C.



=item * avatar_url:

Override the default avatar of the webhook (i.e. post this message using the

avatar at avatar_url).  To upload a new avatar to Discord, see C.



=item * tts:

If set, posts as a TTS message.  TTS messages appear as normal, but will also

be read aloud to users in the channel (if permissions allow).



=item * allowed_mentions:

Customize behavior of pings ("at mentions") in a message.  By default, Discord

will parse the message content looking for users, roles, and groups to notify.

Sometimes this is undesired - for example, when reposting content into the

channel, it would be impolite to let a news summary that includes "@everyone"

to ping the entire channel.  This parameter instructs Discord on how to

correctly parse (or suppress) mentions from the posted message.



The value should be an allowed_mentions object (hashref) to post.  These values

are not checked by WebService::Discord::Webhook.  For details about the data

structure, refer to Discord's documentation on Allowed Mentions Objects:

L



=back



As a special case, if a scalar is passed to this function, it is assumed to

be a regular text message to post via the "content" method.



The return value for this function depends on the setting of C during

webhook construction.  If C is False (default), the function returns

immediately: parameters are checked for validity, but no attempt is made to

verify that the message actually posted to the channel.  There is no return

value in this case.



If C is True, function return is delayed until the message successfully

posts.  The return value in this case is a hashref containing details about

the posted message.



=head2 execute_slack



Executes a Slack-compatible Webhook.



The function should be passed either a scalar (assumed to be the JSON string

contents of the Slack webhook), or a hash containing a Slack webhook

structure (will be encoded to JSON using C).



More information about the format of a Slack webhook is available on the

Slack API reference at L.



This function's return behavior is similar to C, in that it is also

affected by the value of C.  Typically a Slack webhook returns the string

C<"ok"> on success.



=head2 execute_github



Executes a Github-compatible Webhook.



The function should be passed a hash containing two keys: C as the JSON

string of a Github webhook, and C as the string containing the name of

the Github event.  The value for C is passed to Discord in the

C header.



More information about the format of a Github webhook is available on the

Github API reference at L.



This function's return behavior is similar to C, in that it is also

affected by the value of C.



B  Posting a message using the C function is currently

a specially-cased feature of Discord.  The webhook always appears as a user

named "GitHub" with a custom avatar, ignoring any existing styling.  Thus, it

should NOT be used as a general-purpose posting function.  However, it may be

useful to proxy messages from GitHub and repost them on Discord.



=head1 ERRORS



All errors in WebService::Discord::Webhook are handled by throwing exceptions

using C.  This includes both local errors (e.g. invalid parameters)

as well as remote service errors (e.g. upload too large, name invalid).



Errors are returned as a single string.  Some attempt is made to standardize

the wording, so that they can be parsed by regex if the caller wants to inspect

the error and retry or continue.



If you wish to trap errors, the traditional Perl way to catch the exceptions is

to wrap them in an C block, as in:



    my $result = eval {

        $webhook->execute(...);

    };



    if ($@) {

        # do something with the error here

        warn "Execute failed with error: $@";

    }



    # execution continues...



Also consider using L, which provides the familiar C / C

constructs to help with exception handling.



=head1 LICENSE



This is released under the Artistic License.  See L.



=head1 AUTHOR



Greg Kennedy - L