MessengerManager¶

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

In this document:

Schema
Custom Operations
Structures
Examples

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

The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:

POST  /aps/2/services/messenger-manager/<operation-path>?<query-params>

{/*<body params>*/}

In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.

Custom Operations ¶

OPERATION	VERB	PATH	RETURNS	Description
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 staff members of the account explicitly specified by the `accountId` or implicitly by the `userId` in the Message structure. If a user is specified in the `message` structure by the `userId` property, this is used to determine the account.
sendMessageToUser	POST	/messenger/sendToUser	If successful, this method returns the 200 OK standard status code.	Send the required message to the user specified by the `userId` property in the Message structure.
getSubscriptions	GET	/messenger/subscriptions	If successful, this method returns a list of NotificationSubscription objects in the response body.	Get notification subscriptions.
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.
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.
addMessageType	POST	/messenger/messagetypes	If successful, this method returns the MessageType object in the response body.	Register a message type.
deleteMessageType	DELETE	/messenger/messagetypes/{msgTypeId}	If successful, this method returns the 200 OK standard status code.	Delete the specified message type (by APS ID).

sendMessage¶

HTTP Request

POST /aps/2/services/messenger-manager/messenger/send

Description

Send the specified message through the messenger manager to all staff members of the account explicitly specified by the accountId or implicitly by the userId in the Message structure. If a user is specified in the message structure by the userId property, this is used to determine the account.

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/services/messenger-manager/messenger/sendToUser

Description

Send the required message to the user specified by the userId property in the Message structure.

Parameters

PARAMETER	TYPE	DESCRIPTION
message	Message	Message

Returns

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

getSubscriptions¶

HTTP Request

GET /aps/2/services/messenger-manager/messenger/subscriptions

Description

Get notification subscriptions.

Returns

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

createSubscription¶

HTTP Request

POST /aps/2/services/messenger-manager/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.

getMessageTypes¶

HTTP Request

GET /aps/2/services/messenger-manager/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.

addMessageType¶

HTTP Request

POST /aps/2/services/messenger-manager/messenger/messagetypes

Description

Parameters

PARAMETER	TYPE	DESCRIPTION
event	MessageType	Message type MessageType

Returns

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

deleteMessageType¶

HTTP Request

DELETE /aps/2/services/messenger-manager/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.

Structures ¶

Message¶

Message.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
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.
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.
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.
params	Object	Required	The list of the message specific parameters with values assigned to them.

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	DESCRIPTION
locale	String	Not Required	Speifies a locale, for example, ‘de_DE’.
from	String	Not Required	It is the email `From` header.
subject	String	Required	The translated subject of the email notification.
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’).

MessageType¶

The structure used to register a message type.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
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.
description	String	Not Required	Full description of the email template as displayed in the open email template in the provider control panel.
templates	Array of Template	Not Required	A list of the Template objects.
subscribeByDefault	Boolean	Not Required	Specifies if by default a new user will be subscribed (true) to the notification of this type or not (false).
contentType	Enum	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.

Examples ¶

Note

Registration and modification of message types is allowed to APS applications only.

Get Registered Message Types¶

To get a list of registered message types, send the following request:

GET /aps/2/services/messenger-manager/messenger/messagetypes

The response will look as follows (shortened for brevity):

HTTP/1.1 200 OK

[
  {
    "id": 2,
    "name": "Register domain method failed",
    "description": "Register domain method failed",
    "subscribeByDefault": false
  },
  {
    "id": 5,
    "name": "Check availability domains method failed",
    "description": "Check availability domains method failed",
    "subscribeByDefault": false
  },
  {
    "id": 1,
    "name": "License was suspended or terminated",
    "description": "License was suspended or terminated",
    "subscribeByDefault": false
  },
  {
    "id": 6,
    "name": "License update failed",
    "description": "License update failed",
    "subscribeByDefault": false
  },
  /* ... */
]

Get Subscriptions to Mail Notifications¶

To get a list of subscriptions to mail notifications, send the following request:

GET /aps/2/services/messenger-manager/messenger/subscriptions

The response will look as follows (shortened for brevity):

