API Plugin

Provides a method for external services to execute commands on the bot using both GET and POST requests.

Security note: GET requests are insecure, please use POST instead.

Requirements:

• plugins/api.py
• (other plugins if you intend to call their functionality)

Setup

• Create a self-signed certificate
• Set up your config.json as follows:

  "api_key": "YOUR_API_KEY",
  "api": [
    {
    "certfile": "YOUR_CERT_FILE",
    "name": "YOUR_SERVER_NAME",
    "port": LISTENING_PORT
    }
  ]

Note: You will need to append the bot's user_id to the admin list if you want to be able to run admin commands externally

Sending Commands to the Bot

hangupsbot/tests/api-send.py

A small Python 3 script has been provided to get you started.

usage: api-send.py [-h] url target apikey content

positional arguments:
  url         url to send the data
  target      target conversation id
  apikey      api key from config.apikey
  content     content to send, quote if it contains spaces

optional arguments:
  -h, --help  show this help message and exit

Example Usage

Send "/bot echo hello world" to CONV_ID:

python3 api-send.py https://<YOUR_SERVER_NAME>:<LISTENING_PORT> <CONV_ID> <YOUR_API_KEY> "/bot echo hello world"

Tasker (on Android)

1. Download the Tasker Project xml file
2. Disable Tasker' s beginner mode in preferences->UI->Beginner Mode
3. You'll now see a little house in the bottom left corner, long click it until a menu appears, press import
4. locate where you saved Bot.prj.xml (Note: it must be named exactly that) and press it
5. You'll now have a symbol "Bot" besides the small house, click it.
6. Click VARS in the top menu, press every variable to set them
7. Go to tasks and try them out

---

(OLD) Example GET and POST general requests

SECURITY WARNING: DO NOT USE GET-BASED REQUESTS IN PRODUCTION ENVIRONMENTS - THE URL MAY BE LOGGED BY THE WEB-SERVER/PROXY. USE POST METHOD INSTEAD.

Using POST:

Ensure that you have "Content-length" in your header Params (in JSON) and:

{
    "key": "api_key",
    "sendto": "user_id or chat_id to send the message to",
    "content": "content of message"
}

Example content:

"<b>Hello</b> World!"
"/bot ping"

Using GET:

Path: https://[NAMEOFSERVER]:[NAMEOFPORT]/[APIKEY]/[SENDTO]/[CONTENT]

Example content (URL encoded):

"%3Cb%3EHello%3C%2Fb%3E%20World%21"
"%2Fbot%20ping"

EXAMPLE COMMANDS:

Add user to a chat (requires convtools.py)

POST

'key': 'APIKEY'
'sendto': 'YOURGID'
'content': '/bot addusers [GID] into [CID]'

GET

https://[ADDRESS]/[APIKEY]/[YOURGID]/%2Fbot%20addusers%20[GID]%20into%20[CID]

Create a conversation between several users (requires convtools.py)

POST

'key': 'APIKEY'
'sendto': 'YOURGID'
'content': '/bot createconversation [GID1] [GID2] [GID3]'

GET

https://[ADDRESS]/[APIKEY]/[YOURGID]/%2Fbot%20createconversation%20[GID1]%20[GID2]%20[GID3]

Create a syncout between two or more chats (requires syncrooms_config.py)

POST

'key': 'APIKEY'
'sendto': 'YOURGID'
'content': '/bot attachsyncout [CID1] [CID2] [CID3]'

GET

https://[ADDRESS]/[APIKEY]/[YOURGID]/%2Fbot%20attachsyncout%20[CID1]%20[CID2]%20[CID3]