documentation

As of 2025-03-13, the api for fonetic hyperlocal uses a single websocket endpoint, at wss://api.fonetic.studio/socket. This endpoint expects to receive JSON messages.

The flow for sending messages in a room is as follows:

  1. Using the joinroom command, join a room.

  2. Use the sendmsg command to send a message.

The following commands are exposed through the API

Joining a room

Required arguments:

  • cmd: “joinroom”
  • beaconID: [the beacon identifier]
  • totpcode: [the rotating security code of the beacon]
  • user_lang: [A 2 letter language code specifying in which language the user wants to receive their messages]

Optional arguments:

  • user_name: [The name of the user]. “Unknown” if left empty

Example

{
  "cmd": "joinroom",
  "totpcode": "1234",
  "beaconID": "1",
  "user_lang": "fr",
  "user_name": "Raphael"
}

Return value

The return value for this command is the JSON representation of the current user, consisting of:

  • status: A http status code
  • echocmd: the command that was issued to generate this response
  • user: a representation of the current user:
  • user_ID: A UUID
  • user_name: the chosen username
  • user_lang: the language the user wants to read their messages in.

Return example


{"status": 200, "user": {"user_ID": "HHys9z9eXWtHNRCo4SpYEw", "user_lang": "fr", "user_name": "Raphael"}, "echocmd": "joinroom"}

Sending a message

Required arguments:

  • cmd: “sendmsg”
  • beaconID: [the beacon identifier]
  • totpcode: [the rotating security code of the beacon]
  • user_ID: [the ID returned by joinroom]
  • src_string: [the string the user wants to send]

Example

{
  "cmd": "sendmsg",
  "totpcode": "1023",
  "beaconID": "1",
  "user_ID": "dpj3dEEnfZ5F7rEvt8Yk22",
  "src_string": "Mijn naam is Raphael en ik ben aan het programmeren"
}

Return value

The return value for this command serves as a confirmation of receipt, and consists of:

  • status: A http status code
  • echocmd: the command that was issued to generate this response

Return example

{"status": 200, "echocmd": "sendmsg"}

Receiving messages

Receiving messages happens after joining a room, and the JSON is structured as follows:

{"status": 200, "echocmd": "recvmsg", "message": {"res": "My name is Julia and I'm waiting for the train.", "src_lang": "auto"}, "sender": "Julia"}

Changing the user language

You can change the language you request using the change_language command.

Required arguments:

  • cmd: "change_language"
  • beaconID: [the beacon identifier]
  • totpcode: [the rotating security code of the beacon]
  • user_ID: [the user's ID]
  • user_lang: [A 2 letter language code specifying in which language the user wants to receive their messages]