User

User is the recipient who can receive notifications from your app. You should use our API or front-end in-app library to create your user in Engagespot, so that Engagespot can deliver notifications to them.

Why Engagespot needs to identify your users?

When you use a third party service like Engagespot to build your multi-channel product notification infrastructure, we manage the delivery, store your user's notification preferences etc. So it is essential that you share your user's details like email, phone number etc to our system. We store your user's information in a highly secure and encrypted environment.

Structure of user data

Every user should have a unique identifier. It could be the auto-increment id from your database, or any other unique value such as their Email or Phone number.

info

The unique identifier you choose for the user should be unique across your entire application. It should never change.

Additional attributes

Along with the unique identifier, a user can have multiple attributes attached to their profile.This could be their Email id, phone number, FCM token, profile picture, name or anything.

Some channels requires certain attributes in the user's profile to work. For example, the SMS channel works only for users who have phoneNumber attribute set in their profile. To read more about profiles, and how to set them, read User Profile guide

Here are some of the attributes that is recommended for your users.

Attribute	Usage
firstName	You can use this field in your templates to personalise your notifications (Eg: Hey {{recipient.firstName}})
email	Used to deliver emails to the user. If you set your identifier itself as the email, then this property will be auto created.
phoneNumber	Used to deliver SMS and WhatsApp messages. Make sure to use the E.164 format

Creating your users in Engagespot

You can create users in Engagespot via multiple ways.

If you use Engagespot In-App Inbox library in your front-end app such as React, Angular, Vue or any other Javascript stack, the user will be created automatically (Except when secure mode is enabled).

Or else you can use the User REST API or client library to create users from your backend. This method is recommended.

NodeJS

import { EngagespotClient } from '@engagespot/node';

const client = EngagespotClient({
  apiKey: 'ENGAGESPOT_API_KEY',
  apiSecret: 'ENGAGESPOT_API_SECRET',
});

client.createOrUpdateUser('identifier', {
  email: 'xxx@xxx.com',
  phoneNumber: '+xxxxxxxxx',
});

PHP

use Engagespot\EngagespotClient;

$identifier = 'johndoe-001'; // your unique identifier
$profile = [
    'email' => 'johndoe@test.com',
];

$engagespot = new EngagespotClient($apiKey, $apiSecret);
$enagagespot->createOrUpdateUser($identifier, $profile);

Curl

curl --location --request PUT 'https://api.engagespot.co/v3/users/{identifier}' \
--header 'X-ENGAGESPOT-API-KEY: ENGAGESPOT_API_KEY' \
--header 'X-ENGAGESPOT-API-SECRET: ENGAGESPOT_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
"email":"xxx@xxx.com",
"phoneNumber":"+xxxxxxxxx"
}'

caution

If you try to send a notification to a user who is not created in Engagespot, it will be discarded.

Inline identification of users

Instead of creating the users beforehand, it is possible to create the users during a workflow trigger.

In the below example, the user johndoe001 gets created with email and phoneNumber profile attributes before the workflow is triggered.

Node

const { EngagespotClient } = require('@engagespot/node');
const client = EngagespotClient({
  apiKey: 'YOUR_ENGAGESPOT_API_KEY',
  apiSecret: 'YOUR_ENGAGESPOT_API_SECRET',
});

client.send({
  notification: {
    workflow: {
      identifier: 'welcomeMessage',
    },
  },
  sendTo: {
    recipients: [
      {
        identifier: 'johndoe001',
        email: 'johndoe001@gmail.com',
        phoneNumber: '+16020000000',
      },
    ],
  },
});

cURL

curl --location --request POST 'https://api.engagespot.co/v3/notifications' \
--header 'X-ENGAGESPOT-API-KEY: YOUR_ENGAGESPOT_API_KEY' \
--header 'X-ENGAGESPOT-API-SECRET: YOUR_ENGAGESPOT_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
    "notification": {
        "workflow": {
            "identifier": "<workflowIdentifier>"
        },
        "sendTo": {
            "recipients": [{
              "identifier":"johndoe001",
              "email": "johndoe001@gmail.com",
              "phoneNumber": "+16020000000",
            }]
        }
    }
}'

PHP

use Engagespot\\EngagespotClient;

  $engagespot = new EngagespotClient('ENGAGESPOT_API_KEY', 'ENGAGESPOT_SECRET_KEY');

  $notificationData = [
    'notification' => [
        'workflow' => [
           'identifier' =>'welcomeMessage'
        ],
    ],
    'sendTo' => [
      'recipients' => [
        'identifier': 'johndoe001',
        'email': 'johndoe001@gmail.com',
        'phoneNumber': '+16020000000',
      ],
    ],
  ];

$response = $engagespot->send($notificationData);

info

Make sure to supply the identifier properly during inline identification of users.