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": , "my_other_array": } }`
$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 »