HTTP/1.1 200 OK

[
  {
    "msgTypeId": 2,
    "userId": "4cd4f457-9f4d-4ce7-88c5-a5818441a773"
  },
  {
    "msgTypeId": 5,
    "userId": "4cd4f457-9f4d-4ce7-88c5-a5818441a773"
  },
  /* ... */
]

Register a Message Type¶

To register a custom message type, an application must send a request similar to the following:

POST /aps/2/services/messenger-manager/messenger/messagetypes/

{
   "id": null,
   "name": "New VPS demo subscription",
   "description": "New VPS demo subscription is created",
   "templates": [
      {
         "locale": "en",
         "from": "\"${vendor_company_name}\" <${vendor_tech_email}>",
         "subject": "New VPS Demo subscription",
         "body": "The customer ${customerName} subscribed to the VPS Demo application. Subscription APS ID -  ${subscriptionId}",
         "contentType":null
      }
   ],
   "subscribeByDefault": true,
   "contentType": "text/plain"
}

The response will look as follows:

HTTP/1.1 200 OK

{
   "id": 46,
   "name": "New VPS demo subscription",
   "description": "New VPS demo subscription is created",
   "templates": [
      {
         "locale": "en",
         "from": "\"${vendor_company_name}\" <${vendor_tech_email}>",
         "subject": "New VPS Demo subscription",
         "body": "The customer ${customerName} subscribed to the VPS Demo application. Subscription APS ID -  ${subscriptionId}"
      }
   ],
   "subscribeByDefault": true,
   "contentType": "text/plain"
}

Send a Notification¶

To send a notification by email, an application must request it as follows:

POST /aps/10.1/resources/36948aca-ab2c-4a01-8766-668eaf655583//messenger/send

{
   "msgTypeId": "46",
   "name": null,
   "userId": null,
   "accountId": "0e34371a-ac67-48ff-89e1-c5200a90baa2",
   "params": {
      "customerName": "John Smith",
      "subscriptionId":"38cd2bf8-6077-4e9a-b25c-c4cb5826490e"
   }
}

The response will look as follows:

HTTP/1.1 200 OK

{
   "msgTypeId": 46,
   "accountId": "0e34371a-ac67-48ff-89e1-c5200a90baa2",
   "params": {
      "customerName": "John Smith",
      "subscriptionId": "38cd2bf8-6077-4e9a-b25c-c4cb5826490e",
      "message_type": "46",
      "account_id_list": "1000001"
   }
}

Remove a Message Type¶

To remove a message type, for example, during removal of the APS application instance, the application must send the following request:

DELETE /aps/2/services/messenger-manager/messenger/messagetypes/46

The response must be as follows:

HTTP/1.1 200 OK

Concepts¶

The Mail Notifications document explains the concepts and provides examples on the messenger operations for an APS connector based on the APS PHP framework.

← Messaging Notifications

Notification Management →

CloudBlue Commerce API

Table Of Contents

Previous topic

Next topic

MessengerManager¶

Schema ¶

Custom Operations ¶

sendMessage¶

sendMessageToUser¶

getSubscriptions¶

createSubscription¶

getMessageTypes¶

addMessageType¶

deleteMessageType¶

Structures ¶

Message¶

NotificationSubscription¶

Template¶

MessageType¶

Examples ¶

Get Registered Message Types¶

Get Subscriptions to Mail Notifications¶

Register a Message Type¶

Send a Notification¶

Remove a Message Type¶

Concepts¶

CloudBlue Commerce API

Table Of Contents

Previous topic

Next topic

MessengerManager¶

Schema¶

Custom Operations¶

sendMessage¶

sendMessageToUser¶

getSubscriptions¶

createSubscription¶

getMessageTypes¶

addMessageType¶

deleteMessageType¶

Structures¶

Message¶

NotificationSubscription¶

Template¶

MessageType¶

Examples¶

Get Registered Message Types¶

Get Subscriptions to Mail Notifications¶

Register a Message Type¶

Send a Notification¶

Remove a Message Type¶

Concepts¶

Schema ¶

Custom Operations ¶

Structures ¶

Examples ¶