TWW UNIMESSAGE. Volume SMS Messaging. Web services Integration Guide ( Version 3.09 )

Transcription

1 TWW UNIMESSAGE Volume SMS Messaging Web services Integration Guide ( Version 3.09 ) 1

2 TWW UNIMESSAGE Volume SMS Messaging WEBSERVICES Integration Guide Information in this document, or in the described system, including URL and other internet Web Site and IP references, is subject to change without notice. Complying with all applicable copyright laws is responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means ( electronic, mechanical, photocopying, or otherwise ), or for any purpose, without express written permission of TWW do Brasil S.A. TWW may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from TWW, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Author: Carlos A A Moura TWW do Brasil S A 2

3 Unimessage Volume Messaging Web Connection The UNIMESSAGE Web Services service permits Volume message sending thru the WEB. The UNIMESSAGE Web Services has a command set that offers: Unique SMS sending Batch SMS sending SMS Status verification Message report etc. UNIMESSAGE Web Services System Integration At the URL: is a command list with a short description and parameters. You can consult the command list, Post / Get / Soap examples, and do some tests thru a web browser like MS Internet Explorer or Mozilla Firefox. The WSDL with the methods descriptions could be downloaded through the following URL: Notes: You should inform your server IP address to be able to access the TWW UNIMESSAGE WebservicesURL. It s necessary to have login and password to use these commands. Please ask our Sales Department for an account. 3

4 Address URL: IP: Port: 80 URL: IP: Port: 443 TWW Unimessage CAP WEB Page: 4

5 Available Commands: AlteraSenha - Changes a user password. The password maximum length is 18 characters. Returns a Boolean that indicates transaction success. Fields needed: SenhaAntiga Old Password SenhaNova New Password BuscaSMSAgenda - Returns a DataSet named OutDataSet that contains one scheduled message for the SeuNum informed, at a time Fields needed: SeuNum This field is a number or alphanumeric character chain with 10 characters that is generated by the user for future queries. It s not necessary to be ordered and could be repeated Returned dataset example: <?xml version="1.0" encoding="utf-8"?> - <DataSet xmlns=" - <xs:schema id="outdataset" xmlns="" xmlns:xs=" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> - <xs:element name="outdataset" msdata:isdataset="true" msdata:usecurrentlocale="true"> - <xs:complextype> - <xs:choice minoccurs="0" maxoccurs="unbounded"> 5

6 - <xs:element name="buscasmsagenda"> - <xs:complextype> - <xs:sequence> <xs:element name="seunum" type="xs:string" minoccurs="0" /> <xs:element name="celular" type="xs:string" minoccurs="0" /> <xs:element name="mensagem" type="xs:string" minoccurs="0" /> <xs:element name="status" type="xs:string" minoccurs="0" /> <xs:element name="datarec" type="xs:datetime" minoccurs="0" /> <xs:element name="dataenv" type="xs:datetime" minoccurs="0" /> <xs:element name="datastatus" type="xs:datetime" minoccurs="0" /> </xs:sequence> </xs:complextype> </xs:element> </xs:choice> </xs:complextype> </xs:element> </xs:schema> - <diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1"> - <OutDataSet xmlns=""> - <BuscaSMSAgenda diffgr:id="buscasmsagenda1" msdata:roworder="0"> <seunum>abc123</seunum> <celular> </celular> <mensagem>teste agendamento ws</mensagem> <status>ok</status> <datarec> t14:55: :00</datarec> <dataenv> t10:00:00-02:00</dataenv> <datastatus> t14:55: :00</datastatus> </BuscaSMSAgenda> </OutDataSet> </diffgr:diffgram> </DataSet> *Note - After making a search, wait one minute to make a new search 6

