MessengerManager

This APS type represents the platform built-in email messenger manager as explained in the Mail Notifications concepts.

Schema

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "MessengerManager",
  "id": "http://www.parallels.com/pa/pa-core-services/messenger-manager/1.0",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "access": {
    "global": true
  },
  "operations": {
    "sendMessage": {
      "path": "/messenger/send",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "message": {
          "kind": "body",
          "type": "Message"
        }
      }
    },
    "sendMessageToUser": {
      "path": "/messenger/sendToUser",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "message": {
          "kind": "body",
          "type": "Message"
        }
      }
    },
    "getSubscriptions": {
      "path": "/messenger/subscriptions",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "NotificationSubscription"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "createSubscription": {
      "path": "/messenger/subscriptions",
      "verb": "POST",
      "response": {
        "type": "NotificationSubscription"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "subscription": {
          "kind": "body",
          "type": "NotificationSubscription"
        }
      }
    },
    "getMessageTypes": {
      "path": "/messenger/messagetypes",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "MessageType"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "addMessageType": {
      "path": "/messenger/messagetypes",
      "verb": "POST",
      "response": {
        "type": "MessageType"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "event": {
          "kind": "body",
          "type": "MessageType"
        }
      }
    },
    "deleteMessageType": {
      "path": "/messenger/messagetypes/{msgTypeId}",
      "verb": "DELETE",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "msgTypeId": {
          "kind": "path",
          "type": "integer"
        }
      }
    }
  },
  "structures": {
    "Message": {
      "type": "object",
      "properties": {
        "msgTypeId": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "userId": {
          "type": "string"
        },
        "accountId": {
          "type": "string"
        },
        "params": {
          "type": "object",
          "required": true
        }
      }
    },
    "NotificationSubscription": {
      "type": "object",
      "properties": {
        "msgTypeId": {
          "type": "integer",
          "required": true
        },
        "userId": {
          "type": "string",
          "required": true
        }
      }
    },
    "Template": {
      "type": "object",
      "properties": {
        "locale": {
          "type": "string"
        },
        "from": {
          "type": "string"
        },
        "subject": {
          "type": "string",
          "required": true
        },
        "body": {
          "type": "string",
          "required": true
        },
        "contentType": {
          "type": "string"
        }
      }
    },
    "MessageType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "required": true,
          "readonly": true,
          "final": true
        },
        "name": {
          "type": "string",
          "required": true,
          "final": true
        },
        "description": {
          "type": "string"
        },
        "templates": {
          "type": "array",
          "items": {
            "type": "Template"
          }
        },
        "subscribeByDefault": {
          "type": "boolean"
        },
        "contentType": {
          "type": "string",
          "enum": [
            "text/plain",
            "text/html"
          ]
        }
      }
    }
  }
}

Custom Operations

OPERATION	VERB	PATH	RETURNS	Description
addMessageType	POST	/messenger/messagetypes	If successful, this method returns the MessageType object in the response body.	Register a message type.
createSubscription	POST	/messenger/subscriptions	If successful, this method returns the NotificationSubscription object in the response body.	Subscribe the user that calls the method to the specified notification.
deleteMessageType	DELETE	/messenger/messagetypes/{msgTypeId}	If successful, this method returns the 200 OK standard status code.	Delete the specified message type (by APS ID).
getMessageTypes	GET	/messenger/messagetypes	If successful, this method returns a list of MessageType objects in the response body.	Get a list of the registered message types.
getSubscriptions	GET	/messenger/subscriptions	If successful, this method returns a list of NotificationSubscription objects in the response body.	Get notification subscriptions.
sendMessage	POST	/messenger/send	If successful, this method returns the 200 OK standard status code.	Send the specified message through the messenger manager to all account staff members or to a user as specified in the message structure.
sendMessageToUser	POST	/messenger/sendToUser	If successful, this method returns the 200 OK standard status code.	Send the required message to all account staff members subscribed to this message type.

addMessageType

HTTP Request

