Our documentation is changing, please click here to enjoy it!
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
| |
body | Data Application |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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 |
---|---|---|
| Creates an application called "New application" |
Update an application
This API route allows you to update an existing application on Accengage.
Operations
|
|
Parameter | Model |
body | Data
Application |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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 certificate |
INACTIVE_CONVERT | Cannot convert the certificate |
INACTIVE_GATEWAY | Cannot connect to the gateway |
Examples
Request | Body | Description |
---|---|---|
| Updates the application with applicationID "124" |
Messages
Create message(s)
This API route allows you to create a message on Accengage.
Operations
|
|
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 | |
(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 | |
returnCode | Description |
| 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 |
16 | CampaignId and partner mismatch |
23 | No or bad template for buttons |
24 | No or bad button id |
25 | Bad custom params for buttons |
Examples
Request | Body | Description |
---|---|---|
| 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
|
|
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 (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 | |
returnCode | Description |
| 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 |
23 | No or bad template for buttons |
23 | No or bad button id |
25 | Bad custom params for buttons |
Examples
Request | Body | Description |
---|---|---|
| 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
|
|
Parameter | Model |
body | Data
Schedule |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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 |
---|---|---|
| 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
|
|
Parameter | Model |
body | Data Schedule |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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 |
---|---|---|
| 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
|
|
Parameter | Model |
body | Data Target |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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 |
---|---|---|
| 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
|
|
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
(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 | |
returnCode | Description |
| 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 |
22 | Invalid certificate |
23 | No or bad template for buttons |
24 | Nor or bad button id |
25 | 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 |
---|---|---|
| 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
|
|
Parameter | Model |
body | Data FieldValue Target Criterion |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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 |
---|---|---|
| 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
|
|
Parameter | Model |
body | Data |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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 |
---|---|---|
| Links the segment with segmentId 1234 with message with messageId 5678 | |
POST / | 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
|
|
Parameter | Model |
body | Data |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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 |
---|---|---|---|
| Deletes the segment with segmentId "226" |
Statistics
This API route allows you to collect message or campaign statistics on the Accengage solution.
Operations
|
|
Parameter | Model |
body | Data
(1) At least one of these values is mandatory (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 | |
returnCode | Description |
| 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 |
---|---|---|
| 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
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
|
|
Parameter | Model |
body | Data Image |
Response | |
---|---|
body | |
Return code | |
returnCode | Description |
| 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: |
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 |
---|---|---|---|
| Uploads a bigPicture image from a URL |