Lyric API Web Documentation 0.08

7/26/2019 Lyric API Web Documentation 0.08

1/17


2/17

v0.06

Added function api_reset_queue Fixed an issue with the function api_sms_available_spacethat wouldn't return the real available

space Fixed documentation of functions that use the sms_dir parameter (previously it showed dir

instead of sms_dir)

v0.05

Fixed function api_reset_sent_counternot setting counters to 0 permanently Added the following functions:

api_recv_number_unread

api_recv_get_first_n_unread

api_recv_get_last_n_unread

api_sms_delete_by_status

api_sms_delete_by_id

api_sms_available_space

Added optional parameter set_readto functions api_recv_get_first_nand api_recv_get_last_n

v0.04

Added function api_get_channels_status Added function api_reset_sent_counter

v0.03

Added optional parameter channelto function api_queue_sms Added optional parameter channelto function api_get_status

Added the following functions

api_sms_send_disable

api_sms_send_enable

Parameter Enconding and Supported Characters

As it was stated in the introduction, the encoding used for the parameters is UR !RF" #$%& with the additionof ()*s that may be used for spaces+

he characters currently supported are the following:

-./123456789;?@B'!CD),E+0GH#IJ&K%$:LMNOPQA"STFVWXYTZ[\]^R_U`jabcdefghiklemnoprstuvwxyq

"haracters lie and z are excluded on purpose, because the use of these would truncate the maximum_Z_ length to K0 characters !from G&0+

Web API Commands

Zost of the following commands reuire authentication with the web server+ he parameters used forauthentification are:

username: Username for _Z_ A]W service authentication


3/17

password: ]assword for _Z_ A]W service authentication

apiversion: eb A]W version used by the client

