message.proto

/* Message management.
 *
 *
 */
syntax = "proto3";

package hiber.message;

import "google/protobuf/struct.proto";

import "base.proto";
import "modem.proto";
import "tag.proto";

option java_multiple_files = false;
option java_package = "global.hiber.api.grpc.message";
option java_outer_classname = "MessageApi";
option go_package = ".;hiber";

/* This service contains calls to list and manage messages. */
service MessageService {
    /* List messages for the selected modems. */
    rpc List (ListMessages.Request) returns (ListMessages.Response);

    /* Count messages for the selected modems. */
    rpc Count (CountMessages.Request) returns (CountMessages.Response);
}

/* Message received from a device in the field.
 * Messages have a number of default field, like sent and received time, and location. In addition, depending on the
 * assigned body parsers, messages have a number of body fields with values.
 */
message Message {
    /* Parsed message body.
     * If any parsers are configured for the modem, they are applied to the message.
     * The result is stored either as a json object or an error string.
     */
    message ParsedBody {
        /* Globally unique identifier of the parser that was used. */
        string parser_identifier = 6;

        /* Name of the parser that was used. */
        string parser_name = 2;

        oneof parsed {
            /* Error while parsing the message body. */
            string error = 4;

            /* Result of parsing the body with this parser. */
            google.protobuf.Struct result = 5;
        }

        reserved 1, 3;
    }

    /* Unique message identifier. */
    uint64 message_id = 1;

    /* Modem number of the modem that sent the message. */
    string modem_number = 2;

    /* The name of the modem that sent the message. */
    string modem_name = 3;

    /* The device identifier for the modem that sent the message (e.g. a MAC address). */
    string modem_identifier = 4;

    /* Time the message was sent from the modem. */
    Timestamp sent_at = 5;

    /* Time the message was received on the server. */
    Timestamp received_at = 6;

    /* Modem location when the message was sent. */
    Location location = 7;

    /* Message body. */
    bytes body = 8 [deprecated = true];

    /* Message body convenience object. */
    BytesOrHex body_bytes = 9;

    /* A list of applied body parsers and their results. */
    repeated ParsedBody body_parsed = 10;

    /* Convenience flag marking whether the body was parsed successfully by at least one parser. */
    bool body_parsed_successfully = 11;

    /* True if the the TEST source is in the sources. */
    bool is_test = 12;

    /* Whether this message contains other messages. */
    bool is_gateway_message = 13;

    /* The gateway message this message was sent in. */
    uint64 via_gateway_message = 14;

    /* Message metadata, defined by the modem or gateway. */
    google.protobuf.Struct metadata = 15;

    /* Flattened results of all successful body parsers.
     * This is a convenience to access the fields from body_parsed, but if any fields are present in
     * multiple body_parsed results, it is not defined which field will be used in this Struct.
     * This may change in the future.
     */
    google.protobuf.Struct body_fields = 16;

    /* The tags of the modem that sent the message. */
    repeated tag.Tag tags = 19;

    /* The names of the tags of the modem that sent the message. */
    repeated string tag_names = 20;
}

/* Selection object for modem messages.
 * Filter messages by modem and time sent (note that this is not the time the message was received)
 */
message MessageSelection {
    /* Select the modems to return messages for. Optional, when omitted or empty everything is included. */
    optional modem.ModemSelection modem_selection = 1;

    /* Filter message by time range. */
    optional TimeRange time_range = 2;

    /* Include messages by id */
    repeated int64 modem_message_ids = 4;

    /* Replace whatever time zone was specified in the start and end time with the modem time zone.
     * This means you may get values outside of the original time range, but can be useful when requesting
     * data for a date, for example.
     * For example: start.textual = 2022-01-01, end.textual = 2022-02-01 would return a month of data in UTC time.
     * When combined with this flag, it would return that month of data in the time zone of the modem, which may
     * even be different per modem.
     */
    optional bool override_time_range_with_modem_time_zone = 3;
}

message ListMessages {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the messages to list. Optional, when omitted or empty everything is included. */
        optional MessageSelection selection = 2;
        optional Pagination pagination = 3;
    }

    message Response {
        repeated Message messages = 1;
        Request request = 2;
        Pagination.Result pagination = 3;
    }
}

message CountMessages {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the messages to count. Optional, when omitted or empty everything is included. */
        optional MessageSelection selection = 2;

        /* Numeric timezone offset for day grouping. Optional. */
        optional int32 time_zone_offset = 5;

        /* Timezone string for day grouping. Optional. */
        optional string time_zone = 6;
    }
    message Response {
        message MessageCount {
            Date date = 1;
            int32 count = 2;
        }

        repeated MessageCount message_count_per_day = 1;
        Request request = 2;
    }
}