From Touchpoint to Invite

On this page:

  • Learn about touchpoints, event types, invite rules, events and invites
  • Learn how to trigger events at touchpoints and how to automate review invites
  • Create an event via API call

Step: Touchpoints and Event Types

Picking one or more touchpoints is crucial in establishing the foundation of your experience feedback. Touchpoints are the hooks into your own system landscape from where you can automate your review collection process with eTrusted.

Each touchpoint along your customer journey can potentially trigger what we call an event. Such an event is a piece of information that is transferred from your system into eTrusted and that will trigger a review invite automatically. Technically, this transmission is a POST call against our Events API (see below).

For example, checkout marks the point in time when a customer finishes the purchase in a typical web shop. Thus, checkout is a touchpoint that occurs during that particular customer journey and makes for a reasonable event type.

Once you made your choice what kind of touchpoint you want to represent with an event type, create it via API call. For that, first retrieve an access token from our authentication service (see Setup and Authentication). Then call our Event Types API via POST method and create your event type:

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.etrusted.com/event-types",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>
  '{
    "active": true,
    "name": "my_new_event_type",
  }',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {access_token}",
    "Content-Type: application/json",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

If the POST call succeeded, you should have a response that looks like this:

{
    "id": "ety-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
    "createdAt": "2018-02-01T17:09:41.790Z",
    "updatedAt": "2018-02-01T17:09:41.790Z",
    "active": true,
    "name": "my_new_event_type"
}

You may verify that the event type was properly created by calling the API again via GET method:

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.etrusted.com/event-types/ety-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {access_token}",
    "Content-Type: application/json",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

If your response looks like the last response, your event type was properly persisted in eTrusted.

Step: Invite Rules

(templates)

When eTrusted receives events, a process chain is triggered that ultimately will send out a review invite to your customer automatically.

Invite rules control the conditions for sending out invites via eTrusted. For each event type, only one invite rule may be active. The rule defines a delay for sending out the invite as well as the transport type of its message (e.g. email).

Create a new invite rule with our Invite Rules API via POST method:

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.etrusted.com/invite-rules",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => '{
    "name": "my_new_invite_rule",
    "eventTypeRef": "ety-xxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
    "templateRef": "ivt-xxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
    "questionnaireTemplateRef": "qrt-xxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
    "sendingDelay": "P3D",
    "timeOfDay": "10:00:00Z",
    "active": true
  }',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {access_token}",
    "Content-Type: application/json",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Note

  • eventTypeRef should be the event type UUID from above
  • Get templateRef and questionnaireTemplateRef with another API call against our templates API via GET method. templateRef is the UUID of your INVITE template, while questionnaireTemplateRef is the UUID of your QUESTIONNAIRE template.
  • sendingDelay and timeOfDay are very important for the rule. As set above, they express a delay of three days and the invite will then be sent the next day at 10 am.

Once there are some invite rules, you can inspect them via API call. You can either fetch the entire list of invite rules for your account with an invite-rules GET call, like so:

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.etrusted.com/invite-rules",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {access_token}",
    "Content-Type: application/json",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

a sample response looks like this:

[
  {
    "_object": "checkout",
    "id": "evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
    "name": "checkout",
    "active": true,
    "rules": [
      {
        "_object": "InviteRule",
        "id": "irl-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
        "name": "Default checkout rule",
        "template": {
          "name": "Default template",
          "id": "ivt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
        },
        "questionnaireTemplate": {
          "name": "Default questionnaire template",
          "id": "qrt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
        },
        "sendingDelay": "P3D",
        "timeOfDay": "10:00:00Z",
        "createdAt": "2018-02-01T17:09:41.790Z",
        "updatedAt": "2018-02-01T17:09:41.790Z",
        "active": true,
        "default": true
      }
    ]
  }
]

Alternatively, if you already know the invite rule's ID, you can GET it via the ID. The response is similar but only contains a single invite rule object rather than a list.

You can also just GET all invite rules that are associated with one of your channels if you know the channel ID.

Via PUT request you can activate and deactivate invite rules account-wide or by channel ID.

Step: Call the Events API

Call our Events API via POST method and create an event for this event type:

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.etrusted.com/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>
  '{
    "type": "my_new_event_type",
    "customer": {
      "email": "customer.email@ddr.ess",
    },
    "channel": {
      "id": "{your_test_channel_id}",
      "type": "etrusted"
    },
    "transaction": {
      "reference": "order-12345",
    },
    "products": [
      {
        "name": "Your product",
        "sku": "1234-5678-9",
        "url": "example-url.com",
      }
    ],
    "system": "test_system",
    "systemVersion": "1.0",
  }',
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {access_token}",
    "Content-Type: application/json",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Note

