# API Documentation ## [Home](https://kf7eel.github.io/hblink3/) | [Configuration](/hblink3/config_doc.html) | [API Documentation](https://kf7eel.github.io/hblink3/api_doc.html) | [HBlink Website](https://hblink-org.github.io/) ---- 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.