File Coverage

blib/lib/SMS/MessageBird/API/Voice.pm
Criterion Covered Total %
statement 9 21 42.8
branch 0 4 0.0
condition n/a
subroutine 3 8 37.5
pod 5 5 100.0
total 17 38 44.7


line stmt bran cond sub pod time code
1             package SMS::MessageBird::API::Voice;
2              
3 2     2   7 use strict;
  2         2  
  2         42  
4 2     2   5 use warnings;
  2         2  
  2         35  
5              
6 2     2   5 use parent 'SMS::MessageBird::API';
  2         2  
  2         7  
7              
8             =head1 NAME
9              
10             SMS::MessageBird::API::Voice - Sub-module for the SMS::MessageBird distribution.
11              
12              
13             =head1 SYNOPSIS
14              
15             This is a sub-module which is part of the SMS::MessageBird distribution.
16              
17             While this module can be used directly, it's designed to be used via
18             L
19              
20              
21             =head1 DESCRIPTION
22              
23             This module provides the interface to the Text-to-Voice SMS related methods of
24             the MessageBird JSON API.
25              
26             The methods implmented acceept the paramteres as named in the MessageBird API
27             documentation which can be found at the L.
28             If you're using this distribution you should be familiar with the API
29             documentation.
30              
31             =head2 Response Data
32              
33             Every method returns a standardised hashref containin the following keys:
34              
35             =over
36              
37             =item ok
38              
39             Value of 0 or 1. Indicates if the request was completed successfully or not.
40             This value is based on LWP::UserAgent's is_success() method.
41              
42             =item code
43              
44             This is the HTTP code returned by the API. In the event of ok => 0 - it's
45             possible that the request was a 401 etc. So this is provided for sanity
46             checking.
47              
48             =item content
49              
50             This is a Perl hashref data structure decoded from the API's response JSON
51             as-is.
52              
53             Please see the L
54             for more information on the expected structure.
55              
56             =back
57              
58             =head2 Text-to-Voice formatting.
59              
60             Text-to-Voice SMS can be tweeked to alter the speed of reading and add delays
61             in the spoken text. Please see the "The Voice Body" section of the
62             L
63             for more information.
64              
65              
66             =head1 METHODS
67              
68              
69             =head2 send
70              
71             In: %params - Hash of params accepted by the MessageBird API.
72             Out: $response - Hashref of response data. See "Response Data" above.
73              
74             This method implements the POST /voicemessages route of the API.
75              
76             Accepted parameters are listed in the MessageBird API documentation.
77              
78             Require parameters are as follows:
79              
80             =over
81              
82             =item originator
83              
84             The originator parameter is required but can be omitted if set when
85             instantiating the SMS::MessageBird module.
86              
87             =item recipients
88              
89             The recipients parameter is required and can be either a scalar containing a
90             single MSISDN (mobile number) or an arrayref containing many recipients.
91              
92             =item body
93              
94             The body parameter is required. Scalar containing the text of the message.
95              
96             Text-to-Voice SMS can be tweeked to alter the speed of reading and add delays
97             in the spoken text. Please see the "The Voice Body" section of the
98             L
99             for more information.
100              
101             =back
102              
103             All other parameters are optional.
104              
105             Please see the L
106             for more information.
107              
108             =cut
109              
110             sub send {
111 0     0 1   my ($self, %params) = @_;
112              
113 0           return $self->_api_request(
114             post => '/voicemessages',
115             \%params
116             );
117             }
118              
119              
120             =head2 receive
121              
122             In: $voice_mesasge_id - Optional ID of the voice message to recieve.
123             Out: $response - Hashref of response data. See "Response Data" above.
124              
125             This method implements the GET /voicemessages/{voice_message_id} route of the
126             API.
127              
128             If supplied with a $voice_message_id, that one message will be returned. If
129             omitted, a complete list of messages will be returned.
130              
131             Please see the L
132             for more information.
133              
134             =cut
135              
136             sub receive {
137 0     0 1   my ($self, $voice_message_id) = @_;
138              
139 0 0         my $route = ($voice_message_id) ? "/voicemessages/$voice_message_id"
140             : '/voicemessages';
141              
142 0           return $self->_api_request( get => $route );
143             }
144              
145              
146             =head2 get
147              
148             Synonym for the L method.
149              
150             =cut
151              
152             sub get {
153 0     0 1   my ($self, $voice_message_id) = @_;
154 0           return $self->receive($voice_message_id);
155             }
156              
157              
158             =head2 remove
159              
160             In: $voice_message_id - The voice message_id to remove.
161             Out: $response - Hashref of response data. See "Response Data" above.
162              
163             This method implements the DELETE /voicemessages/{message_id} route of the API.
164              
165             Deletes the SMS with identifier $message_id.
166              
167             Please see the L
168             for more information.
169              
170             =cut
171              
172             sub remove {
173 0     0 1   my ($self, $voice_message_id) = @_;
174              
175 0 0         return $self->_no_param_supplied('voice message ID') if !$voice_message_id;
176              
177 0           return $self->_api_request( delete => "/voicemessages/$voice_message_id" );
178             }
179              
180              
181             =head2 del
182              
183             Synonym for the L method.
184              
185             =cut
186              
187             sub del {
188 0     0 1   my ($self, $voice_message_id) = @_;
189 0           return $self->remove($voice_message_id);
190             }
191              
192              
193             =head1 AUTHOR
194              
195             James Ronan, C<< >>
196              
197             =head1 BUGS
198              
199             Please report any bugs or feature requests to C,
200             or through the web interface at L.
201             I will be notified, and then you'll automatically be notified of progress on your
202             bug as I make changes.
203              
204             Alternatively you can raise an issue on the source code which is available on
205             L.
206              
207             =head1 LICENSE AND COPYRIGHT
208              
209             Copyright 2016 James Ronan.
210              
211             This library is free software; you can redistribute it and/or modify it under
212             the same terms as Perl itself.
213              
214             =cut
215              
216             1;
217