API OLD

Introduction

This documentation was designed to enable developers to connect their applications with the Accengage API.

Most of the main features of the Accengage products are available within this API.

The API is hosted on https://apimobilecrm.accengage.com, and you need to use it like https://apimobilecrm.accengage.com /apiName.php .

Format

When querying the Accengage API, request bodies should comply to the JSON format (including the Content-Type: application/json header). Results are also returned in the JSON format.

All requests need two elements to ensure you have proper rights to access the API: a user and a partner, defined below.

User

Partner

Note that these objects are mandatory for accessing the API. They are denoted User and Partner in this documentation.

Response data handling

Upon finishing treatment, the server returns a JSON in the following format:

When returnCode is "0", the request is completed successfully. In this case, a status may be returned to indicate additional status information upon the request. Any other returnCode value indicates a failure in processing the request.

The returnLabel field corresponds to a user-friendly representation of the returnCode.

Additional data may be added to the response typically in the form of a resource ID.

Applications

Create an application

This API route allows you to create a new application on the Accengage solution.

Operations

Response
`POST`	`/createApplication.php`
body	Data Application
`body`
Return code
`returnCode`	Description
`0`	Application has been created
`1`	A database error occured
`2`	No createApplication
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad Application
`6`	Bad icon
`7`	Bad certificate or password
`8`	Application already exists
Status
`status`	Description
`ACTIVE`	Active certificate
`INACTIVE_CONVERT`	Cannot convert the certificate
`INACTIVE_GATEWAY`	Cannot connect to the gateway

Examples

Request	Body	Description
`POST /createApplication.php`		Creates an application called "New application"

Update an application

This API route allows you to update an existing application on Accengage.

Operations

Response
`POST`	`/updateApplication.php`
Parameter	Model
`body`	Data Application
`body`
Return code
`returnCode`	Description
`0`	Application has been updated
`1`	A database error occured
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad application
`6`	Bad icon
`7`	Bad certificate or password
`9`	No updateApplication field
`10`	Application does not exist
Status
`status`	Description
`ACTIVE`	Active certificate
`INACTIVE_CONVERT`	Cannot convert the certificate
`INACTIVE_GATEWAY`	Cannot connect to the gateway

Examples

Request	Body	Description
`POST /updateApplication.php`		Updates the application with applicationID "124"

Messages

Create message(s)

This API route allows you to create a message on Accengage.

Operations

Response
`POST`	`/createMessage.php`
Parameter	Model
`body`	Data Messages Message Popup CustomParam InteractiveButtons The value of the template can be found in the category on the interface or here for the Accengage's templates.
	Buttons
	_{⁽¹⁾ Only available for Android push messages} _{⁽²⁾ Only available for iOS push messages} _{⁽³⁾ The name of the image must be provided by the uploadImage API}
`body`
Return code
`returnCode`	Description
`0`	Message has been created
`1`	A database error occured
`2`	No createMessage
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad message
`6`	Bad custom params
`9`	No or bad appId
`13`	Cannot have message & messages
`14`	Bad message language code
`15`	External ID already exists
₁₆	CampaignId and partner mismatch
₂₃	No or bad template for buttons
₂₄	No or bad button id
₂₅	Bad custom params for buttons

Examples

Request Body Description

POST /createMessage.php

Create a message "Api test message" with a custom sound "test.wav" and badge "1", with a richpush in a webview and custom params, for campaign 123

POST /createMessage.php

Create several messages for different language IDs with the same externalId "externalName"

POST /createMessage.php

Create one message with interactive buttons

Update a message

This API route allows you to update an existing message on Accengage.

Operations

Response
`POST`	`/updateMessage.php`
Parameter	Model
`body`	Data Message InteractiveButtons The value of the template can be found in the category on the interface or here for the Accengage's templates. Buttons CustomParam _{⁽¹⁾ Only available for Android push messages} _{⁽²⁾ Only available for iOS push messages} _{⁽³⁾ The name of the image to fill in is provided by the uploadImage API}
`body`
Return code
`returnCode`	Description
`0`	Message updated successfully
`1`	A database error occured
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad message
`6`	Bad custom params
`7`	No updateMessage
`8`	Bad message ID
₂₃	No or bad template for buttons
₂₃	No or bad button id
₂₅	Bad custom params for buttons

Examples

Request Body Description

POST /updateMessage.php

Update the message with messageId "67"

Message schedules

Create a message schedule

This API route allows you to create a message schedule on Accengage.

Operations

Response
`POST`	`/createSchedule.php`
Parameter	Model
`body`	Data Schedule
`body`
Return code
`returnCode`	Description
`0`	Message schedule has been created
`1`	A database error occured
`2`	No createSchedule
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad Schedule
`6`	No or bad message ID
`7`	No or bad schedule type
`8`	No or bad schedule date
`9`	Bad timezone
`10`	Bad status

(1) The timeZone field must comply with the Wikipedia list of tz database time zones.

