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 correspondingContact()
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); });
- opts.create (boolean) – Whether to create a contact for the user if it does not yet exist.
Defaults to
-
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’smsisdn
attributeussd
: maps to the contact’smsisdn
attributegtalk
: maps to the contact’sgtalk_id
attributetwitter
: maps to the contact’stwitter_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
- name (string) – The name of the contact api method (for eg,
-
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 useContactStore.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.
-
static
-
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
- name (string) – The name of the group api method (for eg,
-
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.