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!",
    ...
}

delete

Request

{
  "action": "messages.delete",
  "params": {
    "id": "1"
  }
}

Response

{
    "id": "1",
    "body": "Hello world!",
    ...
}

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!",
    ...
}

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!",
    ...
}

reply

The reply action is used internally into RingCX 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.

messaging.queuing_update

The messaging.queuing_update action is sent by RingCX 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 RingCX 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!",
    ...
}