WhatsATool API - REST-Like Interface to WhatsATool Services

Transcription

1 Disclaimer This service and also mtms Solutions GmbH is not associated in any case with WhatsApp. WhatsApp is a registered Trademark owned by WhatsApp Inc. mtms is not related in any way with WhatsApp Inc. This is not a official service of WhatsApp and uses interfaces to WhatsApp which are not designed to be used this way. This means this service can be shut down by WhatsApp at any time without prior information. This can effect the whole service or only single simcards. In the case WhatsApp blocks a simcard, all contacts on this simcard have to reregister to a new simcard. We are not responsible if you violate WhatsApp by using this service. It's in your responsibility to check if using this service within your business process is legal. mtms is only a technical provider, which does not own the accounts and is not responsible for any violation of the WhatsApp EndUserLicencAgreement (EULA). Please remember: We can not guarantee the function of this service at any time. The content and works published on this document are governed by the copyright laws of Austria. Any duplication, processing, distribution or any form of utilization beyond the scope of copyright law shall require the prior written consent of the author or authors in question. Disclaimer 1. General 1.1. Messagetypes: 2. Webservice for Sending Messages to Contacts (MT) 2.1. Simple / Sending to only one msisdn Requestparameters Examples 2.2. Broadcast / Sending a message to a channel Requestparameters Examples 2.3. Broadcast / Sending a message to a list of contacts Requestparameters Examples 2.4. Sending Media Files Images Audio Video Link with preview (WhatsApp) 2.5. Response 2.6. PHP sample code: 3. Receiving messages via WhatsATool (MO) 4. Webservice for Contactmanagement 4.1. Overview 4.2. List current SIMs Request Response 4.3. List current contacts Request Response 4.4. Register a Contact Request Response 4.5. Remove a Contact Request Response 4.6. Add to a Channel Request Response 4.7. Remove from a Channel Request 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 1

2 Response 4.8. List current Channels Request Response 4.9. Get Next Potential SIM Request Response 5. Forwarders 5.1. httpbotfwd Sending Text Message Sending Media File Example If something went wrong 6. Document-History 1. General Timezone for all date/timestamps are Vienna Local Time (CET/CEST) 1.1. Messagetypes: Currently you can send/receive the following types of messages: type send receive textmessages as utf8 including emoticons yes yes images jpg and png, max 1600px x 1600px and max. 2MB yes audiomessages aac and mp3 (max. 10MB) aac and autoconvert to mp3 Video PDF yes (preview with image and link will be autogenerate) (comming soon) yes (preview with image and link will be autogenerate) (comming soon) yes yes geodata no yes - converted to longitude und latitude 2. Webservice for Sending Messages to Contacts (MT) Messages can be sent to contacts via a REST-like webservice. The method to deliver the data is an HTTP-POST or HTTP-GET request. s will be accepted as regular GET/POST- or as a JSON-encoded object. The URL for this webservice is: It is recommended to accept self-signed certificates. The sending of messages is divided into the following types: simple (sending a message to a single receiver/msisdn) 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 2

