ARAP connects to the BGO/ARO Social Media Gateway (SMG) software in order to interface with Twitter, Facebook, and http web client interface using the commands below. The SMG software must be authenticated as an "app" and connected to particular Twitter and Facebook accounts.  

All commands set the boolean variable SMERROR to "true" if an error occurs or "false" if no error occurs.


socialmediaon

Syntax: socialmediaon

This command initiates communication with the SMG software. If this operation is successful, the variable SMCONNECTED is set to "true". All commands below that require communication with it must be preceded by this command.

socialmediaoff

Syntax: socialmediaoff

This command terminates communication with the SMG software and sets the variable SMCONNECTED to "false".

tweet

Syntax: tweet message <messageid> <mediafilename>

This command sends "message" as a Twitter public tweet. If the optional "messageid" parameter is provided, the tweet is sent as a reply to that message id. If the optional "mediafilename" parameter is included, the tweet will include the specified image (the filename must be fully-qualified) -  see Twitter's Uploading Media page for details and limitations.

tweetprivate

Syntax: tweetprivate message recipient <messageid>

This command sends "message" as a Twitter private direct message to "recipient". If the optional "messageid" parameter is provided, the direct message is sent as a reply to that message id.

gettwittermentions

Syntax: gettwittermentions count <messageid>

This command retrieves the most recent "count" Twitter-mentions. If the optional "messageid" parameter is provided, only those Twitter-mentions received after the specified message id are retrieved.

The response is stored in variable SMRESPONSE as one text line (each ending with cr and lf characters) per Twitter-mention. If "mentions" were received, SMRESPONSE is NULL. Each line is tab-separated with the following fields:

  • date and time. eg: "Sun Jun 19 19:05:55 +0000 2016"
  • handle of tweet sender
  • message id
  • comma-separated list of tags. eg. request,waycool
  • the text of the tweet

Below is an example on how to access the variable SMRESPONSE, which is essentially a two dimensional array, with ARAP arrays:

gettwittermentions 5

iftrue $SMERROR jump ERROR        ; handle error


TWEETS= $SMRESPONSE                ; copy to a global variable  

ARRAYDELIMITER= $CRLF

NUMTWEETS= $TWEETS[0] - 1        ; gives one more because of extra cr-lf

echo "Number of mentions:" $NUMTWEETS

ATWEET= $TWEETS[$NUMTWEETS]        ; get oldest "mention"

       

ARRAYDELIMITER= $TAB

       echo "Sender Handle:" $ATWEET[2]                ; get sender field

       echo "Tweet Text:" $ATWEET[5]                ; get tweet text field

gettwittertimeline

Syntax: gettwittertimeline count <messageid>

This command retrieves the most recent "count" tweets from the user's Twitter timeline. If the optional "messageid" parameter is provided, only those tweets received after the specified message id are retrieved.

The response is stored in variable SMRESPONSE as one text line (each ending with cr and lf characters) per Twitter-mention. If no tweets were received, SMRESPONSE is NULL. Each line is tab-separated with the following fields:

  • date and time. eg: "2016/12/18 19:05:55"
  • handle of tweet sender
  • message id
  • comma-separated list of tags. eg. request,waycool
  • the text of the tweet

See gettwittermentions for an example on how to access the variable SMRESPONSE with ARAP arrays.

gettwitterdirectmessages

Syntax: gettwitterdirectmessages count <messageid>

This command retrieves the most recent "count" direct (private) messages. If the optional "messageid" parameter is provided, only those messages received after the specified message id are retrieved.

The response is stored in variable SMRESPONSE as one text line (each ending with cr and lf characters) per Twitter-mention. If no direct messages were received, SMRESPONSE is NULL. Each line is tab-separated with the following fields:

  • date and time. eg: "2016/12/18 19:05:55"
  • handle of the message sender
  • message id
  • comma-separated list of tags. eg. automated,observatories,rock
  • the text of the message

See gettwittermentions for an example on how to access the variable SMRESPONSE with ARAP arrays.

getpagemessages

Syntax: getpagemessages

This command retrieves new Facebook page messages for the Facebook page configured in the SMG software.

