Contacts

Contacts hold information about the users interacting with your application. While User() is used for short-term information about a user (usually information related to a particular interaction session), a Contact() holds long-term information.

class Contact(attrs)

Holds long-term information about a user interacting with the application.

Arguments:

• attrs.key (string) – A unique identifier for looking up the contact.
• attrs.user_account (string) – The name of the vumi go account that the contact is stored under.
• attrs.msisdn (string) – The contact’s msisdn.
• attrs.gtalk_id (string) – The contact’s gtalk address. Optional.
• attrs.facebook_id (string) – The contact’s facebook address. Optional.
• attrs.twitter_handle (string) – The contact’s twitter handle. Optional.
• attrs.name (string) – The contact’s name. Optional.
• attrs.surname (string) – The contact’s surname. Optional.
• attrs.extra (object) – A data object for additional, app-specific information about a contact. Both the keys and values need to be strings. Optional.
• attrs.extras-<name> (object) – An alternative way of specifying an extra. Optional.
• attrs.groups (array) – A list of keys, each belonging to a group that this contact is a member of. Optional.

static serialize()

Returns a deep copy of the contact’s attributes.

Contact.do.reset(attrs)

Resets a contact’s attributes to attrs. All the contact’s current attributes will be lost.

Arguments:

• attrs (object) – the attributes to reset the contact with.

Contact.do.validate()

Validates a contact, throwing a ValidationError() if one of its attributes are invalid.

ContactStore(im)

Provides ‘ORM-like’ access to the sandbox’s contacts resource, handling the raw contact resource api requests and allowing people to interact with their contacts as Contact() instances.

Arguments:

• im (InteractionMachine) – The interaction machine

static create(attrs)

Creates and adds a new contact, returning a corresponding Contact() via a promise.

Arguments:

• attrs (object) – The attributes to initialise the new contact with.

self.im.contacts.create({
    surname: 'Jones',
    extra: {location: 'CPT'}
}).then(function(contact) {
    console.log(contact instanceof Contact);
});

static for_user(opts)

Retrieves a contact for the the current user in the InteractionMachine(), returning a corresponding Contact() via a promise. If no contact exists for the user, a contact is created.

Arguments:

• opts.create (boolean) – Whether to create a contact for the user if it does not yet exist. Defaults to true.
• opts.delivery_class (string) – The delivery class corresponding to the current user’s address. If not specified, ContactStore() uses its fallback, ContactStore.delivery_class.

self.im.contacts.for_user().then(function(contact) {
    console.log(contact instanceof Contact);
});

static get(addr[, opts])

Retrieves a contact by its address for a particular delivery class, returning a corresponding Contact() via a promise.

Arguments:

• addr (boolean) – The address of the contact to be retrieved.
• opts.create (boolean) – Create the contact if it does not yet exist. Defaults to false.
• delivery_class (string) – The delivery class corresponding to the given address. If not specified, ContactStore() uses its fallback, ContactStore.delivery_class.

self.im.contacts.get('+27731234567').then(function(contact) {
    console.log(contact instanceof Contact);
});

The following delivery classes are supported:

• sms: maps to the contact’s msisdn attribute
• ussd: maps to the contact’s msisdn attribute
• gtalk: maps to the contact’s gtalk_id attribute
• twitter: maps to the contact’s twitter_handle attribute

static get(key)

Retrieves a contact by its key, returning a corresponding Contact() via a promise.

Arguments:

• key (string) – The contact’s key.

self.im.contacts.get('1234').then(function(contact) {
    console.log(contact instanceof Contact);
});

static request(name, cmd)

Makes raw requests to the api’s contact resource.

Arguments:

• name (string) – The name of the contact api method (for eg, 'get')
• cmd (object) – The request’s command data

static save(contact)

Saves the given contact to the store, returning a promise that is fulfilled once the operation completes.

Arguments:

• contact (Contact) – The contact to be saved

static search(query)

Searches for contacts matching the given Lucene search query, returning an array of the matching Contact() instances via a promise. Note that this can be a fairly heavy operation. If only the contact keys are needed, please use ContactStore.search_keys() instead.

Arguments:

• query (string) – The Lucene query to perform

self.im.contacts.search('name:"Moog"').then(function(contacts) {
    contacts.forEach(function(contact) {
        console.log(contact instanceof Contact);
    });
});

static search_keys(query)

Searches for contacts matching the given Lucene search query, returning an array of the contacts’ keys via a promise.

Arguments:

• query (string) – The Lucene query to perform

self.im.contacts.search_keys('name:"Moog"').then(function(keys) {
    keys.forEach(function(key) {
        console.log(typeof key == 'string');
    });
});

class Group(attrs)

Holds information about a group of contacts.

param string attrs.key:  a unique identifier for looking up the contact. param string attrs.user_account:  the name of the vumi go account that owns this group. param string attrs.name:  a human-readable name for the group. param string attrs.query:  the contact search query that determines the contacts in this group. Optional.

static serialize()

Returns a deep copy of the group’s attributes.

Group.do.reset(attrs)

Resets a groups’s attributes to attrs. All the groups’s current attributes will be lost.

Arguments:

• attrs (object) – the attributes to reset the group with.

Group.do.validate()

Validates a group, throwing a ValidationError() if one of its attributes are invalid.

GroupStore(im)

Provides ‘ORM-like’ access to the sandbox’s group resource, allowing people to interact with their groups as Group() instances.

Arguments:

• im (InteractionMachine) – The interaction machine

static get(name[, opts])

Retrieves a group by its name, returning a corresponding Group() via a promise.

Arguments:

• name (string) – The name of the group to retrieve.
• opts.create (boolean) – Create the group if it does not yet exist. Defaults to false.

self.im.groups.get('spammers').then(function(group) {
    console.log(group instanceof Group);
});

static get_by_key(key)

Retrieves a group by its key, returning a corresponding Group() via a promise.

Arguments:

• key (string) – The group’s key.

self.im.groups.get_by_key('1234').then(function(group) {
    console.log(group instanceof Group);
});

static list()

Returns a promise fulfilled with a list of the Group()‘s stored under the account associated with the app.

static request(name, cmd)

Makes raw requests to the api’s group resource.

Arguments:

• name (string) – The name of the group api method (for eg, 'get')
• cmd (object) – The request’s command data

static save(group)

Saves the given group to the store, returning a promise that is fulfilled once the operation completes.

Arguments:

• group (Group) – The group to be saved

static search(query)

Searches for groups matching the given Lucene search query, returning an array of the matching Group() instances via a promise.

Arguments:

• query (string) – The Lucene query to perform

self.im.groups.search('name:"spammers"').then(function(groups) {
    groups.forEach(function(group) {
        console.log(group instanceof Group);
    });
});

static setup()

Sets up the store.

static sizeOf(group)

Returns a promise fulfilled with the number of contacts that are members of the given group.

Arguments:

• group (Group) – The group who’s size needs to be determined.