Introduction
Channels
Templates
Contacts
Messages
API
public
beta
Docs Contact Login

Contacts

All messages sent in Notifuse are tied to contacts. This way, you can see all the messages received by each one of your contacts.

Every contact has its own profile, where you can store some JSON data. This profile data is then available in your templates (i.e: Hello {{ firstName }}), and can be used to create Segments.

Reserved fields

To improve & anticipate the future cool Notifuse features, some profile fields are reserved or have a specific format to respect if you want to use them.

All profile fields are optional!
id forbidden string You cannot set this field by yourself. This field contains the contacts external ID.
firstName string First name of your contact. The firstName is displayed in the Notifuse UI.
lastName string Last name of your contact. The lastName is displayed in the Notifuse UI.
avatar string: URL URL of an image. The avatar is displayed in the Notifuse UI.
timeZone string: time zone name Time zone name defined in https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. The timeZone field is used by Notifuse when you want to schedule your messages at the time zone of your contacts.
language string: ISO 639-1 alpha2 Language code defined in ISO 639-1 alpha2 (two letters).
country string: ISO 3166-2 Country code defined in ISO 3166-2 (two uppercase letters).
latitude number Latitude of the location. required when you set the longitude. This field is used by Notifuse Segments to create a geolocation condition.
longitude number Longitude of the location. required when you set the latitude. This field is used by Notifuse Segments to create a geolocation condition.
address string Address of the location, displayed in the Notifuse UI. optional when you set the latitude+longitude.

The following fields are used by channels to route the messages:

email string: email Email address of your contact, used by email channels.
mobileNumber string Mobile phone number of your contact, used by SMS channels.
slackChannel string Slack channel name, without #.
webhookUrl string: URL URL used by webhooks channel.
twitterUsername string Twitter @username.
Reserved fields for the future also contain: hipchatRoom, apnsToken, gcmToken, mpnsUri, wnsToken, facebookId, facebookToken, ircChannel, ircId.

Date fields

Because the JSON format doesn't have a "date" type, and it's very important to store some dates in your profiles (often used when you create segments), Notifuse will interpret strings of a particular format (ISO 8601) as dates. Example:


  {
    "firstName": "John",
    "signupAt": "2016-06-17T04:42:25.922Z",
    "tags": ["customer", "vip"]
  }
  

Importing & updating contacts

You can initially import your CSV contacts list via the user interface, but it's recommended to implement the API in your app to keep it synced.

Via the API, there are 2 ways to sync your contacts, with contacts.upsert and while you send a message.

If your contact doesn't exist yet, it's inserted, otherwise it's updated!

The simple MongoDB query language has been implemented in the contacts.upsert endpoint to help you set and update your profiles fields.

Let's see an example with a JSON request to the API:


  {
    "contacts": [{
      "id": "1",

      "profile": {
        "$set": {
          "firstName": "John",
          "lastName": "Doe",
          "timeZone": "America/New_York",
          "email": "john@doe.com",
          "language": "en",
          "country": "US",
          "latitude": 40.7127837,
          "longitude": -74.0059413,
          "address": "New York, USA"
          "signupAt": "2016-06-17T04:42:25.922Z"
        },

        "$push": {
          "tags": "customer"
        },

        "$currenDate": {
          "lastLoginAt": true
        },

        "$inc": {
          "totalOrders": 1
        }
      },

      "createdAt": "2015-01-10T11:40:28.435Z"
    }]
  }
  

The contacts.upsert endpoint accepts an array of contacts, and each contact has an id (required), an optional profile and createdAt fields.

The id is yours, the one you use in your DB for this contact. The createdAt is the creation date that's gonna be used for your contact when it gets inserted for the first time in Notifuse.

As you can see in the above example, we set some fields on the profile (firstName, lastName...), add the "customer" value to an array of "tags", set the "lastLoginAt" to the current date and increment the "totalOrders" by 1.

Profile operators

Operators Expected value
$set Merge the provided JSON object with the current profile. If some fields already exist, they are overwritten with the new values.

  Syntax: 
  {
    "$set": {
      "firstName": "John"
    }
  }
            
$currentDate Set the value of a field to the current date.

  Syntax: 
  {
    "$currentDate": {
      "signupAt": true
    }
  }
            
$rename Rename the field names.

  Syntax: 
  {
    "$rename": {
      "field_to_rename": "new_name",
      "another_field_to_rename": "new_other_name"
    }
  }
            
$inc Increments a field by a specified value.

The $inc operator accepts positive and negative values.

If the field does not exist, $inc creates the field and sets the field to the specified value.

Use of the $inc operator on a field with a null value will generate an error.

$inc is an atomic operation within a single document.

  Syntax: 
  {
    "$inc": {
      "field_to_increment": 12.34,
      "another_field_to_decrement": -7
    }
  }
            
$unset Removes the fields. The value of the fields to remove should always be "".

  Syntax: 
  {
    "$unset": {
      "field_to_remove": "",
      "another_field_to_remove": ""
    }
  }
            
$push The $push operator appends a specified value to an array.

If the field is absent in the profile, $push adds the array field with the value as its element.

If the field is not an array, the operation will fail.

If the value is an array, $push appends the whole array as a single element. To add each element of the value separately, use the $each modifier with $push.

  Syntax: 
  {
    "$push": { 
      "my_array": "value_x",
      "my_other_array": { 
        "$each": [ "value_x", "value_y", "value_z" ]
      }
    }
  }
            
$addToSet A set is an array containing unique values (like tags). $addToSet is similar to $push, but adds the value to an array only if it's not yet present.

If the field is not an array, the operation will fail.

If the value is an array, $push appends the whole array as a single element. To add each element of the value separately, use the $each modifier with $push.

  Syntax: 
  {
    "$addToSet": { 
      "my_array": "value_x",
      "my_other_array": { 
        "$each": [ "value_x", "value_y", "value_z" ]
      }
    }
  }
            
$pop The $pop operator removes the first or last element of an array. Pass $pop a value of -1 to remove the first element of an array and 1 to remove the last element in an array.

  Syntax: 
  {
    "$pop": { 
      "my_array": 1,
      "my_other_array": -1
    }
  }
            
$pull The $pull operator removes from an existing array all instances of a value or values that match a specified condition.

We recommend you to read the MongoDB examples of $pull.

  Syntax: 
  {
    "$pull": { 
      "my_array": <value|condition>, 
      "my_other_array": <value|condition>
    }
  }
            
$pullAll The $pullAll operator removes all instances of the specified values from an existing array.

Unlike the $pull operator that removes elements by specifying a query, $pullAll removes elements that match the listed values.

We recommend you to read the MongoDB examples of $pullAll.

  Syntax: 
  {
    "$pull": { 
      "my_array": [ "value_x", "value_y" ... ],
      "my_other_array": [1, 2, 3 ... ]
    }
  }
            
$mul Multiply the value of a field by a number.

  Syntax: 
  {
    "$mul": { 
      "field_to_multiply": 1.25
    }
  }
            

Next: Segment your contacts ยป