Introduction to Send API

The Send API allows you to send contents instantly to Engage Digital. Its purpose is to build a near realtime API when the third party to be connected can support it. This API is optional and is a way to mitigate the slow import (~2 min) of the polling approach.

It also allows you to mark agent contents as read, which is visible by agents when 'view.messaging' option is enabled.

Requirements

To use the send API, you must define what actions can be processed by Engage Digital. Use the polling method to define them in response of the implementation.info action (more information can be found here).

As with the polling method, the send API allows you to implement actions progressively.

Workflow

• Each time that we receive a call to the /realtime/sdk/:source_id endpoint we will look at the content of your query to determine that it's well prepared.
• The source_id url parameter must be filled with the Engage Digital source id that you target.
• For security reasons, the request body must always be signed as described here.
• The request body must be JSON encoded.

JSON Encoded Request Body

{
  "action": "messages.create",
  "params": {
    "id": "890",
    "actions": ["reply", "show", "list"],
    "author": {
      "id": "666",
      "created_at": "07/11/2019",
      "screenname": "John Doe"
    },
    "body": "Awesome post !",
    "format": "text",
    "thread_id": "42"
  }
}

• action and params keys are mandatory.
• action key defines the action that you want to perform on which resource type.
• params key content depends to the action and resource type.
• If the request runs smoothly, the response should be a HTTP 200 with ok as body. Otherwise consult the Errors section.

Actions

This section lists the parameters you must send for all actions and specifies what we return in the response.

Supported Actions

Create Example

Request

{
  "action": "messages.create",
  "params": {
    "id": "890",
    "author": {
      "id": "666",
      "created_at": "06/11/2017",
      "screenname": "John Doe"
    },
    "body": "Awesome post !",
    "thread_id": "42"
  }
}

Response

ok

Mark as read Example

Request

{
  "action": "status.mark_as_read",
  "params": {
    "id": "890"
  }
}

Response

ok

Typing Example

Request

{
  "action": "typing.start",
  "params": {
    "thread_id": "42",
    "in_reply_to_id": "890",
    "preview": "Hello world"
  }
}

{
  "action": "typing.stop",
  "params": {
    "thread_id": "42",
    "in_reply_to_id": "890"
  }
}

Response

ok

Errors

Rate Limits

typing.start requests are limited to 1 request / thread on Engage Digital every 2 seconds (receiving a typing.stop request for a thread will reset this 2 seconds timer).

Other than that there is no limit enforced as of right now.

Complete Examples

<?php

function sign_string($str) {
    $secret = '56e79ea426735090665b1c107c757d6d3a692c061335e4728899af27f215edf3'; // source access_token
    return hash_hmac('sha512', $str, $secret);
}

$content = [
'action' => 'messages.create',
    'params' => [
    'id' => '890',
        'author' => [
            'id' => '42',
            'created_at' => '06/11/2017',
            'screenname' => 'Alice'
            ],
        'body' => 'Nice post!',
        'thread_id' => '888'
    ]
];

$body = json_encode($content);
$signature = sign_string($body);
$source_id = '8da592bc6fcf8bae41b2';

$session = curl_init("https://yourdomain.engagement.dimelo.com/realtime/sdk/{$source_id}");
curl_setopt($session, CURLOPT_HTTPHEADER, ["X-SMCCSDK-SIGNATURE: {$signature}" ]);
curl_setopt($session, CURLOPT_POST, true);
curl_setopt($session, CURLOPT_POSTFIELDS, $body);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
$http_code = curl_getinfo($session, CURLINFO_HTTP_CODE);

echo "{$http_code}: {$response}\n";

?>

require 'faraday'
require 'openssl'
require 'json'

body = {
action: "messages.create",
params: {
    id: "890",
    author: {
    id: "42",
    created_at: "06/11/2017",
    screenname: "Alice"
    },
    body: "Nice post !",
    thread_id: "888"
}
}.to_json


access_token = '56e79ea426735090665b1c107c757d6d3a692c061335e4728899af27f215edf3' # source access_token
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA512.new, access_token, body)
source_id = '8da592bc6fcf8bae41b2' # source id
url = "https://yourdomain.engagement.dimelo.com/realtime/sdk/#{source_id}"

response = Faraday.new(url: url).post do |req|
req.body = body
req.headers['X-SMCCSDK-SIGNATURE'] = signature
end

puts "#{response.status}: #{response.body}"

• Last updated:
• Contributors