Introduction to Action Details
This page lists the parameters we send for all actions and specifies what we expect to receive in the response.
Although we don't show it here for brevity reasons, don't forget that all requests and responses must be signed and that you need to send a 2xx HTTP status code for it be considered successful.
Errors
Server errors
One thing that all actions have in common is the structure of the response in case of a failure. Sending any other HTTP status code than one in the 2xx range will mean an error occurred. It will also be helpful if you also write a short explanation in the body of the response.
Example error response:
HTTP/1.1 503 Service Unavailable
Optional message explaining the error
Resource errors
For any received message, you can return an error:
Response
{
"error": {
"fatal": false,
"message": "Unable to save message."
}
}
We'll always retry to send the message after a message level error. If you want to skip the content and stop the auto retry, set the fatal value to true.
Standard Actions
implementation.info
Request
{
"action": "implementation.info",
"time": "2012-10-01T17:18:40Z"
}
Response
{
"objects": {
"messages": ["create", "show", ...],
"private_messages": [...],
"threads": [...],
"status": ["mark_as_read"]
},
"options": ["messages.no_title", ...],
"locales": {
"default": {"custom_action": "Default name"},
"fr": {"custom_action": "Fr Name"}
}
}
create
Request
{
"action": "messages.create",
"params": {
"id": "1",
"body": "Hello world!",
...
}
}
Response
{
"id": "1",
"body": "Hello world!",
...
}
Please Note
Right now we'll try to create a content 3 times, if anything goes wrong, before giving up.
delete
Request
{
"action": "messages.delete",
"params": {
"id": "1"
}
}
Response
{
"id": "1",
"body": "Hello world!",
...
}
Please Note
Right now we'll try to destroy a content 3 times, if anything goes wrong, before giving up.
list
We will pass the id of the last previously imported content as the since_id parameter. This will allow you to only respond with the new messages. Please bear in mind that the first time we send the request we won't pass any since_id parameter (we don't have any previously imported content) and it will be your choice how many contents to send in that initial run.
If you are limiting the number of contents, you must return the oldest ones (but still after since_id) so we can then query for the following contents by giving you another since_id.
Results must be ordered in descending order. So we know which content is the last to give as since_id for the next calls (IDs are not necessarily ascending)
Request
{
"action": "messages.list",
"params": {
"since_id": "1"
}
}
Response
[
{
"id": "2",
"body": "Hello world!",
...
},
{
"id": "1",
"body": "Hello world!",
...
},
...
]
publish
Request
{
"action": "messages.publish",
"params": {
"id": "1"
}
}
Response
{
"id": "1",
"body": "Hello world!",
...
}
Please Note
Right now we'll try to publish a content 3 times, if anything goes wrong, before giving up.
show
Request
{
"action": "messages.show",
"params": {
"id": "1"
}
}
Response
{
"id": "1",
"body": "Hello world!",
...
}
unpublish
Request
{
"action": "messages.unpublish",
"params": {
"id": "1"
}
}
Response
{
"id": "1",
"body": "Hello world!",
...
}
Please Note
Right now we'll try to unpublish a content 3 times, if anything goes wrong, before giving up.
reply
The reply action is used internally into Engage Digital by displaying the reply button or not, if the call to implementation.info returns a reply action for a collection, then we can only reply to contents of that collection that also have reply in their own actions. You will never receive a request with that action.
Please Note
You don't need to implement reply action to reply to a content. You can create any message with the message.create action. Reply action is used to respond to a specific message.
messaging.queuing_update
The messaging.queuing_update action is sent by Engage Digital to notify you about queuing updates, it includes the estimated wait time (in seconds) and the position of the task in the queue.
In order to receive this action the task mode should be enabled and the corresponding channel (on Engage Digital) should be part of a channel group that is included in the current routing strategy.
Request
{
"action": "messaging.queuing_update",
"params": {
"estimated_wait_time": 30,
"position": 1,
"thread_id": "1",
"in_reply_to_id": "10"
}
}
Response
We're not expecting any specific response format for this request but the response code should be in the 2xx range.
Custom Actions
All non-standard actions will receive the same parameters: the content id and the id of the user who performed the action. The response will have to show the entire content so we can process all the changes that occured.
Request
{
"action": "messages.example",
"params": {
"id": "1",
"user_id": "1"
}
}
Response
{
"id": "1",
"body": "Hello world!",
...
}