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