3 broadcast (addressing a group of receivers by using a channel name) The differentiation of these types will be achieved by the parameter "sendtype". Depending on the sendtype not all parameters are mandatory. The needed parameters will be explained in detail in the succeeding section Simple / Sending to only one msisdn Requestparameters Following parameters will be expected in the request (case sensitive and character set is UTF-8). username String (max. length: password String (max. length: sendtype String (max. length: text String in utf8 (max. length: 500) ts_start Optional String (max. length: For authentication; a unique username; defined in the database of WhatsATool For authentication; defined in the database of WhatsATool "simple" means that only one contact will receive the message (1:1 message) The message, which should be sent String or Unix-Timestamp containing a date/time when the message should be sent. Default: message will be sent immediately watuser1 er4m9xs2f7hk simple This is a Message for the contacts :12:34 msisdn String (max. length: The MSISDN of the contact who should receive the message contactid Optional String (max. length: Instead of using the msisdn as address parameter you can also use the contactid of the receiver Examples Example Request (GET): dn= POST-Data can be JSON-encoded or plain POST-parameters. HTTP-Request with POST-Data as JSON-encoded object: {"username":"watuser1","password":"er4m9xs2f7hk","sendtype":"simple","text":"foo bar","msisdn":" "} OR HTTP-Request with POST-Data as parameters: username=watuser1&password=er4m9xs2f7hk&sendtype=simple&text=foo%20bar&msisdn= {"status":"ok","info":"message queued","id":"302","code":100} 2.2. Broadcast / Sending a message to a channel Requestparameters 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 3

4 Following parameters will be expected in the request (case sensitive and character set is UTF-8). username String (max. password String (max. sendtype String (max. text String (utf8,max. length: 500) ts_start Optional String (max. channel String (max. For authentication; a unique username; defined in the database of WhatsATool For authentication; defined in the database of WhatsATool "broadcast" means that all contacts in a channel will receive the message (1:n message) The Message to be sent String or Unix-Timestamp containing a date/time when the message should be sent. Default: message will be sent immediately The name of the channel, which contains the contacts, who should receive the message watuser1 er4m9xs2f7hk broadcast This is a Message for the contacts :12:34 NEWS1 msgid Optional Integer ID of the broadcast, which allows us to identify a transmission and avoid double sending the same broadcast Examples Example Request (GET): hannel=news1 POST-Data can be JSON-encoded or plain POST-parameters. HTTP-Request with POST-Data as JSON-encoded object: {"username":"watuser1","password":"er4m9xs2f7hk","sendtype":"broadcast","text":"foo bar","channel":"news1"} OR HTTP-Request with POST-Data as parameters: username=watuser1&password=er4m9xs2f7hk&sendtype=broadcast&text=foo%20bar&channel=news1 {"status":"ok","info":"messages queued; count: 1","code":100} 2.3. Broadcast / Sending a message to a list of contacts Requestparameters Following parameters will be expected in the request (case sensitive and character set is UTF-8). username String (max. password String (max. For authentication; a unique username; defined in the database of WhatsATool For authentication; defined in the database of WhatsATool watuser1 er4m9xs2f7hk 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 4

5 sendtype String (max. text String (utf8,max. length: 500) ts_start Optional String (max. "broadcast" means that all contacts in the given list will receive the message (1:n message) The Message to be sent String or Unix-Timestamp containing a date/time when the message should be sent. Default: message will be sent immediately broadcast This is a Message for the contacts :12:34 list String A comma (,) separated list of contacts (msisdns) , , msgid Optional Integer ID of the broadcast, which allows us to identify a transmission and avoid double sending the same broadcast Examples Example Request (GET): ist= %2c %2c% POST-Data can be JSON-encoded or plain POST-parameters. HTTP-Request with POST-Data as JSON-encoded object: {"username":"watuser1","password":"er4m9xs2f7hk","sendtype":"broadcast","text":"foo bar","list":" , , "} OR HTTP-Request with POST-Data as parameters: username=watuser1&password=er4m9xs2f7hk&sendtype=broadcast&text=foo%20bar&list= %2c % 2C% {"status":"ok","info":"messages queued; count: 1","code":100} 2.4. Sending Media Files The media file itself can be transmitted via a "http-post, mulipart/form-data" request or Base64 encoded within the file parameter. Only one file can be transmitted per request. s apply as defined above with the additions below Images In the case you want to send a image via WhatsATool you can use the text parameter as described above as the caption of the image. Only jpg and png images are allowed. The image must not exceed a size of 2 MB at all. Also the resolution must not exceed 1600x1600 pixel Audio If you want to send a audio file via WhatsATool the text parameter as described above is void, because WhatsApp and Telegram do not support caption for audio messages. Only aac and mp3 files are allowed. The file must not exceed a size of 10 MB at all Video In the case you want to send a video via WhatsATool you can use the text parameter as described above as the caption of the video. Only mp4 videos are allowed. The file must not exceed a size of 10 MB at all. Telegram: The Video is sent as is. WhatsApp: The Video is converted to a link with preview image by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 5

6 text String in utf8 (max. length WhatsApp: 500) (max. length Telegram: 200) The media caption which should be sent. Empty string allowed for audio. This is an image! filetype Optional String (max. Type of the file. "image", "audio" or "video". Default: "image" audio file Optional ImageFile (max. 2MB, max 1600x1600) AudioFile (max. 10MB) VideoFile (max. 10MB) To send a media file via WhatsATool you can submit it via a mime multipart http-post request or Base64 encoded filename Optional String in utf8 Filename image.jpg Link with preview (WhatsApp) In WhatsApp there is the possibility to send a link with an preview image. The WhatsApp app scans the given link for so called Open Graph Meta Tags and creates the message. With your interface the behavior can be reproduced. If a link is given, the destination is scanned for following meta tags: "og:description", "og:image" and "og:title". In addition to this, you are able to submit your own data if one or more tags are missing on the site or you want to replace them with your own content. filetype String in utf8 Type of the "file". Has to be "link" link url String in utf8 The URL of the link. description Optional String (max. length: 500) file Optional ImageFile (max 200x200) title Optional String (max. The description of the link. The URL has to be included in the description, if not, it is appended at the end. To send a media file via WhatsATool you can submit it via a mime multipart http-post request or Base64 encoded The title of the link. The Open Graph protocol enables any web page to become a rich object in a social graph. Open Graph protocol 2.5. Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: code status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 403 error invalid msisdn; not assigned to a contact 404 error sim not found or not active 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 6

7 405 error no permission for send 406 error invalid sendtype given 407 error channel not found 408 error no text given 410 error media file to large 412 error media format wrong or resolution invalid 415 error wrong filetype 416 error no list given or wrong separator "," 417 error msgid not a number 418 error message already processed 419 error url not valid 420 error no Open Graph image found for given page and no image given 999 error unknown error occurred; try again later In case of a successful request the result will be a JSON encoded String (UTF-8): code status info id 100 ok messages queued; count: <number of receivers> Id of the message 2.6. PHP sample code: <?php sample code sending messages $file=dirname( FILE )."/logo_4.jpg"; $url=" //$url=" $data=array( "username"=>"username", "password"=>"password", // "sendtype"=>"broadcast", // "channel"=>"news1", "sendtype"=>"simple", "msisdn"=>" ", "text"=>"this is a test message", 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 7

8 ); list($postdata,$headers)=_getmultipartmimepost($data,array("file"=>$file)); $curl = curl_init(); curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata); curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true); $r = curl_exec($curl); curl_close($curl); echo $r; function _getmultipartmimepost($postarr=array(), $files=array()) { // invalid characters for "name" and "filename" $disallow=array("\0", "\"", "\r", "\n"); // build normal parameters foreach ($postarr as $k=> $v) { $k=str_replace($disallow, "_", $k); $body[]=implode("\r\n", array( "Content-Disposition: form-data; name=\"{$k}\"", "", filter_var($v), )); } // build file parameters foreach ($files as $k=> $v) { switch (true) { case false===$v=realpath(filter_var($v)): case!is_file($v): case!is_readable($v): continue; // or return false, throw new InvalidArgumentException } $data=file_get_contents($v); $v=call_user_func("end", explode(directory_separator, $v)); $k=str_replace($disallow, "_", $k); 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 8

9 } $v=str_replace($disallow, "_", $v); $body[]=implode("\r\n", array( "Content-Disposition: form-data; name=\"{$k}\"; filename=\"{$v}\"", "Content-Type: application/octet-stream", "", $data, )); // generate safe boundary do { $boundary=" ".md5(mt_rand().microtime()); } while (preg_grep("/{$boundary}/", $body)); // add boundary for each parameters foreach ($body as $k=> $v) { $body[$k]="--{$boundary}\r\n{$v}"; } // add final boundary $body[]="--{$boundary}--"; $body[]=""; $postdata=implode("\r\n", $body); $headers=array( "Expect: 100-continue", "Content-Type: multipart/form-data; boundary={$boundary}", // change Content-Type ); return array($postdata, $headers); 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 9

10 } 3. Receiving messages via WhatsATool (MO) Messages which are received via WhatsATool can be forwarded to a customer webservice. The parameters must be defined in the admin tool. You have to define the endpoint (Target) and parameter names. Condtinional forwarding based on Keywords or media types can also be done.the following Placeholders are available: 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 10

11 {NICKNAME} {MSISDN} {CONTACTID} internal contact id {MSGID} MsgId of the chat protocol {MSG} {MEDIATYPE} audio/video/image If the message contains an media file, it will be transferd as Mime/multipart POST Request. file Mime/multipart If the message contains a image/audio/video In case of a successful request the result must be a JSON encoded String (UTF-8): code status info 100 ok Additional info 4. Webservice for Contactmanagement Because contacts must be shared over a pool of simcards (max. 500 contacts per simcard), you can not use the same simcard-number in the register process for each customer. We have a algorithm which handles the sharing of the simcardpool. Contacts can be created/updated to WhatsATool via a REST-like webservice. The method to deliver the data is an HTTP-POST or HTTP-GET request. s will be accepted as regular GET/POST- or as a JSON-encoded object. The URL for this webservice is: Overview It is recommended to accpet self-signed certificates. This webservice can handle following use cases ( in braces are the corresponding actions): list SIMs ( listsims) list current contacts ( listcontacts) register a contact ( registercontact) remove a contact ( removecontact) add to a channel ( addtochannel) remove from a channel ( removefromchannel) list current channels ( listcurrentchannels) get next potential SIM ( getnextpotentialsim) The differentiation of the use case will be achieved by the parameter "action". Depending on the use case not all parameters are mandatory. These use cases will be explained in detail in the succeeding section List current SIMs Request Following parameters will be expected in the request (case sensitive and character set is UTF-8) by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 11

12 username String (max. For authentication; a unique username; defined in the database of WhatsATool watuser1 password String (max. For authentication; defined in the database of WhatsATool er4m9xs2f7hk action String (max. To identify the use case which needs to be done listsims Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: code status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 410 error invalid action given 999 error unknown error occurred; try again later In case of a successful request the result will be a JSON encoded String (UTF-8) with the table of currently available contacts: code status contacts 100 ok table of SIMs Example Request: POST-Data can be JSON-encoded or plain POST-parameters. HTTP-Request with POST-Data as JSON-encoded object: {"username":"watuser1","password":"er4m9xs2f7hk","action":"listsims"} OR HTTP-Request with POST-Data as parameters: username=watuser1&password=er4m9xs2f7hk&action=listsims {"status":"ok","info":"","code":100,"sims":[{"id":"1","user_id":"1","msisdn":" ","originator":" ","username":" ",...,"ts_created":" :17:54"},...]} 4.3. List current contacts Request Following parameters will be expected in the request (case sensitive and character set is UTF-8) by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 12

13 username String (max. length: password String (max. length: action String (max. length: channel Optional String (max. length: from Optional String (max. length: to Optional String (max. length: For authentication; a unique username; defined in the database of WhatsATool For authentication; defined in the database of WhatsATool To identify the use case which needs to be done To filter the contact list to a special channel. To filter the contact list to a certain time period (creation). Format: YYYY-MM-DD HH:mm:ss To filter the contact list to a certain time period (creation). Format: YYYY-MM-DD HH:mm:ss watuser1 er4m9xs2f7hk listcontacts Newsflash :00: :59: Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: code status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 405 error no permission for edit contact 410 error invalid action given 999 error unknown error occurred; try again later In case of a successful request the result will be a JSON encoded String (UTF-8) with the table of currently available contacts: code status contacts 100 ok table of contacts Example Request: POST-Data can be JSON-encoded or plain POST-parameters. HTTP-Request with POST-Data as JSON-encoded object: {"username":"watuser1","password":"er4m9xs2f7hk","action":"listcontacts"} OR HTTP-Request with POST-Data as parameters: username=watuser1&password=er4m9xs2f7hk&action=listcontacts {"status":"ok","info":"","code":100,"contacts":[{"id":"31","user_id":"1","sim_id":"1","pic_resource_id":"0","msisdn":" ","nickname":"the Name of the Contact in WhatsApp","active":"1","ts_mo_sent":" :45:42","ts_created":" :45:41"}]} 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 13

14 4.4. Register a Contact Request Following parameters will be expected in the request (case sensitive and character set is UTF-8). username String (max. password String (max. action String (max. For authentication; a unique username; defined in the database of WhatsATool For authentication; defined in the database of WhatsATool To identify the action to commit watuser1 er4m9xs2f7hk registercontact msisdn String (max. The MSISDN of the contact which should be registered simmsisdn Optional String (max. The preferred MSISDN of the SIM which should be used to register the contact to. Default: the next free SIM will be taken sendsms Optional Integer (0/1) If 1 an SMS will be sent to the contact's MSISDN containing a registration message. If 0 no SM will be sent. Default: 0 1 smstext Optional String (max. length: 160) channel Optional String (max. The SMS text the contact should get if sendsms=1. Default "" (empty string, which means the saved text in the database will be used) The name of the channel the contact should be registered to. Default: "" (contact needs not to be added to a channel) Thank you for the registration to our WhatsApp-Service NewsChannel Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: statuscode status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 404 error sim not found or not active (simmsisdn) 405 error no permission for edit contact 407 error channel not found 408 error maximum number of contacts for the chosen sim reached (can only happen if two parallel requests chose the same SIM) 409 error no message for registration-sms defined (sendsms=1: but no message defined this means smstext="" and also no message defined in the database) 410 error invalid action given 412 error no originator for registration-message found 413 error no sim with free space for new contacts found 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 14

15 414 error msisdn in invalid format; must be: error this sim has no more free space for new contacts available 999 error unknown error occurred; try again later In case of a successful request the result will be a JSON encoded String (UTF-8): code status simmsisdn 100 ok (MSISDN of the SIM which was used to register contact) Example Request: = {"status":"ok","info":"contact added to channel","code":100,"simmsisdn":" "} 4.5. Remove a Contact Request Following parameters will be expected in the request (case sensitive and character set is UTF-8). username String (max. For authentication; a unique username; defined in the database of WhatsATool watuser1 password String (max. For authentication; defined in the database of WhatsATool er4m9xs2f7hk action String (max. To identify the action to commit removecontact msisdn String (max. The MSISDN of a contact Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: statuscode status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 403 error invalid msisdn; not assigned to a contact 405 error no permission for edit contact 410 error invalid action given 999 error unknown error occurred; try again later 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 15

16 In case of a successful request the result will be a JSON encoded String (UTF-8): code status info 100 ok contact deleted Example Request: {"status":"ok","info":"contact deleted","code":100} 4.6. Add to a Channel Request Following parameters will be expected in the request (case sensitive and character set is UTF-8). username String (max. For authentication; a unique username; defined in the database of WhatsATool watuser1 password String (max. For authentication; defined in the database of WhatsATool er4m9xs2f7hk action String (max. To identify the action to commit addtochannel msisdn String (max. The MSISDN of a contact channel String (max. The name of the channel the contact should be registered to. NewsChannel Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: statuscode status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 403 error invalid msisdn; not assigned to a contact 405 error no permission for edit contact 407 error channel not found 410 error invalid action given 999 error unknown error occurred; try again later In case of a successful request the result will be a JSON encoded String (UTF-8): 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 16

17 code status info 100 ok contact added to channel Example Request: &channel=NewsChannel1 {"status":"ok","info":"contact added to channel","code":100} 4.7. Remove from a Channel Request Following parameters will be expected in the request (case sensitive and character set is UTF-8). username String (max. For authentication; a unique username; defined in the database of WhatsATool watuser1 password String (max. For authentication; defined in the database of WhatsATool er4m9xs2f7hk action String (max. To identify the action to commit removefromchannel msisdn String (max. The MSISDN of a contact channel String (max. The name of the channel the contact should be registered to. NewsChannel Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: statuscode status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 403 error invalid msisdn; not assigned to a contact 405 error no permission for edit contact 407 error channel not found 410 error invalid action given 999 error unknown error occurred; try again later In case of a successful request the result will be a JSON encoded String (UTF-8): code status info 100 ok contact removed from channel 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 17

18 Example Request: dn= &channel=newschannel1 {"status":"ok","info":"contact removed from channel","code":100} 4.8. List current Channels Request Following parameters will be expected in the request (case sensitive and character set is UTF-8). username String (max. For authentication; a unique username; defined in the database of WhatsATool watuser1 password String (max. For authentication; defined in the database of WhatsATool er4m9xs2f7hk action String (max. To identify the action to commit listcurrentchannels msisdn Optional String (max. The MSISDN of a contact. If none given all available channels will be listed Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: statuscode status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 403 error invalid msisdn; not assigned to a contact 405 error no permission for edit contact 407 error channel not found 410 error invalid action given 999 error unknown error occurred; try again later In case of a successful request the result will be a JSON encoded String (UTF-8): code status channels 100 ok array of channel names Example Request: isdn= by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 18

19 {"status":"ok","info":"","code":100,"channels":["news1"]} 4.9. Get Next Potential SIM Because contacts must be shared over a pool of simcards (max. 500 contacts per simcard), you can not use the same simcard-number in the register process for each customer. We have a algorithm which handles the sharing of the simcardpool. This service will responde a msisdn from the simcard-pool which can be used for the next registration process and can be displayed to the end user. This use-case is needed if you want to know the SIM before the registration of a contact is done. WARNING: Only a limited number of contacts is allowed for one SIM. So in some cases of race condition it could happen, that the SIM returned by this use case, has no more free space for further contacts available when the registercontact use case is done. Following parameters will be expected in the request (case sensitive and character set is UTF-8) Request username String (max. For authentication; a unique username; defined in the database of WhatsATool watuser1 password String (max. For authentication; defined in the database of WhatsATool er4m9xs2f7hk action String (max. To identify the action to commit getnextpotentialsim Response The return (HTTP-Body) is a JSON encoded String (character set is UTF-8). Depending on the result of the request, it can contain one of the following rows: statuscode status info 401 error missing parameter: <parameter> 402 error invalid username and/or password 405 error no permission for edit contact 413 error no sim with free space for new contacts found 999 error unknown error occurred; try again later In case of a successful request the result will be a JSON encoded String (UTF-8): code status simmsisdn info 100 ok sim found Example Request: {"status":"ok","info":"sim found","code":100,"simmsisdn":" "} 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 19

20 5. Forwarders 5.1. httpbotfwd The "httpbotfwd" is a very easy way to process incoming messages (MO) by a web service and send corresponding outgoing messages (MT) back to the contact. The configuration is done at the WAT platform, placed in the "Automatic Answers" sub menu. Incoming messages (MT) are pushed to "Target" (for example in the defined format. (Postdata for forward). For example: msg={msg}&msisdn={msisdn}&nickname={nickname} Available placeholders are listed next to the configuration fields. The output of the web service has to be JSON encoded. For sending a message to the contact the following parameters have to be defined: Sending Text Message status String Has to be "ok" for further processing ok message String in utf8 (max. length: 500) The message, which should be sent Generated message Sending Media File Media file definitions can be found here status String Has to be "ok" for further processing ok message String in utf8 (max. length WhatsApp: 500) (max. length Telegram: 200) The media caption which should be sent. Empty string allowed for audio. This is an image! type String (max. Type of the file. "image", "audio" or "video". Default: "image" audio file ImageFile (max. 2MB, max 1600x1600) AudioFile (max. 10MB) VideoFile (max. 10MB) Base64 encoded filename String in utf8 Filename image.jpg Example {"status":"ok","message":"generated message"} If something went wrong For each "httpbotfwd" a Job is created. Detailed information about success or fail of the job can be found at the WAT platform, placed in the "Jobs" sub menu. 6. Document-History 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 20

21 Version Date Description: Restructuring of the document Added "Link with preview (WhatsApp)" httpbotfwd Link to "msgid" added Error code 417, Filename parameter added Media caption length Telegram Sending a broadcast to a list of recipients Sending video via api. WhatsApp replaced by WhatsATool. (In some cases) WhatsApp-Tool replaced by WhatsATool. Distinction between WhatsApp and Telegram added if needed Moved to Confluence Files Base64 encoded in request FileType parameter in send request Error code listsims/from-to listcontacts/mediatype file-forwarding Added contactlistfilter/changed MO-Params First Version 2015 by atms Telefon- und Marketing Services GmbH, A-1220 Wien, Leonard-Bernstein-Strasse 10 Page 21