Skip to end of metadata
Go to start of metadata

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

POST

/createApplication.php

body
Data
Application
Response
body
Return code
returnCodeDescription

0

Application has been created

1A database error occured
2

No createApplication

3No or bad user
4No or bad partner
5No or bad Application
6Bad icon
7Bad certificate or password
8Application already exists
Status
statusDescription
ACTIVEActive certificate
INACTIVE_CONVERT

Cannot convert the certificate

INACTIVE_GATEWAY

Cannot connect to the gateway

Examples

RequestBodyDescription

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

POST

/updateApplication.php

ParameterModel
body
Data

 


 

Application
Response
body
Return code
returnCodeDescription

0

Application has been updated

1A database error occured
3No or bad user
4No or bad partner
5No or bad application
6

Bad icon

7Bad certificate or password
9No updateApplication field
10Application does not exist
Status
statusDescription

ACTIVE

Active certificate
INACTIVE_CONVERTCannot convert the certificate
INACTIVE_GATEWAYCannot connect to the gateway

Examples

RequestBodyDescription

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

POST

/createMessage.php

ParameterModel
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
  

(1) Only available for Android push messages

(2) Only available for iOS push messages

(3) The name of the image must be provided by the uploadImage API

Response
body
Return code
returnCodeDescription

0

Message has been created

1A database error occured
2No createMessage
3No or bad user
4No or bad partner
5No or bad message
6Bad custom params
9No or bad appId
13Cannot have message & messages
14Bad message language code
15External ID already exists
16CampaignId and partner mismatch
23No or bad template for buttons
24No or bad button id
25Bad custom params for buttons

Examples

RequestBodyDescription

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

POST

/updateMessage.php

ParameterModel
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

(1) Only available for Android push messages

(2) Only available for iOS push messages

(3) The name of the image to fill in is provided by the uploadImage API

 

Response
body
Return code
returnCodeDescription

0

Message updated successfully

1A database error occured
3No or bad user
4No or bad partner
5No or bad message
6Bad custom params
7No updateMessage
8Bad message ID
23No or bad template for buttons
23No or bad button id
25Bad custom params for buttons

Examples

RequestBodyDescription

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

POST

/createSchedule.php

ParameterModel
body
Data

 

Schedule
Response
body
Return code
returnCodeDescription

0

Message schedule has been created

1A database error occured
2No createSchedule
3No or bad user
4No or bad partner
5No or bad Schedule
6No or bad message ID
7No or bad schedule type
8No or bad schedule date
9Bad timezone
10Bad 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

RequestBodyDescription

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

POST

/updateSchedule.php

ParameterModel
body
Data

Schedule
Response
body
Return code
returnCodeDescription

0

Message schedule has been updated

1A database error occured
2No createSchedule
3No or bad user
4No or bad partner
5No or bad Schedule
6No or bad message ID
7No or bad schedule type
8No or bad schedule date
9Bad timezone
10Bad status
11No 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

RequestBodyDescription

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

POST

/sendMessage.php

ParameterModel
body
Data

Target
Response
body
Return code
returnCodeDescription

0

Message has been sent

1A database error occured
2No sendMessage
3No or bad user
4No or bad partner
5No or bad message ID
6Bad targets
7Message 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

RequestBodyDescription

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

POST

/sendInstantMessage.php

ParameterModel
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

 

(1) Only available for Android push messages

(2) Only available for iOS push messages

(3) The name of the image must be provided by the uploadImage API

(4) Only available when targeting one application (not for multi-applications)

(5) Refer to the Apple documentation : https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html

 

Response
body
Return code
returnCodeDescription

0

Instant Message has been sent

1A database error occured
2No sendInstantMessage
3No or bad user
4No or bad partner
5No or bad message
6Bad custom params
9Bad targets
10No parent message ID
11Message limit exceeded
13Field unknown
14Target max number exceeded
15Template cannot be replaced
16No or bad appId
17The selected language does not exist

22

Invalid certificate
23No or bad template for buttons
24Nor or bad button id
25Bad 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

RequestBodyDescription

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

POST

/updateUser.php

ParameterModel
body
Data

FieldValue

Target

Criterion
Response
body
Return code
returnCodeDescription

0

Update successful

1A database error occured
2Parse error
3No updateUser field
4No or bad user
5No or bad partner
6No or bad deviceId
7No or bad field to update
9No or bad targets, unknown field
10No or bad targets, unknown operator or value
11deviceId and targets defined together

Examples

RequestBodyDescription

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

POST

/linkSegment.php

ParameterModel
body
Data
Response
body
Return code
returnCodeDescription

0

OK

1A database error occured
2Bad request format
3No or bad user
4No or bad partner
5No or bad messageId
6No or bad segmentId
7Segment already linked to the message
8Unknown action

Examples

RequestBodyDescription

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

POST

/deleteSegment.php

ParameterModel
body
Data
Response
body
Return code
returnCodeDescription

0

OK

1Resource not found
2No or bad segment
3No or bad user
4No or bad partner
5Access denied
6Cannot delete segment already used for a message

Examples

RequestBodyResponseDescription

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

POST

/getStatistics.php

ParameterModel
body
Data

 


 

(1) At least one of these values is mandatory
(2) This feature is only available on demand

(3) If neither a messageId nor a campaignId is provided, the maximum time interval is 3 days

(4) This feature is mandatory for application using new statistics

Response
body

 


 

Statistic

 


 

Message

 


 

Stat (push notifications, automated messages, Facebook)
Stat (in-app, in-site)
Stat (local notifications)
Return code
returnCodeDescription

0

No error

1Request error
2Bad message ID
3No or bad user
4No or bad partner
5Bad campaign ID
6Too many criteria, it must be messageId OR campaignId
7Type cannot be campaign if messageId is set
8endDate must be after startDate
9Access denied
10Bad type
11Maximum 3 days of daily statistics without messageId or campaignId
12Type must be campaign if campaignId is set
13Cannot 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

RequestBodyDescription

POST /getStatistics.php

Collects statistics for messages from a campaign with ID "261" between the 1st of December 2013 and the 1st 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

RequestResponseDescription
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

POST

/uploadImage.php

ParameterModel
body
Data

Image
Response
body
Return code
returnCodeDescription

0

Image uploaded

1A database error occured
2Parse error
3No uploadedImage
4No or bad user
5No or bad partner
6No image, type or url
7Bad image type
8Cannot download image
9

Cannot copy image: {error type}

10Not an Android application

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

Examples

RequestBodyResponseDescription

POST /uploadImage.php

 

Uploads a bigPicture image from a URL

  • No labels