docs/src/content/docs/components/iota/endpoints.md

title
Endpoints

All messages to the Iota are either from the Omikron directly, from a Client or another Iota trying to message a User on the Iota. All messages will be marked with a sender_id this will be added on the Omikron. It is important to note that the Iota ID is not shared with others as it is what verifies the Iota users to Tensamin. In the response the sender_id & receiver_id must be swapped as sender. When a message comes from an iota without a sender-id that the iota has access to or is designated for the client (33333333-3333-3333-3333-333333333333) the message will not be send.

Messages

Messaging Lifecycle

The messaging system follows a strict derivation loop to ensure delivery and correct state synchronization:

1. The client sends a message_send to its Iota.
2. The Iota sends a response message_send as confirmation back to the client.
3. The Iota sends a message_other_iota to the chat partner's Iota.
   • If it times out:
     • The initial Iota sends a message_state to the client with the state "sending".
   • If successful:
     • The other Iota receives the message_other_iota and handles it.
     • The other Iota informs its client with a message_live.
     • If the client doesn't answer:
       1. The other Iota will send a message_state to the initial Iota with the state "sent".
       2. The initial Iota will store the state and forward the message_state to its client.
     • If the client answers with message_state:
       1. The other Iota will store the state (either "received" or "read") and forward the message_state to the initial Iota.
       2. The initial Iota will store the state and forward the message_state to its client.

Client adds someone to their contacts

When adding via name, the omikron will intercept and fill the chat_partner_id. The iota will never read, or handle the chat_partner_name.

REQ:

{
  "sender_id": "<user-id>",
  "receiver_id": "<user-id>",

  "type": "add_conversation",
  "id": "<uuid>",
  
  "data": {
    "chat_partner_id": id,
    "chat_partner_name": "name"
  }
}

RES:

{
  "sender_id": "<user-id>",
  "receiver_id": "<user-id>",

  "type": "add_conversation",
  "id": "<uuid>",
  "data": {}
}

Client messages someone

REQ:

{
  "sender_id": "<user-id>",
  "receiver_id": "<user-id>",

  "type": "message_send",
  "id": "<uuid>",
  "data": {
    "receiver_id": "<uuid>",
    "content": "<markdown (encrypted)>",
    "files": [
      {
        "name": "<cool name>",
        "id": "<uuid>",
        "type": "[ image | image_top_right | file ]"
      }
    ]
  }
}

RES:

{
  "sender_id": "<user-id>",
  "receiver_id": "<user-id>",

  "type": "message_send",
  "id": "<uuid>",
  "data": {}
}

Client loads messages

REQ:

{
	"sender_id": "<user-id>",

	"type":"messages_get",
	"id": "<uuid>",
	"data": {
		"user_id": "<user-id>",
		"amount": int,
		"offset": int
	}
}

RES:

{
  "sender_id": "<iota-id>",

  "type": "messages_get",
  "id": "<uuid>",
  "data": {
    "messages": [
      {
        "sent_by_self": true,
        "timestamp": 0, // UNIX Timestamp for time sent
        "content": "<markdown (encrypted)>",
        "files": [
          {
            "name": "<cool name>",
            "id": "<uuid>",
            "type": "[ image | image_top_right | file ]"
          }
        ],
        "tint": "<hex color>",
        "avatar": false, // unless false key is removed
        "display": false // unless false key is removed
      }
    ]
  }
}

Send a message to other Iota

REQ:

{
  "type": "message_send",
  "id": "<message_id>",
  "data": {
    "receiver_id": "99999999-8888-7777-6666-555555555555",
    "content": "Hello, how are you?"
  }
}

RES:

{
  "type": "message",
  "id": "<message_id>",
  "receiver": "<user_id>"
}

Receive live message (message_other_iota)

UPDATE:

{
	"type": "message_live",
	"id": "<message_id>",
	"receiver": "<user_id>",

	"data": {
		"send_time": unixstamp,
		"message": "<content>",
		"sender_id": "99999999-8888-7777-6666-555555555555"
	}
}

Communities

Client storing a community on their Iota

REQ:

{
  "type": "add_community",
  "id": "<message_id>",
  "receiver": "<user_id>",

  "data": {
    "community_address": "community_address",
    "community_title": "community_title",
    "position": "x.y.z"
  }
}

RES:

{
  "type": "add_community",
  "id": "<message_id>",
  "receiver": "<user_id>",

  "data": {}
}

Client loading communities from their Iota

REQ:

{
  "type": "get_communities",
  "id": "<message_id>",

  "data": {}
}

RES:

{
  "type": "get_community",
  "id": "<message_id>",
  "receiver": "<user_id>",

  "data": {
    "communities": [
      {
        "community_address": "enc_community_address",
        "community_title": "enc_community_title",
        "position": "x.y.z" // Frontend defines folders etc
      },
      {
        "community_address": "enc_community_address",
        "community_title": "enc_community_title",
        "position": "x.y.z"
      }
    ]
  }
}

Remove a community

REQ:

{
  "type": "remove_community",
  "id": "<message_id>",

  "data": {
    "community_address": "community-uuid-or-address"
  }
}

RES:

{
  "type": "remove_community",
  "id": "<message_id>",
  "receiver": "<user_id>"
}

User Settings

Save user Settings on Iota

REQ:

{
  "type": "settings_save",
  "id": "<message_id>",

  "data": {
    "setting_name": "<name of category>",
    "payload": {
      "this": "will",
      "be": "saved",
      "on": "the",
      "iota": "!"
    }
  }
}

RES:

{
  "type": "settings_save",
  "id": "<message_id>",
  "receiver": "<user_id>",

  "data": {}
}

Load user Settings

REQ:

{
  "type": "settings_load",
  "id": "<message_id>",

  "data": {
    "setting_name": "<name of category>"
  }
}

RES:

{
  "type": "settings_load",
  "id": "<message_id>",
  "receiver": "<user_id>",

  "data": {
    "setting_name": "<name of category>",
    "payload": {
      "this": "will",
      "be": "saved",
      "on": "the",
      "iota": "!"
    }
  }
}