Social Media Commands

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. When SMERROR is "true" the variables SMERRORNUMBER (as an 8-digit hexidecimal number) and SMERRORMESSAGE are also set.

The report error list is below:

80000000 to 80000FFF - the error code reported by the Twitter or Facebook API
80001000 - used for errors with unknown codes
80001001 - for internet connection errors (cannot connect, cannot resolve address, did not receive a reply, etc.)
80002000 - Facebook: invalid page index
80002001 - Facebook: invalid page or album index
80002002 - Facebook: no or bad response
80002003 - Facebook: invalid JSON response
80002004 - Facebook: non-JSON response
80002005 - Facebook: invalid error code
80002006 - Facebook: unknown error - see error message
80002007 - Facebook: invalid error code
80002008 - Facebook: invalid count
80002009 - Facebook: Indy library error
80002010 - Web: id was already replied to
80002011 - Web: unknown error
80002020 - Twitter: no or bad response
80002021 - Twitter: invalid JSON response
80002022 - Twitter: unknown error
80002023 - Twitter: invalid error code
80002024 - Twitter: could not retrieve twitter id
80002025 - Twitter: could not retrieve media id
80002026 - Twitter: could not upload media
80002027 - Twitter: media file does not exist
80002050 - SMG connect error
80002051 - SMG disconnect error
80002052 - SMG startup error (usually caused by bad authentication with Facebook or Twitter)

Social Media Command List:

socialmediaon

Syntax: socialmediaon

This command initiates communication with the SMG software. If the SMG software connected properly, the variable SMCONNECTED is set to "true". The variable SMERROR is set to true if the Facebook and/or Twitter apps could not be authenticated. 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".

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 <mediafilename>

This command sends "message" as a Twitter private direct message to "recipient". 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.

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.

getwebhookmessages

Syntax: getwebhookmessages

This command retrieves new Facebook page messages for the Facebook page configured in the SMG software AND/OR Text Magic text messages.

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:

message type. "S" means it is a Text Magic text message, "C" means it is a Text Magic confirmation of delivery message, and "F" means it is a Facebook Messenger page message
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) OR the sender's for phone number
the Facebook page id that the message is directed to OR the phone number that the message was directed to.
message id
the text of the message (CR, LF, and TAB characters are removed)

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

pagemessage

Syntax: sendpagemessage message recipientid <messagetag>

This command sends the text "message" as a Facebook Messenger page message to the Facebook user id "recipientid" (page context) with an optional "messagetag". Note that a page-context user id is not the same as a main Facebook user id. Message Tags are a means to send a message later than the 24hr+1 limit - see this Facebook Developer site page for a list of supported tags.

pageimageurl

Syntax: sendpageimageurl imageurl recipientid <messagetag>

This command sends the image "imageurl" as a Facebook Messenger page message to the Facebook user id "recipientid" (page context) with an optional "messagetag. 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. Message Tags are a means to send a message later than the 24hr+1 limit - see this Facebook Developer site page for a list of supported tags.

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 count

This command retrieves up to "count" new web command messages received independently and stored by the SMG software.

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 SMG software 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>reason

- the message was accepted and the web client busy flag is "busy". The value of 'reason' is set by setwebclientbusyreason command.

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 40 characters)
the text of the reply message (up to 128k characters)

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).

setwebclientbusyreason

Syntax: setwebclientbusyreason reason

This command sets the message ('reason') that is reported by the SMG software to web clients when setwebclientbusy is set to 'true' (see getwebcommands).