6.2 KiB
API Documentation
Home | Configuration | API Documentation | HBlink Website
The API is a new feature that allows users to interact with external applications via SMS and send messages users on other HBLink servers. The API is built into the D-APRS dashboard. All interaction takes place over HTTP POST requests in JSON format. This allows a single application to be used by multiple servers. Applications can be delevopen in multiple langauges.
There are presently 3 modes for data exchange, "msg_xfer", "app", and "raw".
app
app mode is used specify the request as an app request. An app request contains a one time token generated by the sending HBLink server allowing the external application to send a one time response, without having to have login credentials on the sending server. The auth_token can only be used once.
Example of app request, initiated by a user on an HBLink server via SMS:
{ "mode": "app", "system_shortcut": "ABC", "server_name": "Test HBlink Network", "response_url": "http://localhost:8093/api/", "auth_token": "1234567899", "data": { "source_id": 1234, "slot": 2, "msg_type": "unit", "msg_format": "motorola", "message": "TIME" } }
mode: Set to "app" as this is an app request.
system_shortcut: This is set in the sending server's config.
server_name: This is the name of the sending server.
Response_url: This is the URL where we should send a response. We can initiate a POST to this URL for a response. This is the URL of the sending server's D-APRS dashboard.
auth_token: This is the auth_token of the sending server. Our response must contain this. See example below.
source_id : The source radio DMR ID.
slot: Timeslot the message was received on.
msg_type: Type of call received. This should be group or unit.
msg_format: Format of the received SMS. A value of motorola is the only option at this time.
message: The actual text of the SMS.
Below is an example of a response that can be sent back to the sending HBLink server. The response is sent as a POST to the response:
{ "mode": "app", "app_name": "Test HBlink App", "app_shortcut": "APP", "auth_token": "1234567899", "data": { "1": { "destination_id": 3153591, "slot": 0, "msg_type": "unit", "msg_format": "motorola", "message": "The time is 21:25." }, "2": { "destination_id": 3153591, "slot": 0, "msg_type": "unit", "msg_format": "motorola", "message": "The date is April 26th, 2021." } } }
mode: Set to "app" as this is an app response.
app_shortcut: This is the system shortcut of the external application.
app_name: This is the name of the responding application.
auth_token: This is the auth_token that was originally sent.
destination_id: DMR ID of destination radio.
slot: Timeslot to send message on. A value of 0 will allow the receiving server to determine which timeslot to send the generated SMS on. This should be 0 most of the time. Other values are 1 or 2, for timeslots.
msg_format: Format to generate SMS in. A value of motorola is the only option at this time.
message: The actual text of the SMS.
Multiple SMS can be generated from a single response, useful for sending multiple SMS as a response.
msg_xfer
msg_xfer is used to send a message. When the D-APRS dashboard receives a msg_xfer request, it generates an SMS message and places it in HBLink's SMS sending que.
With msg_xfer, there are 2 authentication types, "public" and "private". With private authentication, the requesting server (or application) must provide a username and password, specified in authorized_users of the receiving server's rules.py. Public authentication is still a work in progress. Public authentication will allow one server to send to another server without having a shared username or password.
Here is an example of a msg_xfer JSON POST using private authentication:
{ "mode": "msg_xfer", "system_shortcut": "ABC", "server_name": "Test HBlink Network", "response_url": "http://localhost:8093/api/", "auth_type": "private", "credentials": { "user": "test_name", "password": "passw0rd" }, "data": { "1": { "source_id": 1234, "destination_id": 3153591, "slot": 0, "msg_type": "unit", "msg_format": "motorola", "message": "text of the message" }, "2": { "source_id": 1234, "destination_id": 3153591, "slot": 0, "msg_type": "unit", "msg_format": "motorola", "message": "text of the 2nd message" } } }
system_shortcut: This is set in the sending server's config. This value is used to find a username and password on the receiving server's side for authentication. This is also the shortcut that users specify in their SMS.
server_name: This is the name of the sending server.
Response_url: This is the URL where we should send a response. This is important for public authentication. It is the location of the sending servers D-APRS dashboard.
auth_type: pubic or private. If private, then "credentials" will be appended with the username and password.
data: The dashboard forms an SMS based on the values in this field.
Multiple SMS can be generated from a single request, useful for sending an SMS to multiple recipients or multiple messages to the same recipient.
source_id and destination_id: The source and destination DMR ID.
slot: Timeslot to send message on. A value of 0 will allow the receiving server to determine which timeslot to send the generated SMS on. This should be 0 most of the time. Other values are 1 or 2, for timeslots.
msg_type: This should be group or unit. Unit for a private call, group for a group call.
msg_format: Format to generate SMS in. A value of motorola is the only option at this time.
message: The actual text of the SMS.
raw
This is still a work in progress.