7 BuscaSMSAgendaDataset - Returns a DataSet named OutDataSet that contains a table called BuscaSMSAgenda with the scheduled messages. Returns Nothing in case of errors. Fields needed: *Note - After making a search, wait one minute to make a new search BuscaSMSMONaoLido - Returns a DataSet named OutDataSet that contains a table called SMSMO with 400 lines at maximum, containing the unread MO messages received in the last 4 days, as answers for SMSs sent by the system, and mark these messages as read. If the resulting table has 400 lines, it should be possible that there are more unread messages available, and these should be read invoking the method again until there are no more unread messages. Returns Nothing in case of errors. Fields needed: *Note - After making a search, wait one minute to make a new search *Note - To do the same search in this method, first need make a reset and after that wait one minute DelSMSAgenda - Deletes a scheduled message. Returns OK or NOK. Fields needed: Agendamento - DATETIME type, ANSI formatted YYYY-MM-DD HH:MM:SS. SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. 7

8 EnviaSMS - Sends unique SMSs. The necessary fields are: SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Celular - (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem ASCII Text (140 char. Maximum size). ASCII between ASCII-32 e ASCII-126 would be accepted (Characters out of this range will be changed.) Returns a string with the following values: OK Message accepted for transmission NOK Message not accepted for transmission or financial pendings Erro - Error NA (not available) System unavailable EnviaSMS2SN - Sends unique SMSs and offers 2 numeric custom reference fields (SeuNum1 and SeuNum2) with a maximum of 20 digits each. Returns OK, NOK(financial pendings, etc), Erro (Error) or NA (not available) SeuNum1 - This is a numeric field with a maximum of 20 digits that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. SeuNum2 - This is a numeric field with a maximum of 20 digits that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. 8

9 Celular - (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem ASCII text ( X characters maximum ) Agendamento - (Scheduling) DATETIME ANSI format: YYYY-MM-DD HH:MM:SS. EnviSMSAge Schedules a message to be sent in a scheduled time. Returns OK, NOK(financial pendings, etc), Erro (Error) or NA (not available) SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem (Message Text) - ASCII Text (140 char. Maximum size). ASCII between ASCII-32 e ASCII-126 would be accepted (Characters out of this range will be changed.) Agendamento (Scheduling) DATETIME ANSI format: YYYY-MM- DD HH:MM:SS. EnviSMSAgeQuebra - Schedules a message to be sent in a scheduled time. If a message was greater than 140 characters, it will be split into multiple messages of 140 characters each with "..." separating the messages. The maximum text length is 4096 characters. Returns OK, NOK(financial pendings, etc), Erro (Error) or NA (not available) SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the 9

10 message, for future queries. It s not necessary to be ordered, and could be repeated. Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem (Message Text) - ASCII Text (4096 char. Maximum size). ASCII between ASCII-32 e ASCII-126 would be accepted (Characters out of this range will be changed.) If a message was greater than 140 characters, it will be split into multiple messages of 140 characters each with "..." separating the messages. The maximum text length is 4096 characters. Agendamento (Scheduling) DATETIME ANSI format: YYYY-MM-DD HH:MM:SS. EnviaSMSAlt Send a message to a mobile phone using url alternative. *Note discontinued function, please use function EnviaSMS EnviaSMSConcatenadoComAcento - Sends a concatenated accented text SMS message. The "Serie" field should contain a number between 0 and 255 that should be unique for each concatenated SMS sent, being increased by 1 at each sent message and when reaches 255 start again with 0 ( zero ). If this message has more than 70 characters, it will be split in several messages with 70 characters each and received in form of a concatenated unique message at the mobile phone, only if the destination operator supports concatenation. If there is no support for concatenation at the destination operator, the messages will be sent with +" in the beginning and end of each segment. The maximum text length is 2048 characters. Returns OK, NOK (invalid user, password, message with more than 2048 characters or financial pendings), Erro (Error), or NA (not available) the necessary fields are SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. 10

11 Serie - Number between 0 and 255 that should be unique for each concatenated SMS sent, being increased by 1 at each sent message and when reaches 255 start again with 0 ( zero ). It should not be sequential and could be repeated. Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem (Message Text) - ASCII Text (2048 char. Maximum size, UNICODE from 0000 to 00FF). EnviaSMSConcatenadoComAcento2N - Sends a concatenated accented text SMS message with 2 numeric custom reference fields (SeuNum1 and SeuNum2). The "Serie" field should contain a number between 0 and 255 that should be unique for each concatenated SMS sent, being increased by 1 at each sent message and when reaches 255 start again with 0 ( zero ). If this message has more than 70 characters, it will be split in several messages with 70 characters each and received in form of a concatenated unique message at the mobile phone, only if the destination operator supports concatenation. If there is no support for concatenation at the destination operator, the messages will be sent with +" in the beginning and end of each segment. The maximum text length is 2048 characters. Returns OK, NOK (invalid user, password, message with more than 2048 characters or financial pendings), Erro (Error), or NA (not available) the necessary fields are SeuNum1 - This is a numeric field with a maximum of 20 digits that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. SeuNum2 - This is a numeric field with a maximum of 20 digits that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Serie - Number between 0 and 255 that should be unique for each concatenated SMS sent, being increased by 1 at each sent message and when reaches 255 start again with 0 ( zero ). It should not be sequential and could be repeated. 11

12 Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem (Message Text) - ASCII Text (2048 char. Maximum size, UNICODE from 0000 to 00FF). EnviaSMSConcatenadoSemAcento - Sends a concatenated text (not accented) SMS message. The "Serie" field should contain a number between 0 and 255 that should be unique for each concatenated SMS sent, being increased by 1 at each sent message and when reaches 255 start again with 0 ( zero ). If this message has more than 140 characters, it will be split in several messages with 140 characters each and received in form of a concatenated unique message at the mobile phone, only if the destination operator supports concatenation. If there is no support for concatenation at the destination operator, the messages will be sent with +" in the beginning and end of each segment. The maximum text length is 4096 characters. Returns OK, NOK (invalid user, password, message with more than 4096 characters or financial pendings), Erro (Error), or NA (not available) the necessary fields are SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Serie - Number between 0 and 255 that should be unique for each concatenated SMS sent, being increased by 1 at each sent message and when reaches 255 start again with 0 ( zero ). It should not be sequential and could be repeated. Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem (Message Text) - ASCII Text (2048 char. Maximum size, UNICODE from 0000 to 00FF). 12

13 EnviaSMSConcatenadoSemAcento2N - Sends a concatenated text (not accented) SMS message with 2 numeric custom reference fields (SeuNum1 and SeuNum2). The "Serie" field should contain a number between 0 and 255 that should be unique for each concatenated SMS sent, being increased by 1 at each sent message and when reaches 255 start again with 0 ( zero ). If this message has more than 140 characters, it will be split in several messages with 140 characters each and received in form of a concatenated unique message at the mobile phone, only if the destination operator supports concatenation. If there is no support for concatenation at the destination operator, the messages will be sent with +" in the beginning and end of each segment. The maximum text length is 4096 characters. Returns OK, NOK (invalid user, password, message with more than 4096 characters or financial pendings), Erro (Error), or NA (not available) the necessary fields are SeuNum1 - This is a numeric field with a maximum of 20 digits that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. SeuNum2 - This is a numeric field with a maximum of 20 digits that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Serie - Number between 0 and 255 that should be unique for each concatenated SMS sent, being increased by 1 at each sent message and when reaches 255 start again with 0 ( zero ). It should not be sequential and could be repeated. Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem (Message Text) - ASCII Text (2048 char. Maximum size, UNICODE from 0000 to 00FF). 13

14 EnviaSMSDataSet: For batch message sending. Receives a DataSet with the SMS messages to be sent, with the following fields: Seunum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem ASCII Text (140 char. Maximum size). ASCII between ASCII- 32 e ASCII-126 would be accepted (Special characters will be changed. Agendamento (Scheduling) DATETIME ANSI format: HH:MM:SS. YYYY-MM-DD Returns a string with the following values: OK Message accepted for transmission NOK Message not accepted for transmission or financial pendings Erro - Error NA (not available) System unavailable The dataset should be filled as the following SOAP command: POST /reluzcap/wsreluzcap.asmx HTTP/1.1 Host: Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: " " <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:soap=" instance" <soap:body> 14

15 <EnviaSMSDataSet xmlns=" <NumUsu>string</NumUsu> <Senha>string</Senha> <DS> <xsd:schema>schema</xsd:schema>xml</ds> </EnviaSMSDataSet> </soap:body> </soap:envelope> Senha (Password) 18 alphanumeric characters long. EnviaSMSESMDCS - Send a message to a cell phone. ESM, Header and DCS fields must be in format OTA 8-bit format with an even number of hexadecimal characters. The message field must be formatted as a text string. Returns OK, NOK (financial pending, etc), error or NA (not available). Senha (Password) 18 alphanumeric characters long SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Celular - (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number ESM - OTA 8 bit format, with an even number of hexadecimal characters DCS - OTA 8 bit format, with an even number of hexadecimal characters Header - OTA 8 bit format, with an even number of hexadecimal characters Mensagem (Message Text) - ASCII Text (4096 char. Maximum size). ASCII between ASCII-32 e ASCII-126 would be accepted (Characters out of this range will be changed.) If a message was greater than 140 characters, it will 15

16 be split into multiple messages of 140 characters each with "..." separating the messages. The maximum text length is 4096 characters. EnviaSMSOTA8Bit Sends a binary message. The Header and Data fields must be in the OTA 8 bit format, with an even number of hexadecimal characters. Returns OK, NOK (invalid user, password, message with more than 4096 characters or financial pendings), Erro (Error), or NA (not available) the necessary fields are SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Header - OTA 8 bit format, with an even number of hexadecimal characters Data - OTA 8 bit format, with an even number of hexadecimal characters, with 4096 characters maximum length EnviSMSQuebra - Sends a SMS message. If the message is greater than 140 characters, it will be split into multiple messages of 140 characters each with "..." separating the messages. The maximum text length is 4096 characters. Returns OK, NOK(financial pendings, etc), Erro (Error) or NA (not available) SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. 16

17 Celular - (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem - (Message Text) - ASCII Text (4096 char. Maximum size). ASCII between ASCII-32 e ASCII-126 would be accepted (Characters out of this range will be changed.) If a message was greater than 140 characters, it will be split into multiple messages of 140 characters each with "..." separating the messages. The maximum text length is 4096 characters. EnviaSMSTIM Not applicable EnviaSMSTemplate - The use of this function is only for customers who use the feature of WebCorp templates. Please check the existing documentation of the WebCorp. EnviaSMSXML Receives a XML with the SMS messages to be sent, with the following fields: Horaenv - (HH:MM:SS) Seunum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number Mensagem (Message Text) - ASCII Text (140 char. Maximum size). ASCII between ASCII-32 e ASCII-126 would be accepted (Characters out of this range will be changed.) Agendamento (Scheduling) DATETIME ANSI format: YYYY-MM-DD HH:MM:SS. Returns a string with the following values: OK Message accepted for transmission 17

18 NOK Message not accepted for transmission or financial pendings Erro - Error NA (not available) System unavailable InsBL - Insert a MSISDN in the black list. Returns 0 in case of success, 0 if the MSISDN in already blacklisted, -1 in case of error. The necessary fields are: Celular (55DDNNNNNNNN) Destination Cell Phone Number, where D = Área Code and N = Cell Phone Number ResetaMOLido - Resets the READ status of the MO messages since 1 day before until now. Returns OK in case of success and NOK on case of error. The necessary fields are: ResetaStatusLido - Resets the READ status of the Statuses since 1 day before until now. Returns OK in case of success and NOK on case of error. The necessary fields are: StatusSMS2SN - Returns a DataSet named OutDataSet for a message sent through the EnviaSMS2SN method. In case of error returns Nothing. Fields needed: 18

19 SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. StatusSMSDataset Receives a Dataset with SeuNum field values, and returns a Dataset called OutDataSet with a table called StatusSMSDS that contains a set of already transmitted messages. In case of error returns Nothing. Please check the web interface thru a web browser for a SOAP Method example. Fields needed: SeuNum - This field is a number or alphanumeric character chain with 10 characters that is generated by the user and, that is recorded with the message, for future queries. It s not necessary to be ordered, and could be repeated. StatusSMSNaoLido Returns a DataSet named OutDataSet with a StatusSMS table with the maximum length of 400 rows, containing the SMS status for the last 4 days that where not read, and mark them as READ. If there are 400 rows, in the returned table it means that more Status should be available and in this case, more calls to the function should be made. In case of error returns Nothing. Fields needed: *Note - To do the same search in this method, first need make a reset and after that wait one minute 19

20 VerBL - Returns a DataSet with the blacklisted MSISDNs for this account. In case of error returns Nothing. Fields needed: VerCredito Not applicable VerValidade Not applicable Unimessage Automatic return integration The web services platform offers resources to do all message-handling tasks, from sending messages to check status and generate reports. In this case, all requests starts at the client side (customer platform). Also, it s possible to set up the reverse way, where all MO (mobile originated) messages, and DLR tickets (message status changes), directed to the customer account should be forwarded to the client server (customer platform), thru HTTP GET, HTTP POST and SMTP methods. In this case, as soon as Unimessage receives a DLR status from the operator, it forwards this DLR update to a pre-defined URL, thru HTTP GET or POST, or by SMTP for a pre-defined address. The same is true for MO messages that are received as answers for MT (mobile terminated) messages sent thru the Unimessage customer account, or the message was sent to a custom pre-defined LA (short number), or the message were sent with a pre-defined keyword in the first five positions of the message body. The return path for MOs sent as answers for MTs is valid for a period of 4 days after the MT was sent. The customer Server should be set up to receive the events where the necessary parameters will be passed. 20

21 The URL format, for the GET method should have the following parameters: Example: URL format STATUS parameters: SeuNum - %u (customer message ID) Celular %c (Cell phone number) Status - %s (Two characters Example: CL) Data do status %d (date yyyy-mm-ddthh:mm:ss) TextoStatus - %t (status description, see below *) Operadora - %o (Our numeric code, 1 Claro, 2 TIM, 3 Vivo, etc.) URL Status example: URL Parameters Status descriptions Case "CL" textostatus = "SMS entregue ao celular de destino" (SMS delivered to the mobile) Case "E0" TextoStatus = "Numero de celular invalido/sem operadora" (Invalid mobile number/operator) Case "E1" textostatus = "Blacklist" (MSISDN is blacklisted) Case "E3" textostatus = "Duplicada" (Message rejected due to excessive repetitions) 21

22 Case "E4" textostatus = "SMS recusado pela operadora" (SMS rejected by the operator) Case "E5" TextoStatus = "SMS expirado sem informe da operadora" (SMS without operator notice) Case "E6" textostatus = "SMS expirado conforme informe da operadora" (SMS expired as informed by the operator) Case "E7" textostatus="sms rejeitado por falta de créditos ou conta bloqueada" (rejected due to lack of credit or blocked account) URL format MO parameters: Operadora - %o (Our numeric code, 1 Claro, 2 TIM, 3 Vivo, etc.) Menesagem - %m (MO message text) Celular - %c (Originator mobile number) Shnum - %s (ShortCode - MO destination short number) SeuNum - %u (MT customer message identification number, to witch this MO answers) Data - %d (SMS MO date) URL MO example: URL Parameters 22

23 Message Status Table SMS possible status: OK: message received, queued to be sent to the operator OP: message sent to the operator CL: DLR received ER: System error E0: Invalid mobile number/operator E1: MSISDN is blacklisted E3: Message rejected due to excessive repetitions E4: Message rejected by the operator E5: Message expired without operator notice E6: SMS expired as informed by the operator E7: Message rejected due to lack of credit or blocked account Operator code number: 0 - No operator (message with no MSISDN or the MSISDN does not belong to any operator) 1 - Claro 2 - TIM 3 - Vivo 4 - TeleMig 5 - Oi 6 - Nextel 7 - Brasil Telecom 8 - Sercomtel 9 CTBC 10 Porto Conecta 11 Vodafone 23

24 12 Surf Telecom 257 Other OBS: The status should be changed up to 48 hours after sent to the operators For more information, please contact: 24