If the schedule has been created with the INACTIVE status, the messagge will never be launched.

Examples

Request	Body	Description
`POST /createSchedule.php`		Creates a schedule for the message with messageId "67"

Update a schedule

This API route allows you to update a message schedule on Accengage.

Operations

Response
`POST`	`/updateSchedule.php`
Parameter	Model
`body`	Data Schedule
`body`
Return code
`returnCode`	Description
`0`	Message schedule has been updated
`1`	A database error occured
`2`	No createSchedule
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad Schedule
`6`	No or bad message ID
`7`	No or bad schedule type
`8`	No or bad schedule date
`9`	Bad timezone
`10`	Bad status
`11`	No or bad schedule ID

(1) The timeZone field must comply with the Wikipedia list of tz database time zones.

If the schedule has been created with the INACTIVE status, the message will never be launched.

Examples

Request	Body	Description
`POST URL`		Updates the schedule with ID "2748"

Send messages

Send a message

This API route allows you to send an existing message to targets on Accengage.

Operations

Response
`POST`	`/sendMessage.php`
Parameter	Model
`body`	Data Target
`body`
Return code
`returnCode`	Description
`0`	Message has been sent
`1`	A database error occured
`2`	No sendMessage
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad message ID
`6`	Bad targets
`7`	Message limit exceeded

The deviceId field corresponds to unique device IDs you want to target, depending on the one used in the Accengage SDK. It is limited to 100 entries.

Please contact the Accengage team if you need to get access to another key in the database scheme, such as the user ID.

Examples

Request	Body	Description
`POST URL`		Sends the message with messageId "67"

Send an Instant Message

This API route allows you to send a new message to targets. This new message won't be visible on the Accengage interface but will be linked to an existing one (the "parent" message).

Operations

Response
`POST`	`/sendInstantMessage.php`
Parameter	Model
`body`	1) Sending on only one application (one partner) Data (send on 1 application) 2) Sending on multi applications (several partners) Data (send on multi applications) Messages Message Popup Target Criterion Content Aps InteractiveButtons The value of the template can be found in the category on the interface or here for the Accengage's templates. Buttons CustomParam _{⁽¹⁾ Only available for Android push messages} _{⁽²⁾ Only available for iOS push messages} _{⁽³⁾ The name of the image must be provided by the uploadImage API} _{⁽⁴⁾ Only available when targeting one application (not for multi-applications)} ^{⁽⁵⁾ Refer to the Apple documentation : https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html}
`body`
Return code
`returnCode`	Description
`0`	Instant Message has been sent
`1`	A database error occured
`2`	No sendInstantMessage
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad message
`6`	Bad custom params
`9`	Bad targets
`10`	No parent message ID
`11`	Message limit exceeded
`13`	Field unknown
`14`	Target max number exceeded
`15`	Template cannot be replaced
`16`	No or bad appId
`17`	The selected language does not exist
₂₂	Invalid certificate
₂₃	No or bad template for buttons
₂₄	Nor or bad button id
₂₅	Bad custom params for buttons

If the message has been sent (returnCode: 0) in the case of multiple partners, you will only get the

messageId of the last message that you have provided in the Messages array.

The targets array contains all target definition for the message(s). This array can contain up to 100 entries.

One target object can contain multiple criteria, so a device will be targeted if all the criteria match the device properties. In the example below, a device will only be targeted if its language property is set to "en" AND the user opened the application more than once.

If the actions of the buttons are directly set in your request, their value must be one of the following: browser, email, phone, store, sms, webView, urlSheme or close.

The message text can contain template macros. These templates will be replaced with, in order:

values set in API target data object
values set in API message data object
values set in the devices database

If no value is found, an error is triggered.

Examples

Request	Body	Description
`POST URL`	Exemple with one application Exemple with multi applications Exemple with interactive buttons	Sends an instant message

Users

Update users

This API route allows you to update user info / profiles in the Accengage database.

Operations

Response
`POST`	`/updateUser.php`
Parameter	Model
`body`	Data FieldValue Target Criterion
`body`
Return code
`returnCode`	Description
`0`	Update successful
`1`	A database error occured
`2`	Parse error
`3`	No updateUser field
`4`	No or bad user
`5`	No or bad partner
`6`	No or bad deviceId
`7`	No or bad field to update
`9`	No or bad targets, unknown field
`10`	No or bad targets, unknown operator or value
`11`	deviceId and targets defined together

Examples

Request	Body	Description
`POST /updateUser.php`		Updates a user
`POST /updateUser.php`		Updates a group of users; in this example, we target people with a language ID equal to "en" and deviceId equal to "765c8469b85e0a4e4656fdfb388ff3474c62c252", plus the specific deviceId "846c8469b85e0a4e4656fdfb388ff3474c62c908"

Segments

Link or unlink a segment to a message

This API route allows you to link or unlink a segment to a message.

Operations