The transaction, products and system are dummy data for now. A product is not mandatory, but is included for clarity reasons in this example.

Make sure that you replace {your_test_channel_id} and {access_token} with your data.

If the POST call succeeded, you should have a response that looks like this:

{
    "Message": "Your event (evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx) was accepted for processing",
    "EventRef": "evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
}

You may verify that your event was properly created by calling the Events API again via GET method, using the event reference from your response:

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.etrusted.com/events/evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {access_token}",
    "Content-Type: application/json",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

If your response looks like this, your event was properly persisted in eTrusted:

{
    "type": "my_new_event_type",
        "customer": {
        "email": "customer.email@ddr.ess"
    },
    "channel": {
        "id": "your_test_channel_id",
        "type": "etrusted"
    },
    "transaction": {
        "reference": "order-12345",
        "date": "2017-01-01T13:30:15.000Z"
    },
    "products": [
        {
            "name": "Your product",
            "sku": "1234-5678-9",
            "url": "example-url.com",
        }
    ],
    "system": "your_system_name",
    "systemVersion": "1.0"
}

I know how to call the events API, but I want to create a large number of events

Each Events POST call only creates a single event. In order to create many events at once, you need to create a loop manually.

Some sample code:

<?php
$touchpointsData = array(
    array(
        'transactionRef' => '123'
    ),
    array(
        'transactionRef' => '456'
    ),
    array(
        'transactionRef' => '789'
    )
);

foreach ($touchpointsData as $tp) {        
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.etrusted.com/events",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 30,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_POSTFIELDS =>
      '{
        "type": "my_new_event_type",
        "customer": {
          "email": "customer.email@ddr.ess",
        },
        "channel": {
          "id": "{your_test_channel_id}",
          "type": "etrusted"
        },
        "transaction": {
          "reference": $tp["transactionRef"],
        },
        "system": "test_system",
        "systemVersion": "1.0",
      }',
      CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer {access_token}",
        "Content-Type: application/json",
        "cache-control: no-cache"
      ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    }
}
?>

The example iterates over the $touchpointsData array that contains the reference IDs of three transactions. For each of these IDs, a separate Events POST call is generated in the $foreach loop.

Step: Check for Invites

Finally, make sure that eTrusted sent out your invite properly by calling our invites API via GET method:

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.etrusted.com/channels/{my_test_channel_id}/invites",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "cache-control: no-cache"
  ),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

If the call succeeded, you should have a response that looks like this:

{
  "totalElements": 1,
  "paging": {
    "count": 1,
    "cursor": {
      "before": "inv-xxxxxxxa-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
      "after": "inv-xxxxxxxb-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
    },
    "links": {
      "previous": "https://api.etrusted.com/channels/channelId/invites?count=10&before=inv-xxxxxxxa-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
      "next": "https://api.etrusted.com/channels/channelId/invites?count=10&after=inv-xxxxxxxb-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
    }
  },
  "items": [
    {
      "id": "inv-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
      "_object": "Invite",
      "mode": "AUTOMATIC",
      "accountRef": "{my_account_id}",
      "channelRef": "{my_test_channel_id}",
      "locale": "{my_channel_locale}",
      "customer": {
        "id": "cst-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phoneNumber": 442071838750,
        "preferredLocale": "en_GB",
        "consents": [
          {
            "purpose": "DATA_FORWARDING",
            "given": true
          }
        ]
      },
      "inviteSource": "CUSTOM",
      "transaction": {
        "id": "txn-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
        "reference": "order-12345",
        "date": "2018-01-04T12:09:50.722Z"
      },
      "scheduledAt": "2018-01-04T12:09:50.722Z",
      "template": {
        "id": "qrt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
        "name": "After Sales Standard EN"
      },
      "sender": {
        "name": "eTrusted",
        "email": "ex@mple.com"
      },
      "replyTo": {
        "name": "eTrusted",
        "email": "ex@mple.com"
      },
      "event": "evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
      "createdAt": "2018-02-01T17:09:41.790Z",
      "updatedAt": "2018-02-01T17:09:41.790Z",
      "sentAt": "2018-02-01T17:09:41.790Z",
      "status": {
        "name": "SCHEDULED",
      }
    }
  ]
}

If there are multiple invites in the response, find the correct invite e.g. via the event UUID.