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 tab="PHP" "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:

``` json
{
    "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](https://developers.etrusted.com/etrusted-api.html#operation/get-event-type): ``` php tab="PHP" "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](https://developers.etrusted.com/etrusted-api.html#tag/Invite-Rules) via [`POST` method](https://developers.etrusted.com/etrusted-api.html#operation/post-invite-rule):

``` php tab="PHP"
<?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](https://developers.etrusted.com/etrusted-api.html#tag/Templates) via [`GET` method](https://developers.etrusted.com/etrusted-api.html#operation/getAllTemplates). `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](https://developers.etrusted.com/etrusted-api.html#operation/get-invite-rules), like so: ``` php tab="PHP" "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:

``` json
[
  {
    "_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](https://developers.etrusted.com/etrusted-api.html#operation/get-invite-rule). 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](https://developers.etrusted.com/etrusted-api.html#operation/get-invite-rules-by-channel) if you know the channel ID. Via `PUT` request you can activate and deactivate invite rules [account-wide](https://developers.etrusted.com/etrusted-api.html#operation/put-invite-rule) or [by channel ID](https://developers.etrusted.com/etrusted-api.html#operation/put-invite-rule-by-channel). ## Step: Call the Events API Call our [Events API](https://developers.etrusted.com/etrusted-api.html#tag/Events) via [`POST` method](https://developers.etrusted.com/etrusted-api.html#tag/Events/paths/~1events/post) and create an event for this event type: ``` php tab="PHP" "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:

``` json
{
    "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](https://developers.etrusted.com/etrusted-api.html#tag/Events/paths/~1events~1{eventRef}/get), using the event reference from your response: ``` php tab="PHP" "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*:

``` json
{
    "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"
}
!!! Info "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 tab="PHP" '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; } } ?>

1
2
3
4
```

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 tab="PHP" <?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:

``` json
{
  "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.