Response
`POST`	`/linkSegment.php`
Parameter	Model
`body`	Data
`body`
Return code
`returnCode`	Description
`0`	OK
`1`	A database error occured
`2`	Bad request format
`3`	No or bad user
`4`	No or bad partner
`5`	No or bad messageId
`6`	No or bad segmentId
`7`	Segment already linked to the message
`8`	Unknown action

Examples

Request	Body	Description
`POST /linkSegment.php`		Links the segment with segmentId 1234 with message with messageId 5678
`POST /linkSegment.php`		Uninks the segment with segmentId 1234 with message with messageId 5678

Delete a segment

This API route allows you to delete a segment on Accengage.

Operations

Response
`POST`	`/deleteSegment.php`
Parameter	Model
`body`	Data
`body`
Return code
`returnCode`	Description
`0`	OK
`1`	Resource not found
`2`	No or bad segment
`3`	No or bad user
`4`	No or bad partner
`5`	Access denied
`6`	Cannot delete segment already used for a message

Examples

Request	Body	Response	Description
`POST /deleteSegment.php`			Deletes the segment with segmentId "226"

Statistics

This API route allows you to collect message or campaign statistics on the Accengage solution.

Operations

Response
`POST`	`/getStatistics.php`
Parameter	Model
`body`	Data _{⁽¹⁾ At least one of these values is mandatory ⁽²⁾ This feature is only available on demand} _{⁽³⁾ If neither a messageId nor a campaignId is provided, the maximum time interval is 3 days} _{⁽⁴⁾ This feature is mandatory for application using new statistics}
`body`	Statistic Message Stat (push notifications, automated messages, Facebook) Stat (in-app, in-site) Stat (local notifications)
Return code
`returnCode`	Description
`0`	No error
`1`	Request error
`2`	Bad message ID
`3`	No or bad user
`4`	No or bad partner
`5`	Bad campaign ID
`6`	Too many criteria, it must be messageId OR campaignId
`7`	Type cannot be campaign if messageId is set
`8`	endDate must be after startDate
`9`	Access denied
`10`	Bad type
`11`	Maximum 3 days of daily statistics without messageId or campaignId
`12`	Type must be campaign if campaignId is set
`13`	Cannot have daily criteria AND total criteria

If messageId is set, startDate and endDate are only used when daily or total keys are set to true.

If campaignId is set, startDate and endDate are only used when daily or total keys are set to true, or if the type is set to "message".

If daily or total are set to true, startDate and endDate are mandatory. If a campaignId is specified, type "message" is forbidden. Also, if no type is set, "campaign" type is the default value.

Request examples

Request	Body	Description
`POST /getStatistics.php`		Collects statistics for messages from a campaign with ID "261" between the 1^st of December 2013 and the 1^st of February 2014
`POST /getStatistics.php`		Collects statistics for messages from a campaign between the 22th January 2015 and the 29th of January 2015

Response examples

Request	Response	Description
`POST /getStatistics.php`		Response for one message
`POST /getStatistics.php`		Response for one campaign
`POST /getStatistics.php`		Response for all messages between `2013-12-01` and `2014-12-01`
`POST /getStatistics.php`		Response for `daily` statistics for message `2647` between `2014-06-08` and `2014-06-09`
`POST /getStatistics.php`		Response for `total` statistics for message `2647` between `2014-06-08` and `2014-06-09`

Uploads

Upload bigPicture or icon

This API route allows you to upload images from URL to use it in the createMessage or sendInstantMessage APIs. You can then use the bigPicture or icon in those APIs for Android notifications.

This API is only available for Android applications.

Operations

Response
`POST`	`/uploadImage.php`
Parameter	Model
`body`	Data Image
`body`
Return code
`returnCode`	Description
`0`	Image uploaded
`1`	A database error occured
`2`	Parse error
`3`	No `uploadedImage`
`4`	No or bad `user`
`5`	No or bad `partner`
`6`	No `image`, `type` or `url`
`7`	Bad image type
`8`	Cannot download image
`9`	Cannot copy image: `{error type}`
`10`	Not an Android application

Upon successful upload (i.e., returnCode == 0), the returnLabel field in the response will contain the resource name.

Examples

Request Body Response Description

POST /uploadImage.php

Uploads a bigPicture image from a URL

API OLD

Introduction

Format

Response data handling

Applications

Create an application

Operations

Examples

Update an application

Operations

Examples

Messages

Create message(s)

Operations

Examples

Update a message

Operations

Examples

Message schedules

Create a message schedule

Operations

Examples

Update a schedule

Operations

Examples

Send messages

Send a message

Operations

Examples

Send an Instant Message

Operations

Examples

Users

Update users

Operations

Examples

Segments

Link or unlink a segment to a message

Operations

Examples

Delete a segment

Operations

Examples

Statistics

Operations

Request examples

Response examples

Uploads

Upload bigPicture or icon

Operations

Examples

22 Child Pages