he api_versionspecified must match the one supported by the firmware version installed on the device+ heexamples encountered through the documentation use (webuser* as usernameand (webpass* aspassword+

he details of each command will indicate if it reuires the authentication parameters or not along its own

parameters+

api!ueuesms"

#escription" ^ueues the text message indicated in the uery parameters and returns a ticetassociated with the _Z_+ his ticet can be used later to as for the delivery status of themessage

Parameters" content: "ontent of the test message in UR formatdestination: _Z_ destination number

channel !optional: "hannel that should send the message !G to &+ Wf not specified,the message will be sent by any enabled channel

Auth" es

$eturns" he result !in X_\[ format of the function contains the following elements:

success: G: Zessage was succesfully inserted in the device database

0: An error ocurred

messageid: icet of the ueued message+ Wf an error ocurred, this fieldwon't be present on the response

errorcode: \nly if an error ocurred+ _ee error codes section

E%amp&e" ^uery:

http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapiueuesmsBusernameNlyricapiBpasswordNlyricapiBcontentN_Z_)"ontentBdestinationNJJJJJJJJBapiversionN0+0%BchannelNH

Answer:

{ CsuccessC: true, CmessageidC: J |

apigetstatus"

#escription" Retrieves the status of the message associated with the ticet indicated in theparameters


4/17

Parameters" messageid: icet of the message to be ueried

channel !optional: et status for message associated with this channel+ Wf notspecified, the status returned will be from messages belonging tothe general ueue

Auth" es


success: G: Zessage status was retrieved succesfully0: An error ocurred

messagestatus: Wf an error ocurred, this field won't be present on the response+ 0: [ew G: ]rocessing H: _ent #: Failure

lasterror: Wf an error ocurred, this field won't be present on the response+ 0: [one G: Unnown H: Sestination number #: "ontent I: [etwor, temporal J: _imcard

ntries: [umber of failed attempts to send the message

num: Sestination number of the message

channel: ast channel that attempted to send the message, successfully ornot

senddate: Sate in seconds from epoch when the message was sent

recvdate: Sate in seconds from epoch when the message was ueued

reportstage: ]ossible values are:0: [o status report has been received yet

G: emporary status report+ Zore reports should beexpected to arrive+H: Final status report+ Final report received for thismessage+

deliverystatus: _tatus code contained in the report+ ]ossible values are:0: Zessage deliveredG: Zessage forwarded by the _" but unable to confirmdeliveryH: Zessage replaced by the _"#H: "ongestion#J: _ervice rekectedI%: _pecific to each _"&J: Wncompatible destination

deliverydate: Sate of the last status report received for the message

errorcode: _ee error codes section


5/17

E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapigetstatusBusernameNlyricapiBpasswordNlyricapiBmessageidNJBapiversionN0+0%BchannelNG

Answer:{ CsuccessC: true, CmessagestatusC: H, CnumC: C%I0KH&&&C, CchannelC: G, ClasterrorC: 0,CntriesC: 0, CsenddateC: CG##&JHG$G&C, CrecvdateC: CG##&JHG%J%C, CreportstageC:CHC,CdeliverystatusC:C0C, CdeliverydateC:CG##&JHHIC |

apigetchanne&sstatus"

#escription" Retrieves the status !a part of it on this version of all the available channel

Parameters" [o additional parameters reuired

Auth" es


success: G: _tatus of the channels retrieved successfully0: An error ocurred


channels: A X_\[ array with the following info for each element !channel:

id: [umeric channel id !from G to &

smssendena: G if sms delivery is enabled, 0 if not

state: _tring indicating the channel status

imsi: Wf state >N (disabled* and state >N(nosimcard*,

WZ_W of the simcardnsentsms: _ame conditions as imsi+ [} _Z_s sent by the

simcard

E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapigetchannelsstatusBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%

Answer:{ CsuccessC: true, CchannelsC: { CidC: G, CsmssendenaC: G, CstateC: CregisteredC, CimsiC:CK#00GGJJJJJJJJC, CnsentsmsC: J |, { CidC: H, CsmssendenaC: 0, CstateC: CregisteredC,CimsiC: CK#00GG&&&&&&&&C, CnsentsmsC: 0 | z |

apiget!ueuestatus"

#escription" \btains the status of the specified ueue+ Wt's not recommended to use this functionfreuently, since it checs the whole ueue and may lower performance on A]W webintensive applications+


6/17

Parameters" channel !optional: et status for ueue associated with this channel+ Wf notspecified, the status returned will be from the general ueue

Auth" es


success: G: Zessage status was retrieved succesfully0: An error ocurred

nmsgs: [umber of messagges on the ueue

nnew: [umber of messages mared as (new*

nproc: [umber of messages currently being processed

nsent: [umber of messages that were sent

nfail: [umber of messages mared as (failed*

errorcode: _ee error codes section

E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapigetueuestatusBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BchannelNG

Answer:{ CsuccessC: true, CnmsgsC: I, CnnewC: 0, CnprocC: 0, CnsentC: I, CnfailC: 0 |

apiresetsentcounter"

#escription" Resets the _Z_ sent counter for the simcard of the WZ_W or channel specified

Parameters" imsi: WZ_W of the target simcard, or

channel: "hannel where the target simcard is inserted

Auth" es


success: G: "ounter was reseted successfully

0: An error ocurred


E%amp&e" ^uery:

http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapiresetsentcounterBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BchannelN#

Answer:

{ CsuccessC: true |


7/17

apigetversion"

#escription" Returns the eb A]W version supported by the device


Auth" [o

$eturns" he result !in X_\[ format of the function contains the following element:

apiversion: eb A]W version supported by the device

E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapigetversion

Answer:{ CapiversionC: C0+0&C |

apigetnumberrecvsms"

#escription" \btains the number of received messages


Auth" es


success: G: [umber of received messages obtained succesfully0: An error ocurred

nsms: Wf no error ocurred, this field will be present on the responsecontaining the number of received messages

errorcode: ]resent when success field is 0+ _ee error codes section

E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapigetnumberrecvsmsBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%

Answer:{ CsuccessC: true, CnsmsC: J00 |

apirecvgetnumberunread"


8/17

#escription" \btains the number of unread received messages


Auth" es


success: G: [umber of unread received messages obtained succesfully

0: An error ocurrednunread: Wf no error ocurred, this field will be present on the response

containing the number of unread received messages


E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapirecvgetnumberunreadBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%

Answer:{ CsuccessC: true, CnunreadC: G% |

apirecvget'irstn"

#escription" \btains the first [ received messages

Parameters" nregs: [umber of messages to retrievesetread !optional: G: Zar messages retrieved as read

0: eave the messages as they are !default

Auth" es


9/17


success: G: \btained all or part of the messages succesfully0: An error ocurred

nread: Wf no error ocurred, this field will be present and contain thenumber of messages succesfully read from the device

regarray: A X_\[ array containing the messages+ Tach message has thefollowing structure:

id: Zessage WS

senddate: Sate on which the message was sent

recvdate: Sate on which the message was received

readdate: Sate on which the message was read

numorig: \rigin number of the message

message: "ontent of the message

status: (0* means unread, (G* means message read

channel: Sevice channel that received the message !D

imsi: Wmsi that received the message !D


E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapirecvgetfirstnBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BnregsNG

Answer:{ CsuccessC: true, CnreadC: G, (regarray*: { (id*: HJ, (senddate*: (H0G0EG0EH0G#:0J:0G*, (recvdate*: (H0G0EG0EH0 G#:0J:J0*, (readdate*: (E*, (numorig*:(GH#IGH#I*, (message*: (hi, how are youP*, (status*: 0, (channel*: &, (imsi*:(GH#IGH#IGH#I* | z |

!D _ome messages may have channel (EG* and an empty imsi if they were received by any simcard on a yric `oW] device with firmware

version below `0+H0G

apirecvget'irstnunread"

#escription" \btains the first [ unread received messages

Parameters" nregs: [umber of messages to retrieve

setread: G: Zar messages retrieved as read0: eave the messages as they are

Auth" es


10/17





id: Zessage WS










E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapirecvgetfirstnBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BnregsNG




apirecvget&astn"

#escription" \btains the last [ received messages


setread !optional: G: Zar messages retrieved as read0: eave the messages as they are !default

Auth" es


11/17





id: Zessage WS










E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapirecvgetlastnBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BnregsNG




apirecvget&astnunread"

#escription" \btains the last [ unread received messages


setread: G: Zar messages retrieved as read0: eave the messages as they are

Auth" es


12/17





id: Zessage WS










E%amp&e" ^uery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapirecvgetlastnBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BnregsNG




apirecvsetread"

#escription" _ets a message as read and its read date to the moment it is set

Parameters" id: Wd of the message to be set read

Auth" es


success: G: Zessage set read succesfully0: An error ocurred



13/17

E%amp&e" ûery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapirecvsetreadBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BidNK

Answer:{ CsuccessC: true |

apismssendenab&e"

#escription" Tnables the specified channels for _Z_ delivery

Parameters" chanlist: "omma separated list of channels to be enabled

Auth" es


success: G: "hannels were enabled successfully0: An error ocurred


E%amp&e" ûery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapismssendenableBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BchanlistNG,H,#


apismssenddisab&e"

#escription" Sisables the specified channels for _Z_ delivery

Parameters" chanlist: "omma separated list of channels to be disabled

Auth" es


success: G: "hannels were disabled successfully0: An error ocurred


E%amp&e" ûery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapismssenddisableBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BchanlistNG,H,#



14/17

apismsde&eteb(status"

#escription" Seletes the messages matching the specified state from the specified ueue

Parameters" smsdir: in: ueue of the received messages

out: ueue of the outgoing messages

channel !out: _pecifies the target channel ueue !G to &+ Wf not specified, it'lluse the general ueue for outgoing messages

status: unread !in: deletes unread messages

read !in: deletes read messages

new !out: deletes pending messages

sent !out: deletes sent messages

failed !out: deletes messages that failed to be sent

any !in or out: deletes messages matching any status

Auth" es


success: G: Zessage were deleted successfully

0: An error ocurred


E%amp&e" ^uery:

http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapismsdeletebystatusBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BsmsdirNoutBchannelNJBstatusNsent

Answer:

{ CsuccessC: true |

apismsde&eteb(id"

#escription" Seletes the message matching the specified id from the specified ueue




id: Wd of the message at the specified ueue


15/17

Auth" es



0: An error ocurred


E%amp&e" ^uery:

http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapismsdeletebystatusBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BsmsdirNinBidNG0G

Answer:

{ CsuccessC: true |

apismsavai&ab&espace"

#escription" Returns the remaining available space on the specified ueue




Auth" es



0: An error ocurred


navailable: [umber of messages that can be inserted in the ueue beforeoverwritting the oldest message

E%amp&e" ^uery:

http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapismsavailablespaceBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BsmsdirNout

Answer:

{ CsuccessC: true, (navailable*: I00 |


16/17

apireset!ueue"

#escription" Seletes all messages from ueue if there's no message in the (]rocessing* state




Auth" es


success: G: ueue was resetted succesfully

0: An error ocurred


E%amp&e" ûery:http:webuser:webpass-G$H+G&%+H00+G0cgiEbinexecPcmdNapiresetueueBusernameNlyricapiBpasswordNlyricapiBapiversionN0+0%BsmsdirNoutBchannelNJ

Answer:

{ CsuccessC: true |

Error Codes

C)#E #ESC$IP*I)+Satabase]roblem Sevice database couldn't be accessedA]WSisabled eb A]W is disabledSestinationTmpty _Z_ destination was not specified"ontentTmpty "ontent was not specifiedUsernameTmpty Username was not specified]asswordTmpty ]assword was not specifiedA]WèrsionTmpty A]W version was not specifiedadSestination Sestination must be a numeric value

adUser]assword Wncorrect username or passwordadApièrsion Wncorrect A]W versionUnix_ocet]roblem "onnection to unix socet failedAppAnswer]roblem Application does not answerApp[otification]roblem Application answer has errorsZessageWdTmpty Zessage ticet was not specifiedSatabase]roblem\RWd[otFound Satabase couldn't be accessed or ticet does not existSevice[otReady Sevice hasn't initiated completly yetrong"hannel "hannel specified is invalidZissing"hannelist A comma separated list must be specified


17/17

_etReadTmpty Sidn't specify whether to set messges as read or notrong_Z_Sir Xust (in* or (out* is accepted[o_Z_Sir smsdir parameter was not specified"hannel[otReuired _pecified channel for the received _Z_ ueueZissing_tatus _tatus parameter was not specified_tatusrog _tatus parameter is different from (in* or (out*ogTrror Wnternal error while trying to access a ueue"hannel[otWnitialied _pecified channel is not initialied

Wmsi[otFound _pecified imsi couldn't be found^ueue]roblem ^ueue nonexistent or unown ueue related error

$e'erences

Gz http:www+kson+orgHz http:tools+ietf+orghtmlrfc#$%z http:www+python+orgftppythonH+KpythonEH+K+msi !for indowsIz http:www+yx+clsoporte+html

Documents

Lyric API Web Documentation 0.08