History Messages

This documentation will describe the History Message (XMHISTMG) endpoint. This endpoint allows users to add messages to account history.

Use cases

  • Panel/alarm application developers who want to add time stamped, non-alarm information to an account.

Add message

Add message text to account history.

Supported attributes

AttributeTypeRequiredDescription
*setMethodstringYesDetermines the endpoint you are calling. Must be XMHISTMG to create a message.
OPTIONstringYesDetermines the method you will be using. Use NEWMESSAGE when adding new messages.
ACCOUNTstringYesThe subscriber account number (9 character max). The system will write the history message to this account.
MESSAGEstringYesDefines the message text that will be written to history.
DESCRIPTIONstringNoA brief description of the message content.
MESGDATEstringNoDetermines the date that should be assigned to the message. Expects MM/DD/YYYY format (Example: 01/09/2024).
MESGTIMEstringNoDetermines the time that should be assigned to the message. Expects HHMI (24-hour) format (Example: 2200).

Note: the MESGDATE and MESGTIME attributes should be used together. If you use one, you should use the other as well. If neither are used, the date and time will be set to the current date and time.

Example request

curl --location "https://example.securemcloud.com/rest/rest.php?dataSource=methods&*view=xmsubmit" \
--header 'X-DICE-APPKEY: {{X-DICE-APPKEY}}' \
--header 'X-DICE-USERNAME: {{X-DICE-USERNAME}}' \
--header 'X-DICE-DATE: {{X-DICE-DATE}}' \
--header 'X-DICE-NONCE: {{X-DICE-NONCE}}' \
--header 'X-DICE-DIGEST: {{X-DICE-DIGEST}}' \
--header 'Accept: application/json' \
--form '*setMethod="XMHISTMG"' \
--form 'OPTION="NEWMESSAGE"' \
--form 'ACCOUNT="DOC123"' \
--form 'MESSAGE="THIS IS MY MESSAGE"' \
--form 'DESCRIPTION="THIS IS MY DESCRIPTION"' \
--form 'MESGDATE="01/01/2023"' \
--form 'MESGTIME="2310"'

Example response

The response will display when the message was written to history. The displayed time will be in NTD format. See the Date Format documentation for instructions on how to convert NTD to UNIX (and vice versa) as necessary.

{
    "MESGDT": "738523.96528"
}

List available messages

Get a list of the available quick select messages.

Supported attributes

AttributeTypeRequiredDescription
*setMethodstringYesDetermines the method you are calling. Must be XMHISTMG to create a message.
OPTIONstringYesDetermines the method you will be using. Use GETMESSAGES when obtaining the list of available messages.

Example request

curl --location "https://example.securemcloud.com/rest/rest.php?dataSource=methods&*view=xmsubmit" \
--header 'X-DICE-APPKEY: {{X-DICE-APPKEY}}' \
--header 'X-DICE-USERNAME: {{X-DICE-USERNAME}}' \
--header 'X-DICE-DATE: {{X-DICE-DATE}}' \
--header 'X-DICE-NONCE: {{X-DICE-NONCE}}' \
--header 'X-DICE-DIGEST: {{X-DICE-DIGEST}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form '*setMethod="XMHISTMG"' \
--form 'OPTION="GETMESSAGES"'

Example response

{
    "ALMESSGS": [
        {
            "MESSAGE": "MESSAGE CODE DEFINITION EXAMPLE "
        },
        {
            "MESSAGE": "CUSTOMER CALLED GAVE CODE FALSE\n"
        },
        {
            "MESSAGE": "DISABLED ACCOUNT "
        },
        {
            "MESSAGE": "FALSE ALARM VERIFIED BY CUSTOMER "
        },
        {
            "MESSAGE": "TEST MESSAGE DESCRIPTION\n"
        },
        {
            "MESSAGE": "New code "
        }
    ]
}

Response fields

FieldDescription
MESSAGEDisplays the quick message text.