POST /aps/2/resources/{aps-id}/messenger/messagetypes

Description

Register a message type.

Parameters

PARAMETER	TYPE	DESCRIPTION
event	MessageType	Message type MessageType

Returns

If successful, this method returns the MessageType object in the response body.

createSubscription

HTTP Request

POST /aps/2/resources/{aps-id}/messenger/subscriptions

Description

Subscribe the user that calls the method to the specified notification.

Parameters

PARAMETER	TYPE	DESCRIPTION
subscription	NotificationSubscription	Notification subscription NotificationSubscription

Returns

If successful, this method returns the NotificationSubscription object in the response body.

deleteMessageType

HTTP Request

DELETE /aps/2/resources/{aps-id}/messenger/messagetypes/{msgTypeId}

Description

Delete the specified message type (by APS ID).

Parameters

PARAMETER	TYPE	DESCRIPTION
msgTypeId	Integer	Message type ID

Returns

If successful, this method returns the 200 OK standard status code.

getMessageTypes

HTTP Request

GET /aps/2/resources/{aps-id}/messenger/messagetypes

Description

Get a list of the registered message types.

Returns

If successful, this method returns a list of MessageType objects in the response body.

getSubscriptions

HTTP Request

GET /aps/2/resources/{aps-id}/messenger/subscriptions

Description

Get notification subscriptions.

Returns

If successful, this method returns a list of NotificationSubscription objects in the response body.

sendMessage

HTTP Request

POST /aps/2/resources/{aps-id}/messenger/send

Description

Send the specified message through the messenger manager to all account staff members or to a user as specified in the message structure.

Parameters

PARAMETER	TYPE	DESCRIPTION
message	Message	The Message structure.

Returns

If successful, this method returns the 200 OK standard status code.

sendMessageToUser

HTTP Request

POST /aps/2/resources/{aps-id}/messenger/sendToUser

Description

Send the required message to all account staff members subscribed to this message type.

Parameters

PARAMETER	TYPE	DESCRIPTION
message	Message	Message

Returns

If successful, this method returns the 200 OK standard status code.

Structures

Message

Message

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
accountId	String	Not Required		Account ID is alternative to userId and used to specify the APS ID of the account whose staff members must receive the notification.
msgTypeId	Integer	Not Required		ID of the registered message type.
name	String	Not Required		Short description of the message type as displayed in the list of email templates in the provider control panel.
params	key-value pairs of String	Required		The list of the message specific parameters with values assigned to them.
userId	String	Not Required		User ID is alernative to accountID and used to specify the APS ID of the user whom the notification is addressed.

MessageType

The structure used to register a message type.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
contentType	String	Not Required		An enum variable that can be either “text/html” or “text/plain”. It informs the system whether the message body should be interpreted as a plain text or parsed as an HTML code.
description	String	Not Required		Full description of the email template as displayed in the open email template in the provider control panel.
id	Integer	Required Read Only Final		ID assigned by the platform.
name	String	Required Final		The name of the message type as displayed in the list of email templates in the provider control panel.
subscribeByDefault	Boolean	Not Required		Specifies if by default a new user will be subscribed (true) to the notification of this type or not (false).
templates	Template array	Not Required		A list of the Template objects.

NotificationSubscription

The structure used in the custom operations with notification subscriptions.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
msgTypeId	Integer	Required		ID of the subscribed message type.
userId	String	Required		ID of the subscribed user.

Template

A template is created for a locale (language) and includes the translated subject and the message body.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
body	String	Required		The translated notification body of the email notification. This is the actual description of the occasion.
contentType	String	Not Required		Specifies if the content is a plain text (‘text/plain’) or an HTML code (‘text/html’).
from	String	Not Required		It is the email From header.
locale	String	Not Required		Speifies a locale, for example, ‘de_DE’.
subject	String	Required		The translated subject of the email notification.

Examples

Since the considered APS type contains custom operations, refer to Custom Operations for the general explanation of their structure and examples of operation calls.

← Messaging Notifications

Notification Management →