App Push API

The App Push APIs are intended to configure the App Push channel and can be used to register devices and to gather consent. Registration is needed to identify the devices where the Push Notification should arrive. Consent is needed to confirm that the user approves to receive the pushes. Users can withdraw their consent in order not to receive notifications, but they can also unregister.

See operations on Register API and Consent API.

Register API

The Register API is used for Registering and Unregistering Android or IOS Push Application Recipients in Agillic.

Register

With the Register API you can:

  • Register a new device to receive Push Notifications for a Recipient
PUT /apps/register/EMAIL=customer.email@agillic.com
  • Unregister an existing device for a Recipient
PUT /apps/unregister/EMAIL=customer.email@agillic.com

The Unique recipient identifier can be in the form of a recipient id or as a pair of person data field & its value

When sending the requests, the Json body can contain:

{
    "appInstallationId": ...,
    "clientAppId": ...,
    "clientAppVersion": ...,
    "deviceModel": ...,
    "osName": ...,
    "osVersion": ...,
    "pushNotificationToken": ...,
    "firstRegister": ...,
    "lastRegister": ...,
    "countRegister": ...,
    "modelDimX": ...,
    "modelDimY": ...,
    "consent": [
        {          
          "type": ,
          "validUntil": 
        }
    ]
}

Where:

  • the appInstallationId is an identifier for the login on the device (always required)
  • the clientAppId is the customer application id (always required)
  • the clientAppVersion is the customer application version
  • the osName can be either ios or android (always required)
  • the osVersion is the OS version
  • the deviceModel is the device model
  • the pushNotificationToken is the app token (always required when registering)
  • the modelDimX is the device width
  • the modelDimY is the device height
  • consent is an array of consent objects (see the Consent API section)

Examples:

Register a new device for a Recipient identified by his Agillic ID:

And respond with an HTTP status code of 200 OK.
Register a new device for a Recipient identified by a Person Data / Value pair:

And respond with a HTTP status code of 200 OK.

Optionally, the register request can be enhanced with an array of consent objects, which mean giving consent to a specific type, valid until an optional specific date. If no date specified in consent, consent is given forever.

Unregister

Unregister the previously registered device for the Recipient:

Consent API

Recipients are required to give consent to certain features in an app. The consent API allows you to record that a recipient has given consent in Agillic. Consent can be given for a period of time (“validUntil”), or if not expressed will be assumed to be given until withdrawn. Currently, we support consent to push notifications only.

Give consent

  • These APIs allow you to register and withdraw any consent that a recipient may have given in your app. Currently we support consent to push notifications. This consent will be required in order for Agillic to send push notifications to the recipient.
  • It is also possible to give in register API a list of consent objects, which is equivalent as making another request to give consent. See register consent parameter.
PUT /apps/consent/EMAIL=customer.email@agillic.com

When sending the request, the JSON body should contain:

Example:

Withdraw consent

DELETE /apps/consent/EMAIL=customer.email@agillic.com

When sending the request, the JSON body should contain:

Example:

Feedback API

Feedback of push notifications can be provided directly from a device. The feedback API allows you to send message back to Agillic System. The push notification on the device contains a specific field agillic_report_id. The agillic_report_id needs to be added as reportId to the feedback call in order to record that the push notification was received/opened on the device.

Handle feedback

The feedback API receives a request to be processed back to the Agillic System.

POST /apps/feedback/EMAIL=customer.email@agillic.com

When sending the request, the JSON body should contain:

The reportId is an internal id identifying the push notification in agillic system. This is received on the device as metadata.

The clientAppId is the id of the app which have been registered on the device. The feedback status is the actual status of the feedback. Possible values are OPENED / RECEIVED.

Example:

API Documentation