History Messages

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

See the Authentication documentation for information on how to obtain the authentication headers within the request.

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"
}

Add message to existing event

Add message text to an existing alarm event. See the Date Format documentation for instructions on how to convert NTD to UNIX (and vice versa) as necessary.

Supported attributes

AttributeTypeRequiredDescription
*setMethodstringYesDetermines the endpoint you are calling. Must be XMHISTMG to add a history message.
OPTIONstringYesDetermines the method you will be using. Use ADDRANGE when adding messages to existing history events.
STATUS_NOTIFICATIONstringNoDetermines if a status message should return when adding messages to existing events.
ACCOUNTstringYesThe subscriber account number (9 character max). The system will write the history message to an event assigned to this account.
HISTORY_EVENT_NTDstringYesNTD date of the requested event.
INCIDENT_NUMBERstringYesUnique identifier created by the system and assigned to the event.
MESSAGEstringYesDefines the message text that will be assigned to the event.

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="ADDRANGE"' \
--form 'STATUS_NOTIFICATION="Y"' \
--form 'ACCOUNT="00DICE"' \
--form 'HISTORY_EVENT_NTD="739643.68763"' \
--form 'INCIDENT_NUMBER="116257"' \
--form 'MESSAGE="Adding a message to an existing alarm event."'

Example response 

{
    "STATUS": "SUCCESS",
    "HTTPCODE": "200"
}

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.

Possible error messages

Invalid method

Verify XMHISTMG is specified for the *setMethod attribute.

{
    "ERROR_CODE": "999",
    "ERROR_DESCRIPTION": "INVALID%20METHOD%20METHOD",
    "PROGRAM_ERROR": "11",
    "PROGRAM_ERROR_DESCRIPTION": "Missing%20or%20Duplicate%20key",
    "ERROR_ON_LINE": "240",
    "ADDITIONAL_INFO": "%3CMETHOD_NAME%3EXMHISTM%20%3C%2FMETHOD_NAME%3E"
}
← View Account History
History Event Details →