The response is stored in variable SMRESPONSE as one text line (each ending with cr and lf characters) per page message. If no page messages have been received, SMRESPONSE is NULL. Each line is tab-separated with the following fields:

  • date and time. eg: "2016/12/18 19:05:55"
  • the Facebook page-context user id of the sender of the message (note that this is not the same as the sender's main Facebook user id)
  • the Facebook page id that the message is directed to
  • message id
  • the text of the message

See gettwittermentions for an example on how to access the variable SMRESPONSE with ARAP arrays.

pagemessage

Syntax: sendpagemessage message recipientid

This command sends the text "message" as a Facebook Messenger page message to the Facebook user id "recipientid" (page context). Note that a page-context user id is not the same as a main Facebook user id.

pageimageurl

Syntax: sendpageimageurl imageurl recipientid

This command sends the image "imageurl" as a Facebook Messenger page message to the Facebook user id "recipientid" (page context). Note that a page-context user id is not the same as a main Facebook user id. "imageurl" must point to an internet accessible image in JPG, PNG, or GIF format.

getpages

Syntax: getpages

This command retrieves a list of the names of the Facebook pages that the Facebook user is an administrator of. The response is stored in variable SMRESPONSE as a tab-separated list.

getpagealbums

Syntax: getpagealbums pageindex

This command retrieves a list of the names of the Facebook albums for the Facebook page "pageindex". This command must be preceded by the getpages command. The response is stored in variable SMRESPONSE as a tab-separated list.

pagepost

Syntax: pagepost pageindex message <url> <imageurl>

This command posts "message" to the feed of the Facebook page "pageindex" (the first page has a value of 0). This command must be preceded by the getpages command. If the optional parameters "url" and "imageurl" are included, the web page "url" will be linked in the post and the image "imageurl" will be shown. If "imageurl" is not provided, Facebook will choose an image from the linked web page.

pageimage

Syntax: pageimage pageindex albumindex imagefile caption <showonfeed>

This command uploads the image file "imagefile" with the caption "caption" to the album "albumindex" (the first album returned by the getpagealbums command is 0) of the Facebook page "pageindex" (the first page returned by the getpages command has a value of 0). The "imagefile" must be fully-qualified and be in JPG, PNG, or GIF format. This command must be preceded by the getpages and getpagealbums commands. If the optional parameter "showonfeed" is a boolean true, this causes the image with its caption to appear on the Facebook page's feed.

The variable SMRESPONSE is set to the URL of the uploaded image.

getwebcommands

Syntax: getwebcommands

This command retrieves new web command messages received independently and stored by the SMG software.

The response is stored in variable SMRESPONSE as one text line (each ending with cr and lf characters) per message. If no messages have been received, SMRESPONSE is NULL. Each line is tab-separated with the following fields:

  • date and time that the message was received. eg: "2016/12/18 19:05:55"
  • a unique message id as set by the message sender
  • an observer id as set by the message sender
  • a password as set by the message sender (between 7 and 20 characters)
  • the text of the message

It is responsibility of the script to validate the observer id and password.

The format used by http clients of the BGO/ARO Social Media Gateway is:

http://server_url:8080/command?id=1234&observerid=5678&password=ralph123&type=send&command=this is a message

The response, tab separated, is one of:

  • OKIDLE<tab>accepted        - the message was accepted and the web client busy flag is "idle"
  • OKBUSY<tab>accepted        - the message was accepted and the web client busy flag is "busy"
  • ERROR<tab>descriptive error message        - the message was not accepted

sendwebreply

Syntax: sendwebreply messageid observerid password "the reply message"

This command sends a web reply message that is stored by the SMG software. The reply includes (as given in the parameters) a unique ID, observer id, password, and the text if the message. The date and time of the message is added by the SMG software. The intended use is that the message id, observer id and password are the same as the received message being replied to.

The format used by http clients to receive the reply is:

http://server_url:8080/command?id=1234&observerid=5678&password=ralph123&type=get

The response, tab separated, is one of:

  • ERROR<tab>descriptive error message        - the message was not accepted
  • OK<tab>        - followed by the following tab separated fields
    • date and time that the message was received. eg: "2016/12/18 19:05:55"
    • a unique message id
    • the observer id
    • the password (between 7 and 20 characters)
    • the text of the reply message

It is responsibility of the http client to validate the observer id and password.

deletewebid

Syntax: deletewebid messageid

This command deletes a web command message and/or web reply message with id "messageid" stored by the SMG software. This mainly intended to remove a web reply that has become stale (perhaps a follow up message was not received back by the expected time.

deleteallwebreplies

Syntax: deleteallwebreplies

This command deletes all web reply messages stored by the SMG software.

setwebclientbusy

Syntax: setwebclientbusy busy_flag

This command sets a boolean flag stored by the SMG software. This flag controls the response received when sending a command eventually received by getwebcommands. It is intended to be used to indicate if the http client can expect a quick reply (false=IDLE) to its command or there may be some delay (true=BUSY).